Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
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.
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 :
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.
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 extraient 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.
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 :
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 :
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[],[],null,["# Instrumentation samples overview\n\nThis document describes the structure of the instrumentation samples provided\nfor the [Go](/trace/docs/setup/go), [Java](/trace/docs/setup/java),\n[Node.js](/trace/docs/setup/nodejs), and [Python](/trace/docs/setup/python) languages.\nThese samples provide guidance about how to instrument an application.\n\nYou might be interested in other samples that illustrate different\nconfigurations:\n\n- [Correlate metrics and traces by using exemplars](/stackdriver/docs/instrumentation/advanced-topics/exemplars)\n describes how to configure a Go application to generate exemplars.\n An *exemplar* is an example data point attached to a metric data point.\n You can use exemplars to correlate your trace and metric data.\n\n- [Use the Ops Agent and OpenTelemetry Protocol (OTLP)](/trace/docs/otlp)\n describes how you can configure the Ops Agent and an OTLP receiver to\n collect metrics and traces from an application.\n\n| **Note:** The samples display only selected portions of a working application. For example, the samples don't display the list of imported packages. However, the complete applications are available on GitHub. From a code snippet, you can open GitHub by using the *more_vert* **More** options.\n\nHow the samples work\n--------------------\n\nThe samples for Go, Java, Node.js, and Python use the\n[OpenTelemetry protocol](https://opentelemetry.io/docs/specs/otlp/) to collect trace and metric data.\nThe samples configure a logging framework to write\n[structured logs](/logging/docs/structured-logging) and the\nOpenTelemetry collector is configured to read from\nthe application's `stdout` stream. For framework recommendations, see\n[Choose an instrumentation approach](/stackdriver/docs/instrumentation/choose-approach).\n\nThe applications are built and deployed by using Docker. You don't have to\nuse Docker when you instrument an application with OpenTelemetry.\n\nYou can run the samples in the Cloud Shell, on Google Cloud\nresources, or on a local development environment.\n\nDeep dive\n---------\n\nThe samples use the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/installation/) as a sidecar\nto receive and enrich the application's telemetry, which is then sent to your\nGoogle Cloud project by using a [Google Cloud exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README.md). The exporter\nconverts the\ntelemetry into a format compatible with the Cloud Trace API, Cloud Monitoring API,\nor Cloud Logging API. Next, they send the transformed data to your\nGoogle Cloud project by issuing an API command.\n\nThe samples show how to do the following:\n\n1. Configure OpenTelemetry to collect metrics and traces by using the\n [OpenTelemetry collector](https://opentelemetry.io/docs/collector/).\n\n If you review the samples, you'll notice that the complexity of this step\n is language dependent. For example, for Go, this step configures the\n `main` function to call a function that configures the collection of\n metrics and traces. For Go, the HTTP server and client are also updated.\n2. Configure a logging framework to write [structured logs](/logging/docs/structured-logging).\n\n We recommend that your applications write structured logs, which results\n in the log payload being formatted as a JSON object. For these logs, you can\n construct queries that search specific JSON paths and you can\n index specific fields in the log payload.\n\n Some services, like Google Kubernetes Engine, have built-in agents that scrape\n structured logs and send those logs to your Google Cloud project. Other\n services, like Compute Engine, require that you install an agent, which\n scrapes and sends your logs. If you want to learn about agents you install,\n see [Ops Agent overview](/stackdriver/docs/solutions/agents/ops-agent).\n\n You don't need to install any agents to use these samples.\n3. Configure Docker files. All samples contain the following yaml files:\n\n - `docker-compose.yaml`: Configures the services for the application,\n the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/), and a load generator.\n For example, the service for the OpenTelemetry collector, `otelcol`,\n specifies an image, a volume, and environment variables.\n The endpoint for the OpenTelemetry collector is set by the\n `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable, which is\n specified in the `app` service.\n\n - `otel-collector-config.yaml`: Configures the receivers, exporters,\n processors, and pipelines.\n\n The `telemetry` service defines pipelines for trace, metric, and log\n data. Each pipeline entry specifies a receiver, a processor, and an\n exporter. The same receiver, `otlp`, is used for metrics and traces.\n\n The `exporters` section describes how collected data is exported to\n a Google Cloud project. For all telemetry, a Google Cloud exporter is\n utilized. The exporter converts the telemetry into a format\n compatible with the Cloud Trace API, Cloud Monitoring API, or\n Cloud Logging API. Next, it sends the transformed data to your\n Google Cloud project by issuing an API command.\n - `docker-compose.creds.yaml`: This file optionally mounts a\n Google Cloud credentials file in the `otelcol` container. This file\n is needed when a sample is run on a local machine where the\n [Application Default Credentials (ADC)](/docs/authentication/application-default-credentials) are available\n only as a file.\n\nRequired permissions\n--------------------\n\nIf you run the samples in the Cloud Shell, on Google Cloud\nresources, or on a local development environment, then the permissions listed\nin this section are sufficient. For production applications, typically a\nservice account provides the credentials to write log, metric, and trace\ndata.\n\n-\n\n To get the permissions that\n you need to for the sample applications to write log, metric, and trace data,\n\n ask your administrator to grant you the\n following IAM roles on your project:\n\n - [Logs Writer](/iam/docs/roles-permissions/logging#logging.logWriter) (`roles/logging.logWriter`)\n - [Monitoring Metric Writer](/iam/docs/roles-permissions/monitoring#monitoring.metricWriter) (`roles/monitoring.metricWriter`)\n - [Cloud Trace Agent](/iam/docs/roles-permissions/cloudtrace#cloudtrace.agent) (`roles/cloudtrace.agent`)\n\n\n\u003c!-- --\u003e\n\n-\n\n To get the permissions that\n you need to view your log, metric, and trace data,\n\n ask your administrator to grant you the\n following IAM roles on your project:\n\n - [Logs Viewer](/iam/docs/roles-permissions/logging#logging.viewer) (`roles/logging.viewer`)\n - [Monitoring Viewer](/iam/docs/roles-permissions/monitoring#monitoring.viewer) (`roles/monitoring.viewer`)\n - [Cloud Trace User](/iam/docs/roles-permissions/cloudtrace#cloudtrace.user) (`roles/cloudtrace.user`)\n\n\n For more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\n You might also be able to get\n the required permissions through [custom\n roles](/iam/docs/creating-custom-roles) or other [predefined\n roles](/iam/docs/roles-overview#predefined).\n\nRequired APIs\n-------------\n\nThe following provides information about the APIs required to send\ntelemetry data to a Google Cloud project: \n\n### Google Cloud console\n\n\nEnable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com,monitoring.googleapis.com,cloudtrace.googleapis.com)\n\n\u003cbr /\u003e\n\n### Google Cloud CLI\n\n\nEnable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com,monitoring.googleapis.com,cloudtrace.googleapis.com)\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Go sample](/trace/docs/setup/go).\n- [Java sample](/trace/docs/setup/java).\n- [Node.js sample](/trace/docs/setup/nodejs).\n- [Python sample](/trace/docs/setup/python)."]]
