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 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 estas muestras, se demuestra cómo configurar un SDK de OpenTelemetry en el 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 métricas y seguimientos en formato de protocolo OpenTelemetry (OTLP) a your Google Cloud project con la API de Telemetry y envían datos de registro con un Google Cloud exporter.

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. Las muestras configuran un framework de registro para escribir registros estructurados y configuran el recopilador de OpenTelemetry 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 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 con la API de Telemetry, que admite el formato OTLP.

En las muestras, se muestra cómo hacer lo siguiente:

1. Configurar 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. Configurar 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 your Google Cloud project. Otros servicios, como Compute Engine, requieren que instales un agente que analice y envíe tus registros. Para obtener información sobre los agentes que instalas, consulta Descripción general del agente de operaciones.

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

3. Configurar 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. La variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT, que se especifica en el servicio app, establece el extremo para el recopilador de OpenTelemetry.

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

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

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

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

   • 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 registro, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM:

  • Escritor de registros (roles/logging.logWriter) en tu proyecto
  • Escritor de métricas de Monitoring (roles/monitoring.metricWriter) en tu proyecto
  • Escritor de seguimientos de telemetría de Cloud (roles/telemetry.tracesWriter) en tu proyecto
  • Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) en tu proyecto de cuota

  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.

  Nota: Por lo general, las aplicaciones de producción dependen de una cuenta de servicio para proporcionar las credenciales necesarias para escribir datos de registro, métricas y seguimientos. En esos casos, otorga los roles anteriores a la cuenta de servicio.

• 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 mediante 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 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 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:

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

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

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

• Muestra de Go
• Muestra de Java
• Muestra de Node.js
• Muestra de Python