Descripción general de v1.traces

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

Recomendamos la API de Telemetry por los siguientes motivos:

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

  • Tus datos de seguimiento se almacenan en un formato que suele ser coherente con los archivos proto definidos por el protocolo OpenTelemetry. Es posible que algunos campos se conviertan 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 para datos de seguimiento.

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

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

OpenTelemetry es un proyecto de código abierto compatible con Google Cloudingenieros que garantizan la compatibilidad para transferir y visualizar tu Google Cloud telemetría.

Google Cloud Observability verifica que la API de Cloud Trace esté habilitada en tu Google Cloud proyecto antes de almacenar cualquier dato de seguimiento. Eso 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 Google Cloud proyecto, te recomendamos que uses un exportador que escriba datos con formato OTLP en un recopilador, 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 OTLP/HTTP.

Para obtener ejemplos que exportan datos de seguimiento o 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 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 Google Cloud proyecto. Por ejemplo, cuando usas recopiladores, por lo general, usas la extensión googleclientauth para autenticarte con las credenciales de Google.

Para obtener 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 muestra cómo configurar el exportador con tus Google Cloud Credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de autenticación de Google específica para el lenguaje a tu aplicación.

Para enviar datos de telemetría a tu Google Cloud proyecto con la API de Telemetry, también debes hacer lo siguiente:

  • Configura un proyecto de cuota. Para obtener más información, consulta Configura el proyecto de cuota.

  • Otorga los siguientes roles de Identity and Access Management (IAM) al usuario o a la cuenta de servicio que usa la aplicación:

Cloud Trace y residencia de datos

Si usas Assured Workloads porque tienes requisitos de residencia de datos o 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 con las páginas Explorador de seguimiento y Observability Analytics. Para obtener información, consulta lo siguiente:

Cuotas

Para obtener información sobre las cuotas asociadas con la API de Telemetry, consulta Límites de la API de Telemetry.