Elige un enfoque de instrumentación

Puedes elegir el enfoque de instrumentación más eficaz para tu aplicación según tu Google Cloud plataforma de procesamiento y los requisitos de telemetría. En esta guía, se proporcionan recomendaciones para Google Kubernetes Engine (GKE), Compute Engine y Cloud Run, lo que te ayuda a decidir entre el recopilador de OpenTelemetry integrado en Google, el agente de operaciones y la exportación directa de OpenTelemetry en el proceso.

En este documento, se proporcionan recomendaciones generales, así como orientación para las siguientes plataformas:

• GKE
• Compute Engine
• Cloud Run
• Funciones de Cloud Run
• App Engine

Para obtener aplicaciones de muestra, consulta Guías de implementación y ejemplos.

Las recomendaciones de esta página no son las únicas soluciones, y otros enfoques pueden funcionar. Para obtener orientación adicional, comunícate con Atención al cliente de Cloud.

Recomendaciones generales

En esta sección, se incluyen recomendaciones generales sobre cómo instrumentar tu aplicación. Para obtener orientación específica de la plataforma, consulta Recomendaciones de la plataforma.

• Datos de registro: Te recomendamos que uses un framework que se pueda configurar para generar registros estructurados en JSON para Cloud Logging. Para escribir datos de registro, te recomendamos lo siguiente:

  • Go: slog.
  • Python: logging.
  • JavaScript: Pino.
  • Java: SLF4J con Log4j2.

• Datos de métricas: Te recomendamos que uses OpenTelemetry o las bibliotecas cliente de Prometheus:

  • OpenTelemetry proporciona un framework de código abierto independiente del proveedor y bibliotecas cliente para instrumentar aplicaciones para métricas.
  • Las bibliotecas cliente de Prometheus (Go, Java, Python, etc.) generan métricas que se pueden exponer en un extremo HTTP y que un agente puede recopilar.

• Datos de seguimiento: Te recomendamos que uses OpenTelemetry para generar datos de seguimiento distribuidos desde el código de la aplicación.

Arquitecturas de recopilación de OpenTelemetry

Cuando instrumentas una aplicación con bibliotecas de OpenTelemetry, puedes enrutar la telemetría a través del recopilador de OpenTelemetry independiente o exportar directamente desde el proceso de tu aplicación. El archivo de configuración del recopilador de OpenTelemetry controla cómo el recopilador recibe, procesa y exporta la telemetría. En general, te recomendamos que los recopiladores reciban y exporten telemetría con el protocolo OpenTelemetry (OTLP). La API de Telemetry (OTLP) implementa este protocolo.

Existen dos enfoques fundamentales para enviar telemetría a tu Google Cloud proyecto:

• Exportación basada en recopiladores (independiente del proveedor): Instrumentas el código de tu aplicación con el SDK de OpenTelemetry y usas el exportador de OTLP en el proceso para enviar datos a un recopilador de OpenTelemetry, como el recopilador de OpenTelemetry integrado en Google o un receptor del agente de operaciones. El recopilador recibe la telemetría y la reenvía a tu Google Cloud proyecto. El código de tu aplicación sigue siendo completamente independiente del proveedor.

• Exportación directa (específica del proveedor): Instrumentas el código de tu aplicación con el SDK de OpenTelemetry y configuras OpenTelemetry para enviar telemetría a tu proyecto con la API de Telemetry. No necesitas implementar un recopilador, pero el código de la aplicación incluye dependencias específicas del proveedor.

Te recomendamos que uses un recopilador de OpenTelemetry cuando tu entorno de procesamiento admita uno. Para los entornos en los que no es práctico ejecutar un proceso de recopilador independiente, usa la exportación directa en el proceso.

Recomendaciones de la plataforma

Debido a que Google Cloud los entornos de procesamiento tienen diferentes capacidades de ciclo de vida y de sidecar, el patrón de recopilación óptimo varía según la plataforma. En las siguientes secciones, se proporcionan recomendaciones específicas para tu entorno de implementación.

GKE

Para obtener información general sobre GKE, consulta la Descripción general de GKE.

Tipo	Recomendación
Métricas	Te recomendamos usar Google Cloud Managed Service para Prometheus. Para la instrumentación, realiza una de las siguientes acciones: Usa las bibliotecas cliente de Prometheus . Si usas este enfoque, también te recomendamos que uses la recopilación administrada, que incluye instrucciones de instalación de exportador en copia y pegado para aplicaciones comunes. Usa las bibliotecas de OpenTelemetry y el recopilador de OpenTelemetry: Implementa el recopilador de OpenTelemetry integrado en Google en Google Kubernetes Engine. Usa el SDK de OpenTelemetry y el exportador de OTLP para tu lenguaje. El recopilador recibe datos de métricas del exportador de OTLP en el proceso del SDK, procesa esos datos y, luego, los exporta. Asegúrate de configurar el recopilador para exportar datos de métricas a Managed Service para Prometheus. Para obtener más información, consulta Comienza a usar el recopilador de OpenTelemetry.
Seguimiento	Haz lo siguiente: Implementa el recopilador de OpenTelemetry integrado en Google en Google Kubernetes Engine. El recopilador recibe datos de seguimiento del exportador de OTLP en el proceso del SDK procesa esos datos y, luego, los envía a tu Google Cloud proyecto con la API de Telemetry (OTLP). Usa el SDK de OpenTelemetry y el exportador de OTLP para tu lenguaje.
Registros	Configura la app para que genere registros estructurados en JSON en stdout y stderr. Para obtener una lista de frameworks, consulta frameworks de registro recomendados. GKE recopila los registros escritos en stdout y stderr de forma automática. Para obtener más información, consulta Acerca de los registros de GKE.

Compute Engine

Para obtener información general sobre Compute Engine, consulta Instancias de máquina virtual.

Tipo	Recomendación
Métricas y seguimientos	Haz lo siguiente: Usar el agente de operaciones para recopilar métricas y seguimientos Para ver un ejemplo, consulta Recopila métricas y seguimientos del protocolo OpenTelemetry (OTLP). En esta guía, se describe cómo configurar el agente de operaciones para recibir datos de métricas y seguimientos de los exportadores de OTLP en el proceso del SDK, transformar esos datos, y, luego, enviarlos a tu Google Cloud proyecto. Los datos de métricas se envían con la API de Cloud Monitoring, y los datos de seguimiento se envían con la API de Cloud Trace. Usa el SDK de OpenTelemetry y el exportador de OTLP para tu lenguaje. Como alternativa, si solo deseas configurar la recopilación de métricas de formato Prometheus, usa el receptor de Prometheus del agente de operaciones para recopilar métricas instrumentadas con bibliotecas cliente de Prometheus o el SDK de OpenTelemetry.
Registros	Puedes hacer lo siguiente: Configura tu aplicación para que envíe registros estructurados JSON a un archivo. Para obtener una lista de frameworks, consulta frameworks de registro recomendados. Instalar el agente de operaciones y configurar un receptor. Para ver un ejemplo, consulta Receptores de registros.

Cloud Run

Para obtener información general sobre Cloud Run, consulta Qué es Cloud Run.

Tipo	Recomendación
Métricas y seguimientos	Puedes hacer lo siguiente: Usa el SDK de OpenTelemetry y el exportador de OTLP para tu lenguaje. Implementa un sidecar de OpenTelemetry para recopilar métricas y seguimientos. Para ver ejemplos, consulta los siguientes documentos: Escribe métricas de OTLP mediante un archivo adicional de OpenTelemetry. Implementa el recopilador de OpenTelemetry integrado en Google en Cloud Run. El recopilador recibe datos de registro, métricas y seguimientos de los exportadores de OTLP en el proceso del SDK y, luego, transforma los datos recibidos. A continuación, exporta los datos de métricas con el googlemanagedprometheus exportador y exporta los datos de registro y métricas con Google Cloud exportadores. Para tu servicio de Cloud Run, usa la facturación basada en instancias. Con la facturación basada en instancias, la CPU se asigna durante todo el ciclo de vida de la instancia, lo que es necesario porque la instrumentación de OpenTelemetry realiza el procesamiento en segundo plano. Para obtener más información, consulta Parámetros de configuración de facturación para servicios de Cloud Run. Como alternativa, si solo deseas configurar la recopilación de métricas de formato Prometheus, usa el sidecar de Prometheus para Cloud Run para recopilar métricas instrumentadas con bibliotecas cliente de Prometheus o el SDK de OpenTelemetry.
Registros	Configura la app para que genere registros estructurados en JSON en stdout y stderr. Para obtener una lista de frameworks, consulta frameworks de registro recomendados. Cloud Run recopila los registros escritos en stdout y stderr de forma automática. Para obtener más información, consulta Escribe registros de contenedores.

Funciones de Cloud Run

Para obtener información general sobre las funciones de Cloud Run, consulta Descripción general de las funciones de Cloud Run.

Tipo	Recomendación
Métricas	La escritura directa de datos de métricas no es compatible con las funciones de Cloud Run. Puedes generar métricas basadas en registros.
Seguimiento	Usa el SDK de OpenTelemetry y el exportador de Cloud Trace para tu lenguaje.
Registros	Configura la app para que genere registros estructurados en JSON en stdout y stderr. Para obtener una lista de frameworks, consulta frameworks de registro recomendados. Las funciones de Cloud Run recopilan los registros escritos en stdout y stderr de forma automática. Para obtener más información, consulta Funciones de Cloud Run: Supervisión y descripción general del registro.

App Engine

Para obtener información general sobre App Engine, consulta Descripción general de App Engine.

Tipo	Recomendación
Métricas	Usa el SDK de OpenTelemetry y el exportador de Cloud Monitoring para tu lenguaje.
Seguimiento	Usa el SDK de OpenTelemetry y el exportador de Cloud Trace para tu lenguaje.
Registros	Configura la app para que genere registros estructurados en JSON en stdout y stderr. Para obtener una lista de frameworks, consulta frameworks de registro recomendados. App Engine recopila los registros escritos en stdout y stderr de forma automática. Para obtener más información, consulta Escribe y visualiza registros.

Guías de implementación y ejemplos

• En Descripción general de la muestra, se describe la arquitectura y los roles de Identity and Access Management necesarios para los siguientes ejemplos de código basados en recopiladores:

  • Go
  • Java
  • Node.js
  • Python

• En Migra del exportador de Trace al extremo de OTLP , se describe cómo actualizar una aplicación que usa la exportación directa para enviar datos de seguimiento con formato OTLP.

• En Instrumenta aplicaciones de IA generativa, se describe cómo instrumentar o habilitar agentes de IA generativa compilados con LangGraph o el framework del kit de desarrollo de agentes (ADK).

Documentación de OpenTelemetry

En esta sección, se proporcionan vínculos al SDK de OpenTelemetry y los exportadores de OTLP, Cloud Trace y Cloud Monitoring.

Referencias generales:

• APIs y SDK de lenguaje
• Exportador de OTLP

Go

• SDK de Go
• Exportador de OTLP de Go
• Exportador de Cloud Trace de Go
• Exportador de Cloud Monitoring de Go

Java

• SDK de Java
• Exportador de OTLP de Java
• Exportador de Cloud Trace de Java
• Exportador de Cloud Monitoring de Java

JavaScript

• SDK de JavaScript
• Exportador de OTLP de JavaScript
• Exportador de Cloud Trace de JavaScript
• Exportador de Cloud Monitoring de JavaScript

Python

• Python SDK
• Exportador de OTLP de Python
• Exportador de Cloud Trace de Python
• Exportador de Cloud Monitoring de Python