Présentation de v1.metrics

Ce document explique comment les données de métriques envoyées à votre projet Google Cloud à 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 Cloud. Des ingénieurs Google Cloudsont chargés d'assurer la prise en charge de l'ingestion et de la visualisation de vos données de télémétrie.

Métriques OTLP dans Cloud Monitoring

Cette fonctionnalité est soumise(s) 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 de 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 données sont écrits tels quels pour Google Cloud Managed Service pour Prometheus, à l'aide du mapping Prometheus.

Mappage Prometheus

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

Les libellés suivants du 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é à effectuer des requêtes 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, même si nous avons implémenté une logique de secours à utiliser en l'absence de valeurs explicites.

Le tableau suivant indique les sources des valeurs des libellés, par ordre de priorité :

Étiquette 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 défini sur gcp_compute_engine __run__, si l'attribut cloud.platform est défini sur gcp_cloud_run Chaîne vide
namespace	Attribut namespace Attribut k8s.namespace.name Attribut service.namespace Chaîne vide
job	Attribut job "service.namespace" + "/" + attribut service.namespace Attribut service.name Attribut service.name, sauf si unknown_service:foo Attribut faas.name Attribut k8s.deployment.name Attribut k8s.statefulset.name Attribut k8s.job.name Attribut k8s.cronjob.name Attribut service.name, 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érie temporelle Prometheus. Les noms de métriques ne doivent pas comporter de domaine ou doivent utiliser le domaine prometheus.googleapis.com. Après la conversion, le nom de la métrique inclura le préfixe prometheus.googleapis.com et un suffixe supplémentaire, en fonction du type de point OTLP. La métrique Cloud Monitoring obtenue présente la structure suivante :

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

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

Toutes les métriques INT64 OTLP sont traduites en type de valeur DOUBLE dans Cloud Monitoring, même si le collecteur spécifie le type de valeur comme 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 conflits, 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 des métriques, utilisez ce script Golang.

Mappage des métriques Prometheus

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

• La jauge OTLP correspond à la jauge Cloud Monitoring.
• La somme OTLP est mappée comme suit :
  • Pour gauge Cloud Monitoring lorsque is_monotonic est défini sur false.
  • À Cloud Monitoring cumulatif lorsque aggregation_temporality est défini sur AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Pour Cloud Monitoring delta lorsque aggregation_temporality est défini sur AGGREGATION_TEMPORALITY_DELTA.
• L'histogramme OTLP correspond à une distribution Cloud Monitoring avec un type de métrique cumulative ou delta, selon la valeur de aggregation_temporality.
• Les métriques récapitulatives OTLP sont développées en séries temporelles individuelles pour chaque composant : count, sum et chaque quantile.
  • Les noms des métriques de nombre et de somme sont respectivement suffixés par _count ou _sum et sont écrits en tant que métriques cumulatives Cloud Monitoring de type DOUBLE.
  • Chaque quantile devient sa propre série temporelle gauge 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
JAUGE	JAUGE	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	JAUGE	DOUBLE	/unknown	Les valeurs inconnues Prometheus sont divisées en compteur et en jauge par le collecteur OpenTelemetry.
SUM (monotonic, CUMULATIVE)	CUMULATIVE (CUMULÉ)	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE (CUMULÉ)	DOUBLE	/unknown:counter	Les valeurs inconnues Prometheus sont divisées en compteur et en jauge par le collecteur OpenTelemetry.
SOMME (monotone, DELTA)	DELTA	DOUBLE	/delta
SOMME (non monotone, CUMULATIVE)	JAUGE	DOUBLE	/gauge
HISTOGRAMME (CUMULATIF)	CUMULATIVE (CUMULÉ)	DISTRIBUTION avec buckets explicites	/histogram
HISTOGRAMME EXPONENTIEL (CUMULATIF)	CUMULATIVE (CUMULÉ)	DISTRIBUTION avec buckets exponentiels	/histogram
HISTOGRAMME (DELTA)	DELTA	DISTRIBUTION avec buckets explicites	/histogram:delta
HISTOGRAMME EXPONENTIEL (DELTA)	DELTA	DISTRIBUTION avec buckets exponentiels	/histogram:delta
SUMMARY (sum, count, quantile)	CUMULATIVE CUMULATIVE GAUGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Les points de données récapitulatifs sont écrits sous la forme de plusieurs séries temporelles, une pour le nombre, la somme et chaque quantile calculé. Les métriques de quantile sont également générées avec un libellé quantile.

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 (/) dans les noms de métriques. L'exportateur googlemanagedprometheus convertit toutes les instances de ces caractères en trait 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 elle est exportée sous le nom 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 obtenus 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 fusionner 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 elle n'ajoute pas de suffixe _total aux compteurs. Ainsi, une métrique exportée en tant que prometheus.googleapis.com/foo/counter à l'aide 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 des histogrammes exponentiels. L'exportateur googlemanagedprometheus ne définit pas ce champ pour les histogrammes exponentiels.

• L'API convertit toutes les valeurs de points entiers en valeurs doubles pour les métriques Prometheus.

• L'API ne définit pas les libellés scope_version ni scope_name si leurs valeurs sont vides.

Où consulter 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 vos données de métriques sous forme de graphiques, consultez Créer des graphiques avec l'explorateur de métriques.