Utiliser des exemples Prometheus

Ce document explique comment utiliser Google Cloud Managed Service pour Prometheus pour ingérer des exemples Prometheus sur des métriques d'histogramme. Vous devez utiliser l'une des versions suivantes :

  • Managed Service pour Prometheus version 0.7.0 ou ultérieure
  • Managed Service pour Prometheus auto-déployé version 2.35.0-gmp.5-gke.0 ou ultérieure
  • Le collecteur OpenTelemetry

Les émulateurs sont généralement utilisés pour associer des identifiants de trace aux données de métriques collectées dans un intervalle de temps, mais ils peuvent être utilisés pour associer des données autres que des métriques aux métriques collectées. Le stockage des informations de trace avec les données de métriques vous permet d'identifier rapidement les traces associées à une modification soudaine des valeurs de métrique. Vous n'avez pas besoin de référencer manuellement les données de trace et de métrique en utilisant des horodatages pour identifier ce qui se passe dans l'application lorsque les données de métriques sont enregistrées.

Les exemples Managed Service pour Prometheus sont compatibles à la fois avec Cloud Trace et avec des outils de traçage tiers tels que Grafana Tempo.

La capture d'écran suivante montre un graphique Grafana d'un ensemble de buckets d'histogramme et d'exemples associés, avec un exemple développé :

Graphique Grafana illustrant les buckets d'histogramme et les exemples.

Exemples Prometheus dans Managed Service pour Prometheus

Dans Prometheus, les exemples sont mis en œuvre en utilisant le format d'exposition OpenMetrics. Un exemple OpenMetrics possède la structure suivante :

  • La valeur de l'exemple doit être un entier ou un nombre à virgule flottante de 64 bits.
  • (Facultatif) Un horodatage doit être défini sur Unix Epoch (secondes). Il peut être négatif.
  • Un certain nombre de libellés pour l'exemple, généralement les valeurs trace_id et span_id. La longueur totale de l'ensemble des noms et des valeurs de libellés ne doit pas dépasser 128 caractères UTF-8, ou 128 runes dans les applications Go.

Google Cloud Managed Service pour Prometheus ne peut ingérer que les exemples associés aux métriques d'histogramme. Les exemples associés à des métriques de compteur ne peuvent pas être ingérés. Les métriques d'histogramme Prometheus sont converties au type Cloud Monitoring analogue Distribution, qui est compatible avec les exemples. Les métriques de non-distribution dans Cloud Monitoring ne sont pas compatibles avec les exemples.

Les exemples restent disponibles pendant 24 mois. Comparez cette durée de conservation à Prometheus en amont, où les exemples ne sont conservés que lorsque les données sont en mémoire, soit généralement moins de 14 jours. Managed Service pour Prometheus stocke les exemples avec les séries temporelles, de sorte que les exemples sont conservés conformément à la règle de conservation de la série temporelle. Pour en savoir plus sur la conservation des données dans Cloud Monitoring, consultez la section Conservation des données.

Activer l'ingestion d'exemples

Si vous utilisez Managed Service pour Prometheus avec la version 0.7.0 ou une version ultérieure de la collecte gérée, l'ingestion des exemples est automatiquement activée.

Si vous utilisez Managed Service pour Prometheus avec la collecte auto-déployée, vous devez activer l'ingestion d'exemples lorsque vous démarrez le serveur en spécifiant le flag de fonctionnalité suivant :

--enable-feature=exemplar-storage

Écrire des métriques avec des exemples

Chaque client Prometheus dispose de ses propres instructions pour utiliser correctement les exemples dans ce client. Suivez ces instructions pour que votre application expose des métriques au format OpenMetrics pour Prometheus, afin d'effectuer un scraping du point de terminaison /metrics de l'application. Pour obtenir des exemples, consultez les articles suivants :

Intégration avec Cloud Trace

Vous pouvez écrire des histogrammes Prometheus avec des exemples compatibles avec Cloud Trace. Vous pouvez afficher les données, y compris les exemples, sur un graphique de carte de densité Cloud Monitoring, où vous pouvez utiliser les exemples pour afficher des détails sur les délais de trace associés. Vous pouvez également analyser les données de trace dans Cloud Trace. Pour en savoir plus, consultez les sections Afficher des exemples sur un graphique de carte de densité et Afficher les détails des traces.

Pour créer des exemples compatibles avec Trace, vos exemples Prometheus doivent contenir les libellés suivants :

  • project_id
  • trace_id
  • span_id

Si votre exemple inclut ces trois libellés, ceux-ci sont utilisés pour créer un objet SpanContext compatible avec Trace, qui est associé à l'exemple créé pour le bucket Cloud Monitoring Distribution.

Tous les libellés autres que ceux qui constituent un SpanContext complet sont ajoutées à un objet DroppedLabels associé à l'exemple pour un bucket Distribution.

Interroger les métriques avec des exemples

L'API Prometheus expose le point de terminaison api/v1/query_exemplars pour interroger des exemples.

Les interfaces de requête configurées pour interagir avec Google Cloud Managed Service pour Prometheus incluent automatiquement l'interrogation des exemples. Pour en savoir plus sur la configuration des interfaces de requête, consultez la page Interroger à l'aide de Grafana ou Interroger à l'aide de l'API ou de l'interface utilisateur Prometheus.