Descripción general de la API de Telemetry (OTLP)

En este documento, se describe la API de Telemetry (OTLP), que implementa el protocolo OTLP de OpenTelemetry. Esta API está diseñada para usarse con aplicaciones instrumentadas con uno de los SDK de OpenTelemetry o que usan cualquier recopilador de OpenTelemetry.

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.

Datos de seguimiento y la API de Telemetry

En esta sección, se proporciona información sobre la API de Telemetry y los registros.

Por qué deberías usar la API de Telemetry

Cuando usas la API de Telemetry, tus datos se almacenan en un formato que suele ser coherente con los archivos .proto definidos por el protocolo OTLP de OpenTelemetry. Sin embargo, es posible que los campos se conviertan de un tipo de datos específico de OpenTelemetry a un tipo de datos JSON antes del almacenamiento. Además, se aplican los límites de la API de Telemetry. Estos límites suelen ser más generosos que los de la API de Cloud Trace. Por último, tu instrumentación no depende de un exportador específico de Google Cloud.

Para obtener más información sobre el formato de almacenamiento, consulta Esquema de los datos de registro.

Cuándo usar la API de Telemetry

Te recomendamos que envíes tus datos de seguimiento a tu proyecto de Google Cloud con la API de Telemetry. Esta 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 deGoogle Cloud propietaria. Algunas funciones, como la supervisión de aplicaciones, dependen de la información que solo está disponible cuando se envían datos de seguimiento a la API de Telemetry.

Cuando instrumentes tus aplicaciones para enviar datos de seguimiento a tu proyecto deGoogle Cloud , te recomendamos que realices una de las siguientes acciones:

• Usa un exportador que escriba OTLP en un Collector, que luego envía tus datos de seguimiento a la API de Telemetry.
• Usa un exportador de OTLP en el proceso compatible con una biblioteca de OpenTelemetry que envíe telemetría a la API de Telemetry. No hay ningún recopilador con esta configuración.

Para obtener información sobre cómo usar la API de Telemetry, consulta Migra del exportador de Cloud Trace al extremo de OTLP.

Autenticación

Los exportadores deben estar autorizados para enviar datos a tu proyecto Google Cloud . Por ejemplo, puedes configurar el exportador con tus Google Cloud credenciales predeterminadas de la aplicación (ADC) agregando una biblioteca de Google Auth específica del lenguaje a tu aplicación. Para obtener más información y código de muestra, consulta Configura la autenticació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.

Datos de métricas y la API de Telemetry

En esta sección, se describe cómo Cloud Monitoring controla las métricas que se transfieren con el exportador de otlphttp y un recopilador de OpenTelemetry, o bien con aplicaciones instrumentadas con uno de los SDKs de OpenTelemetry.

Métricas de OTLP en Cloud Monitoring

Esta función está con sujeción a las "Condiciones de las Ofertas de la Fase Previa a la DG" de la sección Términos Generales del Servicio de los Términos Específicos del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Cuando se transfieren métricas a Cloud Monitoring con un recopilador de OpenTelemetry y el exportador otlphttp, o bien se envían directamente con un SDK de OpenTelemetry, las métricas de OTLP se asignan a las estructuras de métricas de Cloud Monitoring. En esta sección, se describe lo siguiente:

• La asignación entre los recursos de OTLP y los recursos supervisados de Cloud Monitoring.
• La asignación entre las métricas de OTLP y las métricas de Cloud Monitoring.

Asignación de recursos supervisados

Todos los puntos de métricas se escriben tal como lo hacen para Google Cloud Managed Service para Prometheus, con la asignación de Prometheus.

Asignación de Prometheus

Las métricas de Prometheus requieren el uso del tipo de recurso supervisado prometheus_target.

Las siguientes etiquetas del tipo de recurso prometheus_target se usan para esquematizar y almacenar datos de manera eficiente en Monarch. Cuanto más precisamente especifiques los valores de estos atributos, mejor será tu capacidad de consulta y escalabilidad.

Te recomendamos que seas lo más explícito posible cuando establezcas valores para estas etiquetas, aunque implementamos una lógica de resguardo para usar en ausencia de valores explícitos.

En la siguiente tabla, se muestran las fuentes de valores para las etiquetas, en orden de prioridad:

Etiqueta de prometheus-target	Valor utilizado (en orden de prioridad)
location (obligatorio)	Atributo location Atributo cloud.availability_zone Atributo cloud.region
cluster	Atributo cluster Atributo k8s.cluster.name __gce__, si el atributo cloud.platform es gcp_compute_engine __run__, si el atributo cloud.platform es gcp_cloud_run String vacío
namespace	Atributo namespace Atributo k8s.namespace.name Atributo service.namespace String vacío
job	Atributo job "service.namespace" + "/" + atributo service.namespace Atributo service.name Atributo service.name, si no es unknown_service:foo Atributo faas.name Atributo k8s.deployment.name Atributo k8s.statefulset.name Atributo k8s.job.name Atributo k8s.cronjob.name Atributo service.name, si unknown_service:foo String vacío
instance Rechaza el punto si está vacío	Atributo instance Atributo service.instance.id Atributo faas.instance Atributo k8s.pod.name:k8s.container.name Atributo k8s.pod.name, si no hay un nombre de contenedor presente Atributo host.id

Asignación de métricas

Las métricas se convierten al formato de series temporales de Prometheus. Los nombres de las métricas no deben tener dominio o deben tener el dominio prometheus.googleapis.com. Después de la conversión, el nombre de la métrica incluirá el prefijo prometheus.googleapis.com y un sufijo adicional, según el tipo de punto de OTLP. La métrica de Cloud Monitoring resultante tiene la siguiente estructura:

prometheus.googleapis.com/{metric_name}/{suffix}

Además, para cada recurso único de OpenTelemetry, la conversión agrega una métrica target_info que contiene todos los atributos del recurso, excepto service.name, service.instance.id y service.namespace.

Todas las métricas de INT64 de OTLP se traducen al tipo de valor DOUBLE en Cloud Monitoring, incluso si el recopilador especifica el tipo de valor como INT64. Este cambio se realiza porque, una vez que una serie temporal está en Monarch, no se puede cambiar el tipo de valor. La consecuencia más común de admitir valores de INT64 es que terminas con colisiones que solo se pueden resolver borrando una métrica.

Nota: Es posible que haya colisiones de tipos de valores, en especial si ya enviaste métricas de INT64 target_info. Si encuentras colisiones, la mejor solución a largo plazo es que borres el descriptor de métrica para las métricas de INT64 target_info. Para borrar este descriptor de tu permiso de métricas, usa esta secuencia de comandos de Golang.

Asignación de métricas de Prometheus

Los tipos de métricas se asignan de la siguiente manera:

• El indicador OTLP se asigna al indicador de Cloud Monitoring.
• La métrica de OTLP Sum se asigna de la siguiente manera:
  • En el medidor de Cloud Monitoring cuando is_monotonic se establece en false
  • Para Cloud Monitoring acumulativo cuando aggregation_temporality se establece en AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Es el delta de Cloud Monitoring cuando aggregation_temporality se establece en AGGREGATION_TEMPORALITY_DELTA.
• El histograma de OTLP se asigna a la distribución de Cloud Monitoring con un tipo de métrica acumulativo o delta, según el valor de aggregation_temporality.
• Las métricas de resumen de OTLP se expanden en series temporales individuales para cada componente: count, sum y cada quantile.
  • Los nombres de las métricas de recuento y suma tienen el sufijo _count o _sum, respectivamente, y se escriben como métricas acumulativas de Cloud Monitoring del tipo DOUBLE.
  • Cada cuantil se convierte en su propia serie temporal de medidor de tipo DOUBLE, con una etiqueta quantile.

En la siguiente tabla, se resume el mapeo de métricas:

Tipo de punto de OTLP	Supervisión de tipo de métrica	Supervisión del tipo de valor	Sufijo	Notas
GAUGE	GAUGE	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	El recopilador de OpenTelemetry divide los valores desconocidos de Prometheus en un contador y un indicador.
SUM (monotónica, ACUMULATIVA)	ACUMULATIVO	DOUBLE	/counter
SUM (monotónica, CUMULATIVA, metric.metadata["prometheus.type"]="unknown")	ACUMULATIVO	DOUBLE	/unknown:counter	El recopilador de OpenTelemetry divide los valores desconocidos de Prometheus en un contador y un indicador.
SUM (monotónica, DELTA)	DELTA	DOUBLE	/delta
SUM (no monotónica, CUMULATIVE)	GAUGE	DOUBLE	/gauge
HISTOGRAMA (ACUMULATIVO)	ACUMULATIVO	DISTRIBUTION con buckets explícitos	/histogram
HISTOGRAMA EXPONENCIAL (ACUMULATIVO)	ACUMULATIVO	DISTRIBUTION con buckets exponenciales	/histogram
HISTOGRAMA (DELTA)	DELTA	DISTRIBUTION con buckets explícitos	/histogram:delta
HISTOGRAMA EXPONENCIAL (DELTA)	DELTA	DISTRIBUTION con buckets exponenciales	/histogram:delta
SUMMARY (sum, count, quantile)	ACUMULATIVO ACUMULATIVO MEDIDOR	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Los datos de resumen se escriben como varias series temporales, una para el recuento, la suma y cada cuantil calculado. Las métricas de cuantiles también se generan con una etiqueta quantile.

Diferencias entre el exportador de googlemanagedprometheus y la API de Telemetry

La API de Telemetry (telemetry.googleapis.com) controla las métricas de manera diferente al exportador de googlemanagedprometheus:

• La API de Telemetry permite usar los caracteres de punto (.) y barra diagonal (/) en los nombres de las métricas. El exportador de googlemanagedprometheus convierte todas las instancias de estos caracteres en el carácter de guion bajo (_). Por ejemplo, el exportador de OTLP exporta literalmente una métrica de OTLP llamada prometheus.googleapis.com/foo.bar/gauge, pero el exportador de googlemanagedprometheus la exporta como prometheus.googleapis.com/foo_bar/gauge.

  Cuando se transfieren las métricas, Cloud Monitoring crea descriptores de métricas basados en los nombres. La diferencia en la forma en que las rutas de acceso a la transferencia controlan los caracteres de punto (.) y barra (/) significa que los descriptores de métricas resultantes difieren entre las métricas transferidas con el exportador googlemanagedprometheus y las transferidas con el exportador otlphttp. Si usas ambas rutas de acceso de transferencia, tendrás dos conjuntos de métricas. Para obtener resultados completos cuando realices consultas, deberás unir manualmente los resultados de las versiones de Prometheus y OTLP de las métricas.

• La API de Telemetry no agrega una unidad al nombre de una métrica cuando hay una unidad presente, y no agrega un sufijo _total a los contadores. Por lo tanto, una métrica exportada como prometheus.googleapis.com/foo/counter cuando se usa la API de Telemetry se exporta como prometheus.googleapis.com/foo_seconds_total/counter con el exportador googlemanagedprometheus. Esta diferencia también se aplica a los sufijos _total y _ratio.

• La API sintetiza el valor de sum_of_squared_deviation para los valores de distribución derivados de histogramas exponenciales. El exportador de googlemanagedprometheus no establece este campo para los histogramas exponenciales.

• La API convierte todos los valores de puntos enteros en valores dobles para las métricas de Prometheus.

• La API no establece las etiquetas scope_version o scope_name si tienen valores vacíos.

Dónde ver los datos transferidos

Los datos de seguimiento que se transfieren a través de la API de Telemetry se pueden ver en la página del Explorador de Trace. Para obtener información sobre cómo ver tus datos de seguimiento, consulta lo siguiente:

• Cómo encontrar y explorar seguimientos
• Consultar y analizar registros

Los datos de métricas que se transfieren a través de la API de Telemetry se pueden ver en la página del Explorador de métricas. Para obtener información sobre cómo ver y graficar tus datos de métricas, consulta Crea gráficos con el Explorador de métricas.

Compatibilidad con los Controles del servicio de VPC

El servicio de la API de Telemetry, cuyo nombre de servicio es telemetry.googleapis.com, es un servicio compatible con los Controles del servicio de VPC. Las restricciones de los Controles del servicio de VPC que crees para el servicio de la API de Telemetry solo se aplican a ese servicio. Esas restricciones no se aplican a ningún otro servicio, incluidos aquellos como el servicio de cloudtrace.googleapis.com, que también pueden transferir datos de seguimiento.

Para obtener más información, consulta lo siguiente:

• Documentación de los Controles del servicio de VPC
• Productos admitidos y limitaciones.