Présentation de v1.traces

Ce document explique pourquoi nous vous recommandons d'envoyer vos données de trace à votre Google Cloud projet à l'aide de l'API Telemetry (OTLP), qui implémente le protocole OpenTelemetry OTLP. Il fournit également des conseils sur l'instrumentation de vos applications et sur l'emplacement où vous pouvez afficher vos données de trace. Vous pouvez utiliser l' API Telemetry lorsque vous instrumentez vos applications à l'aide de l'un des SDK OpenTelemetry ou lorsque vous utilisez un collecteur OpenTelemetry.

Nous recommandons l'API Telemetry pour les raisons suivantes :

  • L'API est compatible avec l'écosystème Open Source OpenTelemetry et ses limites sont souvent plus généreuses que celles de l' API Cloud Trace, qui est une API propriétaire Google Cloud .

  • Vos données de trace sont stockées dans un format généralement cohérent avec les fichiers proto définis par le protocole OpenTelemetry OTLP. Certains champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en un type de données JSON avant le stockage. Pour en savoir plus sur le format de stockage, consultez Schéma des données de trace.

  • Votre instrumentation ne repose pas sur un Google Cloud-exportateur spécifique.

  • Certaines fonctionnalités, comme Application Monitoring, reposent sur des informations qui ne sont disponibles que lorsque vous envoyez des données de trace à l'API Telemetry.

OpenTelemetry est un projet Open Source compatible avec Google Clouddes Google Cloud ingénieurs qui veillent à la prise en charge de l'ingestion et de la visualisation de votre télémétrie.

Google Cloud Observability vérifie que l'API Cloud Trace est activée sur votre Google Cloud projet avant de stocker des données de trace. Cela signifie que si vous désactivez l'API Cloud Trace, Google Cloud Observability supprime les données de trace que vous envoyez à 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 intégré 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 aussi 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 à un langage à votre application.

Cloud Trace et résidence des données

Si vous utilisez Assured Workloads car vous avez des exigences en matière 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 à votre projet.

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

Vous pouvez afficher vos données de trace à l'aide des pages Explorateur de traces et Observability Analytics. Pour en savoir plus, consultez les pages suivantes :