Usar ejemplares de Prometheus

En este documento se describe cómo puedes usar Google Cloud Managed Service para Prometheus para ingerir ejemplares de Prometheus en métricas de histograma. Debes usar uno de los siguientes elementos:

  • Versión 0.7.0 o posterior de la recogida gestionada del servicio gestionado de Prometheus
  • Versión 2.35.0-gmp.5-gke.0 o posterior de la recogida autodesplegada de Managed Service para Prometheus
  • El colector de OpenTelemetry

Los ejemplares se suelen usar para asociar identificadores de trazas con datos de métricas recogidos en un intervalo de tiempo, pero se pueden usar para asociar cualquier dato que no sea una métrica con las métricas recogidas. Al almacenar información de la traza con los datos de la métrica, puede identificar rápidamente las trazas asociadas a un cambio repentino en los valores de la métrica. No tiene que cruzar manualmente la información de la traza y los datos de la métrica mediante marcas de tiempo para identificar lo que estaba ocurriendo en la aplicación cuando se registraron los datos de la métrica.

Los ejemplares de Managed Service para Prometheus son compatibles tanto con Cloud Trace como con herramientas de terceros para monitorizar el rastreo, como Grafana Tempo.

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

Gráfico de Grafana que muestra los segmentos del histograma y los ejemplares.

Ejemplares de Prometheus en Managed Service para Prometheus

Prometheus admite ejemplares mediante el formato de exposición OpenMetrics. Un ejemplar de OpenMetrics tiene la siguiente estructura:

  • El valor del ejemplar debe ser un número entero o un número flotante de 64 bits.
  • (Opcional) Una marca de tiempo: debe ser segundos de la época de Unix y puede ser negativa.
  • Un número de etiquetas del ejemplar, que suelen incluir los valores trace_id y span_id. La longitud total de todos los nombres y valores de las etiquetas no debe superar los 128 caracteres UTF-8 ni las 128 runas en las aplicaciones Go.

Google Cloud Managed Service para Prometheus solo puede ingerir ejemplares asociados a métricas de histograma. No se pueden ingerir ejemplares adjuntos a métricas de contador. Las métricas de histograma de Prometheus se convierten al tipo análogo Distribution de Cloud Monitoring, que admite ejemplares. Las métricas que no son de distribución de Cloud Monitoring no admiten ejemplares.

Los ejemplares se pueden consultar durante 24 meses. Compara este periodo de retención con el de Prometheus, donde los ejemplares solo se conservan mientras los datos están en la memoria, normalmente menos de 14 días. Managed Service para Prometheus almacena ejemplares con la serie temporal, por lo que los ejemplares se conservan de acuerdo con la política de conservación de la serie temporal. Para obtener más información sobre la conservación de datos en Cloud Monitoring, consulta el artículo Conservación de datos.

Habilitar la ingestión de ejemplares

Si usas Managed Service para Prometheus con la versión 0.7.0 o posterior de la recogida gestionada, la ingesta de ejemplares se habilita automáticamente.

Si usas Managed Service para Prometheus con la recogida autodesplegada, debes habilitar la ingesta de ejemplares al iniciar el servidor especificando la siguiente marca de función:

--enable-feature=exemplar-storage

Escribir métricas con ejemplares

Cada cliente de Prometheus tiene sus propias instrucciones para usar correctamente los ejemplares en ese cliente. Sigue estas instrucciones para que tu aplicación exponga métricas en formato OpenMetrics para que Prometheus las obtenga del endpoint /metrics de la aplicación. Por ejemplo, consulta lo siguiente:

Integración con Cloud Trace

Puedes escribir histogramas de Prometheus con ejemplares compatibles con Cloud Trace. Puede mostrar los datos, incluidos los ejemplares, en un gráfico de mapa de calor de Cloud Monitoring, donde puede usar los ejemplares para ver detalles sobre los intervalos de seguimiento relacionados. También puedes analizar los datos de la traza en Trace. Para obtener más información, consulta Mostrar ejemplares en un gráfico de mapa de calor.

Para crear ejemplares compatibles con Trace, tus ejemplares de Prometheus deben contener las siguientes etiquetas:

  • project_id
  • trace_id
  • span_id

Si tu ejemplar incluye estas tres etiquetas, se usarán para crear un objeto SpanContext compatible con Trace que se adjuntará al ejemplar creado para el segmento Distribution de Cloud Monitoring.

Todas las etiquetas que no forman parte de un SpanContext completo se añaden a un objeto DroppedLabels adjunto al ejemplar de un segmento Distribution.

Consultar métricas con ejemplares

La API de Prometheus expone el punto de conexión api/v1/query_exemplars para consultar ejemplares.

Las interfaces de consulta configuradas para interactuar con Google Cloud Managed Service para Prometheus incluyen automáticamente las consultas de ejemplares. Para obtener información sobre cómo configurar interfaces de consulta, consulta Consultar con Grafana o Consultar con la API o la interfaz de usuario de Prometheus.