Se usó la API de Cloud Translation para traducir esta página.

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 proporcionadas para los lenguajes Go, Java, Node.js y Python. En estos ejemplos, se proporciona orientación sobre cómo instrumentar una aplicación para usar el SDK de OpenTelemetry y un recopilador de OpenTelemetry.

La instrumentación en estas muestras, que incluye el uso del SDK de OpenTelemetry y el exportador de OTLP integrado en el proceso del SDK, es independiente del proveedor. El exportador integrado en el proceso envía datos de telemetría al recopilador de OpenTelemetry, que recibe esos datos y, luego, los envía a tu proyecto de Google Cloud . El recopilador contiene la vinculación a Google Cloud.

Es posible que te interesen otros ejemplos que ilustran 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 integrado en el 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.

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 el recopilador de OpenTelemetry se configura 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 detallado

En los ejemplos, se usa el recopilador de OpenTelemetry como un sidecar para recibir y enriquecer la telemetría de la aplicación, que luego se envía a tu proyecto deGoogle Cloud con 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 a tu proyecto deGoogle Cloud con un comando de la API.

En los ejemplos, se muestra 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 idioma. Por ejemplo, para Go, este paso configura la función main para que llame a una función que configure la recopilación de métricas y registros. 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 hace que la carga útil del registro se formatee como un objeto JSON. En el caso de 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 extraen registros estructurados y los envían a tu proyecto de Google Cloud . Otros servicios, como Compute Engine, requieren que instales un agente que extrae 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 que instales 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 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 los datos de registro, métricas y seguimiento. 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 registros.
  
  En la sección exporters, se describe cómo se exportan los datos recopilados a un proyecto de Google Cloud . Para toda la telemetría, se utiliza un exportador Google Cloud . 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ía los datos transformados a tu proyectoGoogle Cloud con un comando de la API.
- docker-compose.creds.yaml: Este archivo puede, de manera opcional, montar 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 un archivo.

Permisos necesarios

Si ejecutas las muestras en Cloud Shell, en recursos Google Cloudo en un entorno de desarrollo local, los permisos que se indican en esta sección son suficientes. En el caso de las aplicaciones de producción, por lo general, una cuenta de servicio proporciona las credenciales para escribir datos de registros, métricas y seguimientos.

Para obtener los permisos que necesitas para que las aplicaciones de ejemplo escriban datos de registros, métricas y seguimiento, 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)
- Agente de Cloud Trace (roles/cloudtrace.agent)

Para obtener los permisos que necesitas para ver tus datos de registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
- Visor de registro (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

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

Consola de Google Cloud

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