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 recopilación 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 registro y métricas a tu proyecto. Sin embargo, envían datos de seguimiento atu 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 la transmisión 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 usar 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 detallado

Las muestras usan el recopilador de OpenTelemetry como un archivo adicional para recibir y enriquecer la telemetría de la aplicación, que luego se envía a tu Google Cloud proyecto mediante un Google Cloud exportador. El exportador convierte la telemetría en un formato compatible con la API de Cloud Trace, la API de Cloud Monitoring o la API de Cloud Logging. Luego, envían los datos transformados atu Google Cloud proyecto mediante la emisión de un comando de la API.

Las muestras muestran cómo hacer lo siguiente:

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

Si revisas las muestras, notarás que 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.
Configura un framework de registro para escribir registros estructurados.

Te recomendamos que tus aplicaciones escriban registros estructurados, lo que hace que la carga útil del registro se formatee 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 rastrean registros estructurados y los envían a tu Google Cloud proyecto. Otros servicios, como Compute Engine, requieren que instales un agente, que rastrea y envía tus registros. Si deseas 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.
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. Este recopilador especifica receptores, exportadores, procesadores y canalizaciones.
  
  El servicio telemetry define canalizaciones para datos de seguimiento, métricas y registros. Cada entrada de canalización especifica un receptor, un procesador y un exportador. Se usa el mismo receptor, otlp, para métricas y seguimientos.
  
  En la sección exporters, se describe cómo se exportan los datos recopilados a un Google Cloud proyecto. Para los datos de registro y métricas, Google Cloud se usan exportadores. Estos exportadores convierten la telemetría en un formato compatible con la API correspondiente y, luego, envían los datos transformados a tu Google Cloud proyecto mediante la emisión de un comando de la API. Por el contrario, los datos de seguimiento se envían atu proyecto mediante la API de Telemetry, que admite OTLP.
- docker-compose.creds.yaml: De manera opcional, este archivo instala un Google Cloud archivo de credenciales en el contenedor otelcol. Este archivo es necesario cuando se ejecuta 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 registro, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
- Escritor de registros (roles/logging.logWriter)
- Escritor de métricas de Monitoring (roles/monitoring.metricWriter)
- Escritor de seguimientos de telemetría de Cloud (roles/telemetry.tracesWriter)
Si ejecutas las muestras en Cloud Shell, en Google Cloud recursos, o en un entorno de desarrollo local, los permisos anteriores son suficientes para escribir datos de registro, métricas y seguimientos. Para las aplicaciones de producción, una cuenta de servicio suele proporcionar las credenciales necesarias.

Para obtener los permisos que necesitas para ver tus datos de registro, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
- Visor de registros (roles/logging.viewer)
- Visualizador de Monitoring (roles/monitoring.viewer)
- Usuario de Cloud Trace (roles/cloudtrace.user)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

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