Présentation de l'API Telemetry (OTLP)

Ce document décrit l'API Telemetry (OTLP), qui implémente le protocole OpenTelemetry Line. 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.

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

Bonnes pratiques

Lorsque vous instrumentez vos applications pour envoyer des données de trace à votre projetGoogle Cloud , 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 intégré pour envoyer la télémétrie à l'API Telemetry. Pour savoir comment exporter directement les 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 projet Google Cloud . Par exemple, lorsque vous utilisez des collecteurs, vous utilisez généralement aussi l'extension googleclientauth pour vous authentifier avec les identifiants Google.

Pour obtenir un exemple d'authentification lors de l'exportation directe des 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 comment ajouter une bibliothèque d'authentification Google spécifique à la langue à votre 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 est compatible avec 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 terminé 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 disponible. 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 journaux 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é de localisation 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, des règles d'administration et de l'ensemble des emplacements de buckets compatibles.