Présentation de l'API Telemetry (OTLP)

Ce document décrit l'API Telemetry (OTLP), qui implémente le protocole 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 Clouddes Google Cloud ingénieurs chargés d'assurer la compatibilité avec l'ingestion et la visualisation de votre télémétrie.

Pour en savoir plus sur cette API, consultez les documents de référence suivants :

Pour en savoir plus sur les quotas associés à l'API, consultez Limites de l'API Telemetry.

Bonnes pratiques

Lorsque vous instrumentez vos applications pour envoyer des données de trace à votre Google Cloud projet, nous vous recommandons d'utiliser un exportateur qui écrit des données au format OTLP dans un collecteur, qui envoie ensuite vos données de trace à l'API Telemetry. Dans votre collecteur, spécifiez uniquement l'URL racine :

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry détecte le type de données et ajoute automatiquement /v1/traces, /v1/metrics ou /v1/logs, selon le cas. Pour en savoir plus, consultez Requête OTLP/HTTP.

Pour obtenir des exemples d'exportation de données de trace ou de métriques vers l'API Telemetry, consultez les documents suivants :

Lorsque vous ne pouvez pas utiliser de collecteur, vous pouvez utiliser une bibliothèque OpenTelemetry contenant un exportateur OTLP en cours de traitement pour envoyer des données de télémétrie à l'API Telemetry. Pour savoir comment exporter directement des données de trace, consultez Exportateur Cloud Trace vers le point de terminaison OTLP.

Authentification

Vous devez configurer vos exportateurs avec les identifiants nécessaires pour envoyer des données à votre Google Cloud projet. Par exemple, lorsque vous utilisez des collecteurs, vous utilisez généralement l'extension googleclientauth pour vous authentifier avec des identifiants Google.

Pour obtenir un exemple d'authentification lors de l'exportation directe de données de trace, consultez Configurer l'authentification. Cet exemple montre comment configurer l'exportateur avec vos Google Cloud identifiants par défaut de l'application (ADC) et ajouter une bibliothèque d'authentification Google spécifique à la langue à votre application.

Pour envoyer des données de télémétrie à votre Google Cloud projet à l'aide de l'API Telemetry, vous devez également procéder comme suit :

  • Configurer un projet de quota. Pour en savoir plus, consultez Définir le projet de quota.

  • Attribuez les rôles IAM (Identity and Access Management) suivants à l'utilisateur ou au compte de service utilisé par l'application :

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 :

Points de terminaison d'un service

Un point de terminaison de service est une URL de base qui spécifie l' adresse réseau d'un service d'API. L'API Telemetry accepte un point de terminaison global et des points de terminaison régionaux :

  • Point de terminaison global : telemetry.googleapis.com. Pour ce point de terminaison, une fois que Google Cloud Observability a effectué toutes les étapes de validation, il envoie les données à un service de backend pour le stockage.

  • Points de terminaison régionaux : telemetry.REGION.rep.googleapis.com, où REGION est une région compatible. Pour ces points de terminaison, une fois que Google Cloud Observability a effectué toutes les étapes de validation, il envoie les données à un service de backend. Ce service stocke ou supprime les données :

    • Les données de journal et de trace sont stockées. Le service de backend déplace automatiquement les données entre les régions si nécessaire.
    • Les données de métriques ne sont stockées que lorsque le libellé d'emplacement associé aux données correspond à la région du point de terminaison ou à une zone de cette région.

    Pour obtenir la liste des points de terminaison régionaux compatibles, consultez la documentation de référence de l'API.

L'ingestion de données de trace peut déclencher la création d'un bucket d'observabilité. Toutefois, l'utilisation d'un point de terminaison régional n'a aucune incidence sur l'emplacement où le système crée le bucket d'observabilité. Le système détermine l'emplacement d'un bucket d'observabilité à l'aide des paramètres par défaut, règles d'administration et de l'ensemble des emplacements de bucket compatibles.