Présentation des exemples d'instrumentation basée sur les collecteurs

Ce document décrit la structure des exemples d'instrumentation fournis pour les langages Go, Java, Node.js et Python. Ces exemples vous expliquent comment instrumenter une application pour utiliser le SDK OpenTelemetry et un collecteur OpenTelemetry.

L'instrumentation de ces exemples, qui inclut l'utilisation du SDK OpenTelemetry et de l'exportateur OTLP intégré au SDK, est indépendante du fournisseur. L'exportateur intégré envoie les données de télémétrie au collecteur OpenTelemetry, qui les reçoit et les envoie ensuite à votre projet Google Cloud . Le collecteur contient la liaison à Google Cloud. Ces exemples utilisent des exportateurs Google Cloud pour envoyer des données de journaux et de métriques à votre projet. Toutefois, elles envoient des données de trace à votre projet à l'aide de l'API Telemetry.

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

  • L'article Migrer de l'exportateur Trace vers le point de terminaison OTLP explique comment utiliser l'instrumentation en cours de traitement pour envoyer des données de trace directement à votre projet Google Cloud .

    Nous vous recommandons d'utiliser un collecteur OpenTelemetry pour exporter vos données de télémétrie lorsque votre environnement est compatible avec l'utilisation d'un collecteur. Si vous ne pouvez pas utiliser de collecteur, vous devez utiliser un exportateur intégré qui envoie directement les données à votre projet Google Cloud .

  • 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 les données de télémétrie de l'application, qu'un exportateur envoie ensuite à votre projet Google Cloud . Les exemples d'applications envoient des données de métriques et de trace à votre projet à l'aide de l'API Telemetry, qui est compatible avec le format OTLP.

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.

    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, qui mettent 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 OpenTelemetry :

      • Les exemples utilisent le récepteur otlp pour les données de métriques et de trace, et le récepteur filelog pour les données de journaux.

      • Les exemples utilisent l'exportateur otlphttp pour les données de métriques et de trace, et l'exportateur Google Cloud pour les données de journaux.

        L'exportateur otlphttp envoie les données à votre projet à l'aide de l'API Telemetry, qui est compatible avec OTLP. L'exportateur Google Cloud convertit vos données de journaux dans un format compatible avec l'API Cloud Logging, puis envoie 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'identifiants Google Clouddans le conteneur otelcol. Vous avez besoin de ce fichier lorsque vous exécutez un exemple sur une machine locale où les identifiants par défaut de l'application (ADC) ne sont disponibles que sous forme de fichier.

Autorisations requises

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

    Ces autorisations sont suffisantes si vous exécutez l'exemple dans Cloud Shell, sur des ressources Google Cloud ou dans un environnement de développement local. Pour savoir comment configurer un projet de quota, consultez Définir le projet de quota.

API requises

Activez les API Cloud Logging, Cloud Monitoring, Cloud Trace et Télémétrie :

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles. 

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Étapes suivantes

Pour en savoir plus sur les collecteurs, consultez Collecteur OpenTelemetry conçu par Google.

Explorez les exemples qui utilisent des exportations basées sur des collecteurs.