Habilita los indicadores de telemetría en las bibliotecas cliente de Cloud para Java

Google Cloud proporciona servicios potentes de supervisión, registro y diagnóstico para las aplicaciones de Java.

Las bibliotecas cliente de Java están instrumentadas para emitir datos de registro, métricas y seguimientos. La instrumentación es opcional, por lo que debes habilitarla de forma explícita. En este documento, se describen los indicadores disponibles y cómo habilitarlos.

Indicadores disponibles

Los indicadores dorados incluyen los siguientes datos de telemetría, que cumplen con las convenciones semánticas de OpenTelemetry:

• Seguimientos: Seguimientos de HTTP/gRPC de bajo nivel que representan las solicitudes de red que realizan las bibliotecas cliente.
• Métricas: Métricas de solicitudes de cliente, que hacen un seguimiento de la latencia y las tasas de solicitudes. La métrica principal es gcp.client.request.duration.
• Registros: Registros de errores procesables en el nivel DEBUG, que proporcionan detalles de las solicitudes fallidas en la capa de transporte, incluso si, finalmente, se vuelven a intentar de forma correcta.

Los indicadores incluyen atributos estándares de OpenTelemetry (por ejemplo, http.response.status_code y rpc.system.name) y Google Cloud-específicos atributos personalizados, que pueden incluir estos y atributos similares:

• gcp.client.service: El nombre del servicio (por ejemplo, pubsub o storage).
• gcp.client.repo: El repositorio de la biblioteca cliente (por ejemplo, googleapis/google-cloud-java).
• gcp.client.version: La versión de la biblioteca cliente.
• gcp.client.artifact: La ruta de acceso específica del módulo (por ejemplo, com.google.cloud:google-cloud-secretmanager).
• gcp.resource.destination.id: El ID del recurso sobre el que se actúa.
• gcp.errors.domain: El dominio de error para los registros de errores procesables.
• gcp.errors.metadata.<key>: Claves de metadatos de error adicionales para las solicitudes fallidas (aplanadas).

Para obtener una lista completa de los atributos estándares, consulta las convenciones semánticas de HTTP y gRPC de OpenTelemetry.

Habilita la telemetría

Para proteger los datos sensibles, los indicadores de telemetría están inhabilitados de forma predeterminada. Debes habilitarlos de forma explícita.

Los seguimientos, los registros o las métricas pueden contener datos sensibles, como nombres de recursos, URLs completas y mensajes de error.

Antes de configurar suscriptores o exportadores para seguimientos, registros o métricas, revisa el contenido de los intervalos y consulta la documentación de OpenTelemetry para configurar filtros y formateadores que eviten la filtración de información sensible, según el caso de uso previsto.

Seguimiento y métricas

En las bibliotecas cliente de Java generadas, debes habilitar el seguimiento y las métricas de forma programática. Para ello, proporciona la fábrica de seguimiento adecuada a la configuración de tu cliente durante la inicialización:

• Seguimiento: Configura el cliente con un OpenTelemetryTracingFactory.
• Métricas: Configura el cliente con un OpenTelemetryMetricsFactory.
• Ambos: Si deseas habilitar el seguimiento y las métricas, configura el cliente con un CompositeTracerFactory que encapsule ambas fábricas.

Para el SDK de BigQuery para Java, habilita el seguimiento configurando BigQueryOptions.newBuilder().setEnableOpenTelemetryTracing(true) y proporcionando el seguimiento de OpenTelemetry.

Logging

Los registros de errores procesables se integran directamente en el framework principal ApiTracer. Para activar los registros de errores procesables de forma global en tus Google Cloud bibliotecas cliente, usa la siguiente variable de entorno:

export GOOGLE_SDK_JAVA_LOGGING=true

Propagación del contexto de seguimiento

La propagación del contexto de seguimiento en las bibliotecas cliente de Java requiere que el seguimiento esté habilitado de forma explícita.

Cuando se habilita la generación de seguimientos (por ejemplo, configurando un OpenTelemetryTracingFactory) y tu aplicación tiene un intervalo de OpenTelemetry activo en el contexto actual cuando se llama a un método de biblioteca cliente, la biblioteca lo usa para proporcionar un contexto de seguimiento para las solicitudes salientes. Esto garantiza que los seguimientos a nivel de la aplicación se puedan correlacionar con los registros y los comportamientos del servicio de backend.

Exporta la telemetría

Una vez que se habilita la telemetría en las bibliotecas cliente, se debe configurar tu aplicación para recopilar y exportar estos datos a tu backend de observabilidad.

Seguimiento y métricas

Para exportar los seguimientos y las métricas que generan las bibliotecas cliente de Java, inicializa el SDK de OpenTelemetry con el exportador que prefieras (por ejemplo, OTLP) y configura el propagador de mapa de texto global en tu aplicación.

Para obtener más detalles sobre la recopilación y exportación de datos de OpenTelemetry a Cloud Monitoring o Cloud Trace, consulta Elige un enfoque de instrumentación

Logging

Las bibliotecas cliente de Java usan frameworks de registro estándares como SLF4J y java.util.logging. Cuando se configura GOOGLE_SDK_JAVA_LOGGING=true, se emiten registros de errores procesables en el nivel DEBUG.

Para enrutar estos registros estructurados a Cloud Logging, configura tu framework de registro (por ejemplo, Logback) para escribir JSON en la salida estándar (stdout). Si realizas la implementación en un entorno como Google Kubernetes Engine o Cloud Run, los agentes integrados rastrean estos registros de forma automática.

Para obtener instrucciones detalladas sobre cómo configurar Logback o java.util.logging para generar JSON compatible con Cloud Logging, incluida la correlación de seguimientos, consulta Configura el registro estructurado para Java.