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

Pour que le code de votre application reste indépendant du fournisseur tout en collectant et en envoyant des données de télémétrie à Google Cloud, vous pouvez utiliser les exemples d'instrumentation basés sur le collecteur OpenTelemetry pour Go, Java, Node.js, et Python.

Ces exemples montrent comment configurer un SDK OpenTelemetry en cours d'exécution pour exporter des métriques, des journaux et des traces vers un collecteur OpenTelemetry local qui achemine vos données de télémétrie vers Google Cloud. Les exemples envoient des données de métriques et de traces au format OTLP (OpenTelemetry Protocol) à votre Google Cloud projet à l'aide de l' API Telemetry, et envoient des données de journal à l'aide d'un Google Cloud exportateur.

Fonctionnement des exemples

Les exemples pour Go, Java, Node.js et Python utilisent le protocole OpenTelemetry pour collecter des données de trace et de métriques. Les exemples configurent un framework de journalisation pour écrire des journaux structurés et configurent le collecteur OpenTelemetry pour lire le flux stdout de l'application. Pour obtenir des recommandations sur les frameworks, consultez la section 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 Google Cloud des ressources ou 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 Google Cloud projet. Les exemples d'applications envoient des données de métriques et de traces à 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. Configurer OpenTelemetry pour collecter des métriques et des traces à l'aide du collecteur OpenTelemetry.

    La complexité de cette étape dépend du langage. Par exemple, en Go, vous mettez à jour la fonction main pour initialiser la collecte de données de télémétrie et configurer le serveur et le client HTTP.

  2. Configurer 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 vous pouvez 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 Google Cloud projet. D'autres services, comme Compute Engine, nécessitent que vous installiez un agent qui récupère 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. Configurer 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 le collecteur OpenTelemetry :

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

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

        L'exportateur otlphttp envoie des données à votre projet à l'aide de l'API Telemetry, qui est compatible avec OTLP. L' Google Cloud exportateur convertit vos données de journal dans un format compatible avec l' API Cloud Logging, puis envoie les données transformées à votre Google Cloud projet.

    • docker-compose.creds.yaml : ce fichier monte éventuellement un Google Cloud fichier d'identifiants dans le otelcol conteneur. 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 exemples d'applications écrivent des données de journal, de métriques et de traces, demandez à votre administrateur de vous accorder les rôles IAM suivants :

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

API requises

Activez les API Cloud Logging, Cloud Monitoring, Cloud Trace et Telemetry :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (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

Autres approches d'instrumentation

Vous pouvez être intéressé par d'autres exemples qui illustrent différentes configurations :

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

    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 en cours d'exécution qui envoie directement des données à votre Google Cloud projet.

  • 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 exemple est un point de données d'exemple 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étriques.

  • 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.

Étape suivante

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

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