Présentation de l'API Telemetry (OTLP)

Ce document décrit l'API Telemetry (OTLP), qui implémente le protocole OTLP OpenTelemetry. Cette API est conçue pour être utilisée avec des applications instrumentées à l'aide de l'un des SDK OpenTelemetry ou qui utilisent un collecteur 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.

Données de trace et API Telemetry

Cette section fournit des informations sur l'API Telemetry et les traces.

Pourquoi utiliser l'API Telemetry ?

Lorsque vous utilisez l'API Telemetry, vos données sont stockées dans un format généralement compatible avec les fichiers proto définis par le protocole OTLP OpenTelemetry. Toutefois, les champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en type de données JSON avant d'être stockés. De plus, les limites de l'API Telemetry s'appliquent. Ces limites sont souvent plus généreuses que celles de l'API Cloud Trace. Enfin, votre instrumentation ne repose pas sur un exportateur spécifique à Google Cloud.

Pour en savoir plus sur le format de stockage, consultez Schéma des données de trace.

Quand utiliser l'API Telemetry ?

Nous vous recommandons d'envoyer vos données de trace à votre projet Google Cloud en utilisant l'API Telemetry. Cette API est compatible avec l'écosystème OpenTelemetry Open Source. Ses limites sont souvent plus généreuses que celles de l'API Cloud Trace, qui est une APIGoogle Cloud propriétaire. Certaines fonctionnalités, comme Application Monitoring, reposent sur des informations qui ne sont disponibles que lorsque les données de trace sont envoyées à l'API Telemetry.

Lorsque vous instrumentez vos applications pour envoyer des données de trace à votre projetGoogle Cloud , nous vous recommandons d'effectuer l'une des opérations suivantes :

Utilisez un exportateur qui écrit OTLP dans un collecteur, qui envoie ensuite vos données de trace à l'API Telemetry.
Utilisez un exportateur OTLP intégré compatible avec une bibliothèque OpenTelemetry qui envoie des données de télémétrie à l'API Telemetry. Aucun collecteur ne correspond à cette configuration.

Pour savoir comment utiliser l'API Telemetry, consultez Migrer de l'exportateur Cloud Trace vers le point de terminaison OTLP.

Authentification

Les exportateurs doivent être autorisés à envoyer des données à votre projet Google Cloud . Par exemple, vous pouvez configurer l'exportateur avec vos identifiants par défaut de l'application (ADC) Google Clouden ajoutant une bibliothèque d'authentification Google spécifique à la langue à votre application. Pour en savoir plus et obtenir un exemple de code, consultez Configurer l'authentification.

Cloud Trace et résidence des données

Si vous utilisez Assured Workloads parce que vous avez des exigences de résidence des données ou de niveau d'impact 4 (IL4), n'utilisez pas l'API Telemetry pour envoyer des étendues de trace.

Données de métriques et API Telemetry

Cette section explique comment Cloud Monitoring gère les métriques ingérées à l'aide de l'exportateur otlphttp et d'un collecteur OpenTelemetry, ou par des applications instrumentées à l'aide de l'un des SDK OpenTelemetry.

Métriques OTLP dans Cloud Monitoring

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 changer 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.

Mappage des métriques Prometheus

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

La jauge OTLP est mappée sur la jauge Cloud Monitoring.
La somme OTLP est mappée comme suit :
- Pour évaluer 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 à la 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 de 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
SUM (non-monotonic, CUMULATIVE)	JAUGE	DOUBLE	/gauge
HISTOGRAMME (CUMULATIF)	CUMULATIVE (CUMULÉ)	DISTRIBUTION avec buckets explicites	/histogram
HISTOGRAMME EXPONENTIEL (CUMULATIF)	CUMULATIVE (CUMULÉ)	DISTRIBUTION avec des buckets exponentiels	/histogram
HISTOGRAMME (DELTA)	DELTA	DISTRIBUTION avec buckets explicites	/histogram:delta
HISTOGRAMME EXPONENTIEL (DELTA)	DELTA	DISTRIBUTION avec des 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 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 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 trace ingérées via l'API Telemetry peuvent être consultées sur la page Trace Explorer. Pour savoir comment afficher vos données de trace, consultez les pages suivantes :

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.

Compatibilité avec VPC Service Controls

Le service de l'API Telemetry, dont le nom de service est telemetry.googleapis.com, est un service compatible avec VPC Service Controls. Toutes les restrictions VPC Service Controls que vous créez pour le service de l'API Telemetry ne s'appliquent qu'à ce service. Ces restrictions ne s'appliquent à aucun autre service, y compris ceux comme le service cloudtrace.googleapis.com, qui peuvent également ingérer des données de trace.

Pour en savoir plus, consultez les ressources suivantes :