Descripción general de las muestras de instrumentación basadas en recopiladores

Para mantener el código de la aplicación independiente del proveedor mientras recopilas y envías telemetría a Google Cloud, puedes usar las muestras de instrumentación basadas en recopiladores de OpenTelemetry para Go, Java, Node.js y Python.

En estos ejemplos, se muestra cómo configurar un SDK de OpenTelemetry en proceso para exportar métricas, registros y seguimientos a un recopilador de OpenTelemetry local que enruta tu telemetría a Google Cloud. Las muestras envían datos de registros, métricas y seguimientos en formato de protocolo de OpenTelemetry (OTLP) a tu proyecto de Google Cloud con la API de Telemetry.

Cómo funcionan las muestras

Las muestras de Go, Java, Node.js y Python usan el protocolo de OpenTelemetry para recopilar datos de seguimiento y métricas. En los ejemplos, se configura un framework de registro para escribir registros estructurados y se configura el recopilador de OpenTelemetry para que lea desde el flujo stdout de la aplicación. Para obtener recomendaciones sobre el framework, consulta Elige un enfoque de instrumentación.

Las aplicaciones se compilan y se implementan con Docker. No es necesario que uses Docker cuando instrumentas una aplicación con OpenTelemetry.

Puedes ejecutar las muestras en Cloud Shell, en recursos de Google Cloud o en un entorno de desarrollo local.

Análisis en profundidad

En los ejemplos, se usa el recopilador de OpenTelemetry como un archivo adicional para recibir y enriquecer la telemetría de la aplicación, que un exportador envía a tu proyecto de Google Cloud . Las muestras envían datos de registro, métricas y seguimientos a tu proyecto con la API de Telemetry, que admite el formato OTLP.

En los ejemplos, se muestra cómo hacer lo siguiente:

  1. Configura OpenTelemetry para recopilar métricas y seguimientos con el recopilador de OpenTelemetry.

    La complejidad de este paso depende del lenguaje. Por ejemplo, en Go, actualizas la función main para inicializar la recopilación de telemetría y configurar el servidor y el cliente HTTP.

  2. Configura un framework de registro para escribir registros estructurados.

    Recomendamos que tus aplicaciones escriban registros estructurados, que dan formato a la carga útil del registro como un objeto JSON. Para estos registros, puedes crear consultas que busquen rutas de acceso JSON específicas y puedes indexar campos específicos en la carga útil del registro.

    Algunos servicios, como Google Kubernetes Engine, tienen agentes integrados que extraen registros estructurados y los envían a tu proyecto de Google Cloud . Otros servicios, como Compute Engine, requieren que instales un agente, que recopila y envía tus registros. Para obtener información sobre los agentes que instalas, consulta Descripción general del Agente de operaciones.

    No necesitas instalar ningún agente para usar estas muestras.

  3. Configura archivos de Docker. Todas las muestras contienen los siguientes archivos YAML:

    • docker-compose.yaml: Configura los servicios para la aplicación, el recopilador de OpenTelemetry y un generador de carga. Por ejemplo, el servicio para el recopilador de OpenTelemetry, otelcol, especifica una imagen, un volumen y variables de entorno. El extremo del recopilador de OpenTelemetry se establece con la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT, que se especifica en el servicio app.

    • otel-collector-config.yaml: Configura el recopilador de OpenTelemetry:

      • En los ejemplos, se usa el receptor otlp para los datos de métricas y seguimientos, y el receptor filelog para los datos de registro.

      • En los ejemplos, se usa el exportador otlphttp para los datos de registros, métricas y seguimientos.

        El exportador otlphttp envía datos a tu proyecto con la API de Telemetry, que admite OTLP.

    • docker-compose.creds.yaml: De manera opcional, este archivo activa un archivo de credenciales de Google Cloud en el contenedor otelcol. Necesitas este archivo cuando ejecutas una muestra en una máquina local en la que las credenciales predeterminadas de la aplicación (ADC) solo están disponibles como un archivo.

Permisos necesarios

  • Para obtener los permisos que necesitas para que las aplicaciones de ejemplo escriban datos de registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM:

    Estos permisos son suficientes si ejecutas la muestra en Cloud Shell, en recursos de Google Cloud o en un entorno de desarrollo local. Para obtener información sobre cómo configurar un proyecto de cuota, consulta Configura el proyecto de cuota.

APIs requeridas

Habilita las APIs de Cloud Logging, Cloud Monitoring, Cloud Trace y Telemetry, si aún no están habilitadas:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles. 

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Enfoques de instrumentación alternativos

Es posible que te interesen otras muestras que ilustran diferentes parámetros de configuración:

  • En Migra del exportador de Trace al extremo de OTLP, se describe cómo usar la instrumentación en proceso para enviar datos de seguimiento directamente a tu proyecto de Google Cloud .

    Te recomendamos que uses un recopilador de OpenTelemetry para exportar tus datos de telemetría cuando tu entorno admita el uso de un recopilador. Si no puedes usar un recolector, debes usar un exportador en proceso que envíe datos directamente a tu proyecto de Google Cloud .

  • En Correlaciona las métricas y los seguimientos con ejemplares, se describe cómo configurar una aplicación de Go para generar ejemplares. Un ejemplar es un dato de ejemplo adjunto a un dato de métrica. Puedes usar ejemplares para correlacionar tus datos de seguimiento y métricas.

  • En Usa el Agente de operaciones y el protocolo OpenTelemetry (OTLP), se describe cómo puedes configurar el Agente de operaciones y un receptor de OTLP para recopilar métricas y seguimientos de una aplicación.

¿Qué sigue?

Para obtener más información sobre los recopiladores, consulta Recopilador de OpenTelemetry integrado en Google.

Explora las muestras que usan exportaciones basadas en recopiladores.