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

Para mantener el código de tu aplicación independiente del proveedor mientras recopilas y envías datos de telemetría a Google Cloud, puedes usar las muestras de instrumentación basadas en el recopilador 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 local de OpenTelemetry que enruta tu telemetría a Google Cloud. Los ejemplos envían datos de métricas y de seguimiento en formato de OpenTelemetry Protocol (OTLP) a tu proyecto Google Cloud con la API de Telemetry y envían datos de registro con un exportador Google Cloud .

Cómo funcionan las muestras

Las muestras para Go, Java, Node.js y Python usan el protocolo 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 leer desde el flujo stdout de la aplicación. Para obtener recomendaciones sobre frameworks, 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 Cloudo en un entorno de desarrollo local.

Análisis en profundidad

Las muestras usan el recopilador de OpenTelemetry como un sidecar para recibir y enriquecer la telemetría de la aplicación, que un exportador luego envía a tu proyecto de Google Cloud . Las aplicaciones de ejemplo envían datos de métricas y de seguimiento a tu proyecto a través de la API de Telemetry, que admite el formato OTLP.

En los ejemplos, se muestra cómo realizar las siguientes acciones:

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

    La complejidad de este paso depende del idioma. 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.

    Te 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 recuperan registros estructurados y los envían a tu proyecto Google Cloud . Otros servicios, como Compute Engine, requieren que instales un agente que extrae y envía tus registros. Para obtener información sobre los agentes que instalas, consulta la Descripción general del Agente de operaciones.

    No es necesario que instales ningún agente para usar estas muestras.

  3. Configura los 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 de seguimiento, y el receptor filelog para los datos de registros.

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

        El exportador de otlphttp envía datos a tu proyecto con la API de Telemetry, que admite OTLP. El exportador Google Cloud convierte tus datos de registro en un formato compatible con la API de Cloud Logging y, luego, envía los datos transformados a tu proyectoGoogle Cloud .

    • docker-compose.creds.yaml: Este archivo puede, de manera opcional, montar un archivo de credenciales Google Clouden 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 alguna aún no está habilitada:

Roles necesarios para habilitar las APIs

Para habilitar 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 obtener este permiso 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 ilustren diferentes configuraciones:

  • 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 recopilador, 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.