Esta página se ha traducido con Cloud Translation API.

Información general sobre ejemplos de instrumentación basada en recopiladores

En este documento se describe la estructura de las muestras de instrumentación proporcionadas para los lenguajes Go, Java, Node.js y Python. Estas muestras ofrecen orientación sobre cómo instrumentar una aplicación para usar el SDK de OpenTelemetry y un recolector 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 la telemetría al recopilador de OpenTelemetry, que recibe esos datos y, a continuación, los envía a tu Google Cloud proyecto. El recolector contiene la vinculación a Google Cloud.

Puede que te interesen otros ejemplos que ilustren diferentes configuraciones:

En el artículo Migrar del exportador de trazas al endpoint OTLP se describe cómo usar la instrumentación en proceso para enviar datos de trazas directamente a tu proyecto de Google Cloud .

Te recomendamos que uses un recolector de OpenTelemetry para exportar tus datos de telemetría cuando tu entorno admita el uso de un recolector. Si no puedes usar un colector, debes usar un exportador en proceso que envíe datos directamente a tu proyecto de Google Cloud .
En Correlacionar métricas y trazas mediante ejemplares se describe cómo configurar una aplicación Go para generar ejemplares. Un ejemplar es un punto de datos de ejemplo asociado a un punto de datos de una métrica. Puedes usar ejemplares para correlacionar tus datos de traza y métricas.
En Usar el agente de operaciones y el protocolo OpenTelemetry (OTLP) se describe cómo puedes configurar el agente de operaciones y un receptor OTLP para recoger métricas y trazas de una aplicación.

Cómo funcionan las muestras

Los ejemplos de Go, Java, Node.js y Python usan el protocolo OpenTelemetry para recoger datos de trazas y métricas. Los ejemplos configuran un framework de registro para escribir registros estructurados y el recolector de OpenTelemetry se configura para leer del flujo stdout de la aplicación. Para ver recomendaciones sobre frameworks, consulta Elegir un método de instrumentación.

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

Puedes ejecutar los ejemplos en Cloud Shell, en recursos de Google Cloud o en un entorno de desarrollo local.

Información detallada

Los ejemplos usan OpenTelemetry Collector como sidecar para recibir y enriquecer la telemetría de la aplicación, que se envía a tuGoogle Cloud proyecto mediante un Google Cloud exportador. El exportador convierte la telemetría a un formato compatible con la API de Cloud Trace, la API de Cloud Monitoring o la API de Cloud Logging. A continuación, envían los datos transformados a tu proyectoGoogle Cloud mediante un comando de la API.

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

Configura OpenTelemetry para recoger métricas y trazas mediante el colector de OpenTelemetry.

Si revisas las muestras, verás que la complejidad de este paso depende del idioma. Por ejemplo, en Go, este paso configura la función main para que llame a una función que configure la recogida de métricas y trazas. En el caso de 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 hará que la carga útil del registro se formatee como un objeto JSON. En estos registros, puede crear consultas que busquen rutas JSON específicas e indexar campos concretos en la carga útil del registro.

Algunos servicios, como Google Kubernetes Engine, tienen agentes integrados que recogen registros estructurados y los envían a tu Google Cloud proyecto. Otros servicios, como Compute Engine, requieren que instales un agente que rastree y envíe tus registros. Si quieres obtener información sobre los agentes que instalas, consulta el artículo Información general sobre el Agente de operaciones.

No es necesario instalar ningún agente para usar estas muestras.
Configura los archivos de Docker. Todas las muestras contienen los siguientes archivos YAML:
- docker-compose.yaml: configura los servicios de la aplicación, el colector OpenTelemetry y un generador de carga. Por ejemplo, el servicio del recolector OpenTelemetry, otelcol, especifica una imagen, un volumen y variables de entorno. El endpoint del recolector de OpenTelemetry se define mediante la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT, que se especifica en el servicio app.
- otel-collector-config.yaml: configura el recolector de OpenTelemetry. Este collector especifica receptores, exportadores, procesadores y canalizaciones.
  
  El servicio telemetry define las canalizaciones de datos de trazas, métricas y registros. Cada entrada de la canalización especifica un receptor, un procesador y un exportador. El mismo receptor, otlp, se usa para las métricas y los rastreos.
  
  En la sección exporters se describe cómo se exportan los datos recogidos a un Google Cloud proyecto. Para toda la telemetría, se utiliza un exportador Google Cloud . El exportador convierte la telemetría en un formato compatible con la API Cloud Trace, la API Cloud Monitoring o la API Cloud Logging. A continuación, envía los datos transformados a tuGoogle Cloud proyecto mediante un comando de la API.
- docker-compose.creds.yaml: este archivo monta de forma opcional un archivo de credencialesGoogle Cloud 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 archivo.

Permisos obligatorios

Si ejecutas los ejemplos en Cloud Shell, en Google Cloud recursos o en un entorno de desarrollo local, los permisos que se indican en esta sección son suficientes. En las aplicaciones de producción, normalmente una cuenta de servicio proporciona las credenciales para escribir datos de registro, métricas y trazas.

Para obtener los permisos que necesitas para que las aplicaciones de ejemplo escriban datos de registro, métricas y trazas, pide a tu administrador que te conceda los siguientes roles de IAM en tu proyecto:
- Escritor de registros (roles/logging.logWriter)
- Editor de las métricas de monitorización (roles/monitoring.metricWriter)
- Agente de Cloud Trace (roles/cloudtrace.agent)

Para obtener los permisos que necesitas para ver tus datos de registro, métricas y trazas, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:
- Visualizador de registros (roles/logging.viewer)
- Lector de monitorización (roles/monitoring.viewer)
- Usuario de Cloud Trace (roles/cloudtrace.user)
Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

API obligatorias

A continuación, se proporciona información sobre las APIs necesarias para enviar datos de telemetría a un proyecto de Google Cloud :

Google Cloud console

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Google Cloud CLI