Usar ejemplares de Prometheus

En este documento, se describe cómo puedes usar Google Cloud Managed Service para Prometheus para transferir ejemplares de Prometheus en las métricas de histogramas. Debes usar una de las siguientes opciones:

  • Servicio administrado para la versión de colección administrada de Prometheus que 0.7.0 o una versión posterior
  • Recopilación autoimplementada de Managed Service para Prometheus versión 2.35.0-gmp.5-gke.0 o posterior
  • El recopilador de OpenTelemetry:

Los ejemplos se suelen usar para asociar identificadores de seguimiento con datos de métricas recopilados en un intervalo de tiempo, pero se pueden usar para asociar cualquier dato que no sea de métrica con las métricas recopiladas. Almacenar información de seguimiento con los datos de las métricas te permite identificar con rapidez los seguimientos asociados con un cambio repentino en los valores de las métricas. No tienes que comparar manualmente mediante referencia cruzada la información de seguimiento y los datos de métricas con el uso de marcas de tiempo para identificar lo que estaba sucediendo en la aplicación cuando se registraron los datos de las métricas.

Los servicios administrados para ejemplares de Prometheus son compatibles con Cloud Trace y herramientas de seguimiento de terceros, como Grafana Tempo.

En la siguiente captura de pantalla, se muestra un gráfico de Grafana de conjuntos de buckets de histogramas y ejemplares asociados, con un ejemplar expandido:

Gráfico de Grafana que muestra ejemplares y buckets de histogramas.

Ejemplares de Prometheus en el servicio administrado para Prometheus

Los ejemplares se admiten en Prometheus mediante el formato de exposición de OpenMetrics. Un ejemplo de OpenMetrics tiene la siguiente estructura:

  • El valor del ejemplo debe ser un número entero o un número de punto flotante de 64 bits.
  • Una marca de tiempo: debe ser segundos de tiempo Unix, puede ser negativo (opcional).
  • Una serie de etiquetas para el ejemplo, generalmente los valores trace_id y span_id; la longitud total de todos los nombres y valores de las etiquetas no debe exceder los 128 caracteres UTF-8 o 128 ejecuciones en las aplicaciones de Go.

Google Cloud Managed Service para Prometheus solo puede transferir ejemplares adjuntos a las métricas de histogramas. No se pueden transferir los ejemplos adjuntos a las métricas de contador. Las métricas del histograma de Prometheus se convierten en el tipo Distribution analógico de Cloud Monitoring, que admite ejemplares. Las métricas que no son de distribución en Cloud Monitoring no admiten ejemplos.

Los ejemplos permanecen disponibles para consultas durante 24 meses. Compara este período de retención con Prometheus ascendente, en el que los ejemplos se retienen solo mientras los datos están en la memoria, por lo general, menos de 14 días. El servicio administrado para Prometheus almacena ejemplares con las series temporales, por lo que los ejemplares se conservan de acuerdo con la política de retención de las series temporales. Para obtener más información sobre la retención de datos en Cloud Monitoring, consulta Retención de datos.

Habilita la transferencia de ejemplares

Si usas Managed Service para Prometheus con la recopilación administrada versión 0.7.0 o posterior, la transferencia de ejemplos se habilita automáticamente.

Si usas el servicio administrado para Prometheus con colección implementada automáticamente, debes habilitar la transferencia de ejemplos cuando inicies el servidor mediante la especificación de la siguiente marca de función:

--enable-feature=exemplar-storage

Escribe métricas con ejemplares

Cada cliente de Prometheus tiene sus propias instrucciones para usar correctamente los ejemplos en ese cliente. Sigue estas instrucciones para que tu aplicación exponga métricas en el formato OpenMetrics para que Prometheus las extraiga del extremo /metrics de la aplicación. Para ver ejemplos, consulta lo siguiente:

Integra en Cloud Trace.

Puedes escribir histogramas de Prometheus con ejemplos que sean compatibles con Cloud Trace. Puedes mostrar los datos, incluidos los ejemplos, en un gráfico de mapa de calor de Cloud Monitoring, en el que puedes usar los ejemplos para obtener detalles sobre los intervalos de seguimiento relacionados. También puedes analizar los datos de seguimiento en Trace. Para obtener más información, consulta Muestra ejemplos en un gráfico de mapa de calor y Visualiza los detalles de seguimiento.

Para crear ejemplos que sean compatibles con Trace, tus ejemplos de Prometheus deben contener las siguientes etiquetas:

  • project_id
  • trace_id
  • span_id

Si tu ejemplo incluye estas tres etiquetas, estas se usan para crear una objeto SpanContext compatible con Trace que se adjunta al ejemplo creado para el bucket Distribution de Cloud Monitoring.

Todas las etiquetas, excepto las que conforman un SpanContext completo, se agregan a un objeto DroppedLabels adjunto al modelo para un bucket Distribution.

Consulta métricas con ejemplares

La API de Prometheus expone el extremo api/v1/query_exemplars para consultar ejemplos.

Las interfaces de consulta configuradas para interactuar con Google Cloud Managed Service para Prometheus incluyen automáticamente la consulta de modelos. Para obtener información sobre cómo configurar interfaces de consulta, visita Consulta con Grafana o Consulta con la IU o la API de Prometheus.