Descripción general de las muestras de instrumentación

En este documento, se describe la estructura de las muestras de instrumentación proporcionadas para los lenguajes Go, Java, Node.js y Python. Estos ejemplos proporcionan orientación sobre cómo instrumentar una aplicación.

Es posible que te interesen otros ejemplos que ilustren diferentes configuraciones:

Cómo funcionan las muestras

Los ejemplos de 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 está configurado para leer desde el flujo stdout de la aplicación. Para obtener recomendaciones de 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 Cloud o en un entorno de desarrollo local.

Análisis detallado

En las muestras, se usa el OpenTelemetry Collector como un contenedor para recibir y enriquecer la telemetría de la aplicación, que luego se envía a tu proyecto de Google Cloud con un exportadorGoogle 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ían los datos transformados a tu proyecto de Google Cloud mediante la emisión de un comando de API.

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

  1. 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 llamar a una función que configura la recopilación de métricas y seguimientos. En 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, lo que hace que la carga útil del registro tenga el formato de un objeto JSON. Para estos registros, puedes construir 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 estos ejemplos.

  3. Configura los archivos de Docker. Todos los ejemplos contienen los siguientes archivos yaml:

    • docker-compose.yaml: Configura los servicios de la aplicación, el recopilador de OpenTelemetry y un generador de cargas. Por ejemplo, el servicio del recopilador de OpenTelemetry, otelcol, especifica una imagen, un volumen y variables de entorno. La variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT establece el extremo del recopilador de OpenTelemetry, que se especifica en el servicio app.

    • otel-collector-config.yaml: Configura los receptores, los exportadores, los procesadores y las canalizaciones.

      El servicio telemetry define canalizaciones para los datos de registro, métrica y seguimiento. Cada entrada de canalización especifica un receptor, un procesador y un exportador. Se usa el mismo receptor, otlp, para las métricas y los seguimientos.

      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 usa 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 proyecto de Google Cloud mediante la emisión de un comando de API.

    • docker-compose.creds.yaml: De manera opcional, este archivo activa 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 de 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 registro, métricas y seguimiento.

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.

Enable the APIs

Google Cloud CLI

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

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

¿Qué sigue?