Présentation des exemples d'instrumentation

Ce document décrit la structure des exemples d'instrumentation fournis pour les langages Go, Java, Node.js et Python. Ces exemples vous guident dans l'instrumentation d'une application.

Vous pouvez également consulter d'autres exemples illustrant différentes configurations :

• L'article Corréler des métriques et des traces à l'aide d'exemples explique comment configurer une application Go pour générer des exemples. Un exemplar est un exemple de point de données associé à un point de données de métrique. Vous pouvez utiliser des exemples pour corréler vos données de trace et de métrique.

• Utiliser l'agent Ops et le protocole OpenTelemetry (OTLP) explique comment configurer l'agent Ops et un récepteur OTLP pour collecter des métriques et des traces à partir d'une application.

Fonctionnement des échantillons

Les exemples pour Go, Java, Node.js et Python utilisent le protocole OpenTelemetry pour collecter des données de trace et de métrique. Les exemples configurent un framework de journalisation pour écrire des journaux structurés. Le collecteur OpenTelemetry est configuré pour lire le flux stdout de l'application. Pour obtenir des recommandations sur les frameworks, consultez Choisir une approche d'instrumentation.

Les applications sont créées et déployées à l'aide de Docker. Vous n'avez pas besoin d'utiliser Docker lorsque vous instrumentez une application avec OpenTelemetry.

Vous pouvez exécuter les exemples dans Cloud Shell, sur des ressources Google Cloudou dans un environnement de développement local.

Analyse approfondie

Les exemples utilisent le collecteur OpenTelemetry comme side-car pour recevoir et enrichir la télémétrie de l'application, qui est ensuite envoyée à votre projetGoogle Cloud à l'aide d'un Google Cloud exportateur. L'exportateur convertit la télémétrie dans un format compatible avec l'API Cloud Trace, l'API Cloud Monitoring ou l'API Cloud Logging. Ils envoient ensuite les données transformées à votre projetGoogle Cloud en exécutant une commande d'API.

Les exemples montrent comment effectuer les opérations suivantes :

1. Configurez OpenTelemetry pour collecter des métriques et des traces à l'aide du collecteur OpenTelemetry.

   Si vous examinez les exemples, vous remarquerez que la complexité de cette étape dépend de la langue. Par exemple, pour Go, cette étape configure la fonction main pour appeler une fonction qui configure la collecte de métriques et de traces. Pour Go, le serveur et le client HTTP sont également mis à jour.

2. Configurez un framework de journalisation pour écrire des journaux structurés.

   Nous vous recommandons que vos applications écrivent des journaux structurés, ce qui permet de mettre en forme la charge utile du journal en tant qu'objet JSON. Pour ces journaux, vous pouvez créer des requêtes qui recherchent des chemins JSON spécifiques et indexer des champs spécifiques dans la charge utile du journal.

   Certains services, comme Google Kubernetes Engine, disposent d'agents intégrés qui récupèrent les journaux structurés et les envoient à votre projet Google Cloud . D'autres services, comme Compute Engine, nécessitent l'installation d'un agent qui extrait et envoie vos journaux. Pour en savoir plus sur les agents que vous installez, consultez la présentation de l'agent Ops.

   Vous n'avez pas besoin d'installer d'agents pour utiliser ces exemples.

3. Configurez les fichiers Docker. Tous les exemples contiennent les fichiers YAML suivants :

   • docker-compose.yaml : configure les services pour l'application, le collecteur OpenTelemetry et un générateur de charge. Par exemple, le service du collecteur OpenTelemetry, otelcol, spécifie une image, un volume et des variables d'environnement. Le point de terminaison du collecteur OpenTelemetry est défini par la variable d'environnement OTEL_EXPORTER_OTLP_ENDPOINT, qui est spécifiée dans le service app.

   • otel-collector-config.yaml : configure les récepteurs, les exportateurs, les processeurs et les pipelines.

     Le service telemetry définit des pipelines pour les données de trace, de métrique et de journal. Chaque entrée de pipeline spécifie un récepteur, un processeur et un exportateur. Le même récepteur, otlp, est utilisé pour les métriques et les traces.

     La section exporters explique comment les données collectées sont exportées vers un projet Google Cloud . Un exportateur Google Cloud est utilisé pour toutes les données de télémétrie. L'exportateur convertit la télémétrie dans un format compatible avec l'API Cloud Trace, l'API Cloud Monitoring ou l'API Cloud Logging. Il envoie ensuite les données transformées à votre projetGoogle Cloud en exécutant une commande d'API.

   • docker-compose.creds.yaml : ce fichier monte éventuellement un fichier d'identifiantsGoogle Cloud dans le conteneur otelcol. Ce fichier est nécessaire lorsqu'un exemple est exécuté sur une machine locale où les identifiants par défaut de l'application (ADC) ne sont disponibles que sous forme de fichier.

Autorisations requises

Si vous exécutez les exemples dans Cloud Shell, sur des ressources Google Cloudou dans un environnement de développement local, les autorisations listées dans cette section sont suffisantes. Pour les applications de production, un compte de service fournit généralement les identifiants permettant d'écrire des données de journaux, de métriques et de trace.

• Pour obtenir les autorisations nécessaires pour que les applications exemples puissent écrire des données de journaux, de métriques et de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

  • Rédacteur de journaux (roles/logging.logWriter)
  • Rédacteur de métriques Monitoring (roles/monitoring.metricWriter)
  • Agent Cloud Trace (roles/cloudtrace.agent)

• Pour obtenir les autorisations nécessaires pour afficher vos données de journaux, de métriques et de traces, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

  • Lecteur de journaux (roles/logging.viewer)
  • Lecteur Monitoring (roles/monitoring.viewer)
  • Utilisateur Cloud Trace (roles/cloudtrace.user)

  Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

  Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

API requises

Vous trouverez ci-dessous des informations sur les API requises pour envoyer des données de télémétrie à un projet Google Cloud  :

Étapes suivantes

• Exemple de code Go
• Exemple Java
• Exemple Node.js
• Exemple Python