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

En este documento, se describe la estructura de las muestras de instrumentación que se proporcionan para los lenguajes Go, Java, Node.js y Python. Estas muestras proporcionan orientación sobre cómo instrumentar una aplicación para usar el SDK de OpenTelemetry y un recopilador de OpenTelemetry.

La instrumentación de estas muestras, que incluye el uso del SDK de OpenTelemetry y el exportador OTLP en proceso del SDK, es independiente del proveedor. El exportador en proceso envía telemetría al recopilador de OpenTelemetry, que recibe esos datos y, luego, los envía a tu Google Cloud proyecto. El recopilador contiene la vinculación a Google Cloud. Estas muestras usan Google Cloud exportadores para enviar datos de registros y métricas a tu proyecto. Sin embargo, envían datos de seguimiento a tu proyecto mediante la API de Telemetry.

Es posible que te interesen otras muestras que ilustren diferentes configuraciones:

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

    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 Google Cloud proyecto.

  • Correlaciona las métricas y los seguimientos con ejemplares 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.

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

Cómo funcionan las muestras

Las muestras de Go, Java, Node.js y Python usan el protocolo OpenTelemetry para recopilar datos de seguimiento y métricas. Las muestras configuran un framework de registro para escribir registros estructurados y el recopilador de OpenTelemetry está configurado para leer 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 Google Cloud recursos o en un entorno de desarrollo local.

Análisis en profundidad

Las muestras usan 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 Google Cloud proyecto. Las aplicaciones de muestra envían datos de métricas y seguimientos a tu proyecto mediante la API de Telemetry, que admite el formato OTLP.

En las muestras, 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, para Go, este paso configura la función main para llamar a una función que configura la recopilación de métricas y seguimientos. Para Go, también se actualizan 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 analizan registros estructurados y los envían a tu Google Cloud proyecto. Otros servicios, como Compute Engine, requieren que instales un agente, que analiza y envía tus registros. Para obtener información sobre los agentes que instalas, consulta Descripción general del agente de operaciones.

    No es necesario 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 OpenTelemetry:

      • Las muestras usan el receptor otlp para datos de métricas y seguimientos, y el receptor filelog para datos de registros.

      • Las muestras usan el otlphttp exportador para datos de métricas y seguimientos, y el Google Cloud exportador para datos de registros.

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

    • docker-compose.creds.yaml: De manera opcional, este archivo instala un Google Cloud archivo de credenciales en el otelcol contenedor. 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 muestra 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 el Cloud Shell, en Google Cloud recursos 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:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el serviceusage.services.enable permiso. Obtén más información para otorgar roles. 

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

¿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.