Descripción general de v1.traces

En este documento, se describe por qué recomendamos que envíes tus datos de seguimiento a tu proyecto deGoogle Cloud con la API de Telemetry (OTLP), que implementa el protocolo OTLP de OpenTelemetry. También proporciona orientación sobre cómo instrumentar tus aplicaciones y dónde puedes ver los datos de seguimiento. Puedes usar la API de Telemetry cuando instrumentas tus aplicaciones con uno de los SDKs de OpenTelemetry o cuando usas un recopilador de OpenTelemetry.

Recomendamos la API de Telemetry por el siguiente motivo:

  • La API proporciona compatibilidad con el ecosistema de código abierto de OpenTelemetry y sus límites suelen ser más generosos que los de la API de Cloud Trace, que es una API Google Cloud propietaria.

  • Tus datos de seguimiento se almacenan en un formato que suele ser coherente con los archivos .proto definidos por el protocolo OTLP de OpenTelemetry. Algunos campos se pueden convertir de un tipo de datos específico de OpenTelemetry a un tipo de datos JSON antes del almacenamiento. Para obtener más información sobre el formato de almacenamiento, consulta Esquema de los datos de registro.

  • Tu instrumentación no depende de un exportador específico de Google Cloud.

  • Algunas funciones, como la supervisión de aplicaciones, dependen de la información que solo está disponible cuando envías datos de seguimiento a la API de Telemetry.

OpenTelemetry es un proyecto de código abierto compatible con Google Cloudque cuenta con ingenieros Google Cloudpara garantizar la compatibilidad con la transferencia y visualización de tus datos de telemetría.

Google Cloud Observability verifica que la API de Cloud Trace esté habilitada en tu proyecto Google Cloud antes de almacenar cualquier dato de seguimiento. Esto significa que, si inhabilitas la API de Cloud Trace, Google Cloud Observability descartará los datos de seguimiento que envíes a la API de Telemetry.

Prácticas recomendadas

Cuando instrumentes tus aplicaciones para enviar datos de seguimiento a tu proyecto deGoogle Cloud , te recomendamos que uses un exportador que escriba datos con formato de OTLP en un Collector, que luego envía tus datos de seguimiento a la API de Telemetry. En tu recopilador, especifica solo la URL raíz:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry detecta el tipo de datos y agrega automáticamente /v1/traces, /v1/metrics o /v1/logs según corresponda. Para obtener más información, consulta Solicitud de OTLP/HTTP.

Si deseas ver ejemplos que exportan datos de seguimiento o de métricas a la API de Telemetry, consulta los siguientes documentos:

Cuando no puedes usar un recopilador, puedes usar una biblioteca de OpenTelemetry que contenga un exportador de OTLP en el proceso para enviar datos de telemetría a la API de Telemetry. Para obtener información sobre cómo exportar datos de seguimiento directamente, consulta Exportador de Cloud Trace al extremo de OTLP.

Autenticación

Debes configurar tus exportadores con las credenciales necesarias para enviar datos a tu proyecto de Google Cloud . Por ejemplo, cuando usas recopiladores, también sueles usar la extensión googleclientauth para autenticarte con las credenciales de Google.

Para ver un ejemplo de autenticación cuando se usa la exportación directa de datos de seguimiento, consulta Configura la autenticación. En este ejemplo, se ilustra cómo configurar el exportador con tus Google Cloud credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de Google Auth específica del idioma a tu aplicación.

Cloud Trace y residencia de datos

Si usas Assured Workloads porque tienes requisitos de residencia de datos o de nivel de impacto 4 (IL4), no uses la API de Telemetry para enviar intervalos de seguimiento a tu proyecto.

Dónde ver los datos transferidos

Puedes ver tus datos de seguimiento en las páginas Explorador de seguimiento y Observability Analytics. Para obtener más información, consulta lo siguiente: