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 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 , puis les envoie à votre Google Cloud projet. Le collecteur contient la liaison à Google Cloud. Ces exemples utilisent des Google Cloud exportateurs pour envoyer des données de journaux et de métriques à votre projet. Toutefois, ils envoient des données de trace à votre projet à l'aide de l'API Telemetry.

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

  • Migrer de l'exportateur Trace vers le point de terminaison OTLP explique comment utiliser l'instrumentation intégrée 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 intégré qui envoie directement les 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.

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 le collecteur OpenTelemetry est configuré pour lire à partir du 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, qui sont ensuite envoyées à votre Google Cloud projet à l'aide d'un Google Cloud exportateur. L'exportateur convertit les données de télémétrie dans un format compatible avec l'API Cloud Trace, l'API Cloud Monitoring ou l'API Cloud Logging. Ensuite, il envoie les données transformées à votre Google Cloud projet en exécutant une commande d'API.

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.

    Si vous examinez les exemples, vous remarquerez que la complexité de cette étape dépend du langage. 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. Configurer 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 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 l'installation d'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'agent 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. Ce collecteur spécifie 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étriques et de journaux. 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 décrit comment les données collectées sont exportées vers un Google Cloud projet. Pour les données de journaux et de métriques, Google Cloud des exportateurs sont utilisés. Ces exportateurs convertissent les données de télémétrie dans un format compatible avec l'API correspondante puis envoient les données transformées à votre Google Cloud projet en exécutant une commande d'API. En revanche, les données de trace sont envoyées à votre projet à l'aide de l'API Telemetry, qui est compatible avec OTLP.

    • docker-compose.creds.yaml : ce fichier monte éventuellement un Google Cloud fichier d'identifiants dans le otelcol conteneur. 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

  • Pour obtenir les autorisations nécessaires aux applications d'exemple afin d'écrire des données de journaux, de métriques et de traces, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

    Si vous exécutez les exemples dans Cloud Shell, sur des Google Cloud ressources, ou dans un environnement de développement local, les autorisations précédentes suffisent pour écrire des données de journaux, de métriques et de traces. Pour les applications de production, un compte de service fournit généralement les identifiants requis.

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 du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l' serviceusage.services.enable autorisation. Découvrez comment attribuer des rôles. 

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

Étape suivante

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

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