Présentation de v1.metrics

Ce document explique comment les données de métriques envoyées à votre Google Cloud projet à l'aide de l'API Telemetry (OTLP) sont mappées aux structures Cloud Monitoring. Cette API implémente le protocole OTLP OpenTelemetry. Vous pouvez envoyer des données à cette API lorsque vous instrumentez vos applications avec un exportateur otlphttp et un collecteur OpenTelemetry, ou lorsque vous utilisez les SDK OpenTelemetry.

OpenTelemetry est un projet Open Source compatible avec Google Clouddes Google Cloud ingénieurs chargés d'assurer la prise en charge de l'ingestion et de la visualisation de vos données de télémétrie.

Pour savoir comment configurer OpenTelemetry afin d'envoyer des métriques OTLP à Cloud Monitoring, consultez la présentation de l'ingestion de métriques OTLP.

Métriques OTLP dans Cloud Monitoring

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Lorsque des métriques sont ingérées dans Cloud Monitoring à l'aide d'un collecteur OpenTelemetry et de l'exportateur otlphttp, ou envoyées directement à l'aide d'un SDK OpenTelemetry, les métriques OTLP sont mappées aux structures de métriques Cloud Monitoring. Cette section décrit les opérations suivantes :

• Le mappage entre les ressources OTLP et les ressources surveillées Cloud Monitoring.
• Le mappage entre les métriques OTLP et les métriques Cloud Monitoring.

Mappage des ressources surveillées

Tous les points de métrique sont écrits tels quels pour Google Cloud Managed Service pour Prometheus, à l'aide du mappage Prometheus.

Mappage Prometheus

Les métriques Prometheus nécessitent l'utilisation du type de ressource surveillée prometheus_target.

Les libellés suivants sur le type de ressource prometheus_target sont utilisés pour schématiser et stocker efficacement les données dans Monarch. Plus vous spécifiez précisément les valeurs de ces attributs, plus votre capacité de requête et votre évolutivité seront élevées.

Nous vous recommandons vivement d'être aussi explicite que possible lorsque vous définissez des valeurs pour ces libellés, bien que nous ayons implémenté une logique de secours à utiliser en l'absence de valeurs explicites.

Le tableau suivant présente les sources de valeurs pour les libellés, par ordre de priorité :

Libellé prometheus-target	Valeur utilisée (par ordre de priorité)
location (obligatoire)	Attribut location Attribut cloud.availability_zone Attribut cloud.region
cluster	Attribut cluster Attribut k8s.cluster.name __gce__, si l'attribut cloud.platform est gcp_compute_engine __run__, si l'attribut cloud.platform est gcp_cloud_run Chaîne vide
namespace	Attribut namespace Attribut k8s.namespace.name Attribut service.namespace Chaîne vide
job	Attribut job "service.namespace" + "/" + service.namespace Attribut Attribut service.name Attribut service.name, si ce n'est pas unknown_service:foo Attribut faas.name Attribut k8s.deployment.name Attribut k8s.statefulset.name Attribut k8s.job.name Attribut k8s.cronjob.name service.name Attribut, si unknown_service:foo Chaîne vide
instance Rejeter le point s'il est vide	Attribut instance Attribut service.instance.id Attribut faas.instance Attribut k8s.pod.name:k8s.container.name Attribut k8s.pod.name, si aucun nom de conteneur n'est présent Attribut host.id

Mappage des métriques

Les métriques sont converties au format de séries temporelles Prometheus. Les noms de métriques ne doivent pas avoir de domaine ou doivent avoir le domaine prometheus.googleapis.com. Après la conversion, le nom de la métrique inclut le préfixe prometheus.googleapis.com et un suffixe supplémentaire, en fonction du type de point OTLP. La métrique Cloud Monitoring résultante présente la structure suivante :

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

De plus, pour chaque ressource OpenTelemetry unique, la conversion ajoute une target_info métrique qui contient tous les attributs de ressource, à l'exception de service.name, service.instance.id et service.namespace.

Toutes les métriques OTLP INT64 sont traduites en type de valeur DOUBLE dans Cloud Monitoring, même si le collecteur spécifie le type de valeur INT64. Cette modification est apportée, car une fois qu'une série temporelle se trouve dans Monarch, vous ne pouvez plus modifier le type de valeur. La conséquence la plus courante de la prise en charge des valeurs INT64 est que vous vous retrouvez avec des collisions qui ne peuvent être résolues qu'en supprimant une métrique.

Remarque : Nous nous attendons à ce qu'il y ait des collisions de types de valeurs possibles, en particulier si vous avez déjà envoyé des métriques INT64 target_info. Si vous rencontrez des collisions, la meilleure solution à long terme consiste à supprimer le descripteur de la métrique pour les métriques INT64 target_info. Pour supprimer ce descripteur de votre champ d'application de métriques, utilisez ce script Golang.

Mappage des métriques Prometheus

Les types de métriques sont mappés comme suit :

• La jauge OTLP est mappée à la jauge Cloud Monitoring gauge.
• La somme OTLP est mappée comme suit :
  • À la jauge Cloud Monitoring gauge lorsque is_monotonic est défini sur false.
  • À la valeur cumulée Cloud Monitoring lorsque aggregation_temporality est défini sur AGGREGATION_TEMPORALITY_CUMULATIVE.
  • À la valeur delta Cloud Monitoring delta lorsque aggregation_temporality est défini sur AGGREGATION_TEMPORALITY_DELTA.
• L'histogramme OTLP est mappé à la distribution Cloud Monitoring avec un type de métrique cumulé ou delta, en fonction de la valeur de aggregation_temporality.
• Les métriques de résumé OTLP sont développées en séries temporelles individuelles pour chaque composant : count, sum et chaque quantile.
  • Les noms des métriques de comptage et de somme sont respectivement suffixés par _count ou _sum, et sont écrits en tant que métriques cumulées Cloud Monitoring de type DOUBLE.
  • Chaque quantile devient sa propre série temporelle de jauge de type DOUBLE, avec un libellé quantile.

Le tableau suivant récapitule le mappage des métriques :

Type de point OTLP	Type de métrique Monitoring	Type de valeur Monitoring	Suffixe	Remarques
GAUGE	GAUGE	DOUBLE	/gauge
JAUGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	Les inconnues Prometheus sont divisées en compteur et en jauge par le collecteur OpenTelemetry.
SOMME (monotone, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SOMME (monotone, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	Les inconnues Prometheus sont divisées en compteur et en jauge par le collecteur OpenTelemetry.
SOMME (monotone, DELTA)	DELTA	DOUBLE	/delta
SOMME (non monotone, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SOMME (non monotone, DELTA)	Non compatible			Les UpDownCounters de temporalité delta ne sont pas compatibles.
HISTOGRAMME (CUMULATIVE)	CUMULATIVE	DISTRIBUTION avec des buckets explicites	/histogram
HISTOGRAMME EXPONENTIEL (CUMULATIVE)	CUMULATIVE	DISTRIBUTION avec des buckets exponentiels	/histogram
HISTOGRAMME (DELTA)	DELTA	DISTRIBUTION avec des buckets explicites	/histogram:delta
HISTOGRAMME EXPONENTIEL (DELTA)	DELTA	DISTRIBUTION avec des buckets exponentiels	/histogram:delta
RÉSUMÉ (somme, comptage, quantile)	CUMULATIVE CUMULATIVE JAUGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Les points de données de résumé sont écrits sous forme de plusieurs séries temporelles, une pour le comptage, la somme et chaque quantile calculé. Les métriques de quantile sont également générées avec un quantile libellé.

Différences entre l'exportateur googlemanagedprometheus et l'API Telemetry

L'API Telemetry (telemetry.googleapis.com) gère les métriques différemment de l'exportateur googlemanagedprometheus:

• L'API Telemetry autorise les caractères point (.) et barre oblique (/) avec dans les noms de métriques. L'exportateur googlemanagedprometheus convertit toutes les instances de ces caractères en caractère de soulignement (_). Par exemple, une métrique OTLP appelée prometheus.googleapis.com/foo.bar/gauge est exportée telle quelle par l'exportateur OTLP, mais est exportée en tant que prometheus.googleapis.com/foo_bar/gauge par l'exportateur googlemanagedprometheus.

  Lorsque les métriques sont ingérées, Cloud Monitoring crée des descripteurs de métriques en fonction des noms. La différence dans la façon dont les caractères point (.) et barre oblique (/) sont gérés par les chemins d'ingestion signifie que les descripteurs de métriques résultants diffèrent entre les métriques ingérées à l'aide de l'exportateur googlemanagedprometheus et celles ingérées à l'aide de l'exportateur otlphttp. Si vous utilisez les deux chemins d'ingestion, vous disposez de deux ensembles de métriques. Pour obtenir des résultats complets lors de l'interrogation, vous devez unir manuellement les résultats des versions Prometheus et OTLP des métriques.

• L'API Telemetry n'ajoute pas d'unité à un nom de métrique lorsqu'une unité est présente, et n'ajoute pas de suffixe _total aux compteurs. Ainsi, une métrique exportée en tant que prometheus.googleapis.com/foo/counter lors de l'utilisation de l'API Telemetry est exportée en tant que prometheus.googleapis.com/foo_seconds_total/counter par l'exportateur googlemanagedprometheus. Cette différence s'applique également aux suffixes _total et _ratio.

• L'API synthétise la valeur sum_of_squared_deviation pour les valeurs de distribution dérivées d'histogrammes exponentiels. L'exportateur googlemanagedprometheus ne définit pas ce champ pour les histogrammes exponentiels.

• L'API convertit toutes les valeurs de point entières en valeurs doubles pour les métriques Prometheus.

• L'API ne définit pas les libellés scope_version ni scope_name si ces libellés ont des valeurs vides.

Où afficher les données ingérées

Les données de métriques ingérées via l'API Telemetry peuvent être consultées sur la page Explorateur de métriques. Pour savoir comment afficher et représenter graphiquement vos données de métriques, consultez la page Créer des graphiques avec l'explorateur de métriques.