Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
In diesem Dokument wird die Struktur der Instrumentierungsbeispiele beschrieben, die für die Sprachen Go, Java, Node.js und Python bereitgestellt werden.
Diese Beispiele enthalten Anleitungen zum Instrumentieren einer Anwendung.
Möglicherweise interessieren Sie sich für andere Beispiele, die verschiedene Konfigurationen veranschaulichen:
Im Artikel Messwerte und Traces mithilfe von Beispielen korrelieren wird beschrieben, wie Sie eine Go-Anwendung so konfigurieren, dass Beispiele generiert werden.
Ein Beispiel ist ein Beispieldatenpunkt, der an einen Messwertdatenpunkt angehängt ist.
Sie können Beispiele verwenden, um Ihre Trace- und Messwertdaten zu korrelieren.
In den Beispielen für Go, Java, Node.js und Python wird das OpenTelemetry-Protokoll verwendet, um Trace- und Messwertdaten zu erfassen.
In den Beispielen wird ein Logging-Framework zum Schreiben von strukturierten Logs konfiguriert und der OpenTelemetry Collector ist so konfiguriert, dass er aus dem stdout-Stream der Anwendung liest. Empfehlungen für Frameworks finden Sie unter Instrumentierungsansatz auswählen.
Die Anwendungen werden mit Docker erstellt und bereitgestellt. Sie müssen Docker nicht verwenden, wenn Sie eine Anwendung mit OpenTelemetry instrumentieren.
Sie können die Beispiele in Cloud Shell, auf Google Cloud-Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen.
Detailanalyse
In den Beispielen wird der OpenTelemetry Collector als Sidecar verwendet, um die Telemetrie der Anwendung zu empfangen und anzureichern. Die Daten werden dann mit einem Google Cloud -Exporter an IhrGoogle Cloud -Projekt gesendet. Der Exporter konvertiert die Telemetriedaten in ein Format, das mit der Cloud Trace API, der Cloud Monitoring API oder der Cloud Logging API kompatibel ist. Anschließend senden sie die transformierten Daten mit einem API-Befehl an IhrGoogle Cloud -Projekt.
In den Beispielen wird Folgendes gezeigt:
Konfigurieren Sie OpenTelemetry so, dass Messwerte und Traces mit dem OpenTelemetry Collector erfasst werden.
Wenn Sie sich die Beispiele ansehen, werden Sie feststellen, dass die Komplexität dieses Schritts sprachabhängig ist. In Go wird in diesem Schritt beispielsweise die Funktion main so konfiguriert, dass eine Funktion aufgerufen wird, die die Erfassung von Messwerten und Traces konfiguriert. Für Go werden auch der HTTP-Server und ‑Client aktualisiert.
Konfigurieren Sie ein Logging-Framework, um strukturierte Logs zu schreiben.
Wir empfehlen, dass Ihre Anwendungen strukturierte Logs schreiben, wodurch die Log-Nutzlast als JSON-Objekt formatiert wird. Für diese Logs können Sie Abfragen erstellen, mit denen Sie bestimmte JSON-Pfade durchsuchen, und bestimmte Felder in der Log-Nutzlast indexieren.
Einige Dienste wie Google Kubernetes Engine haben integrierte Agents, die strukturierte Logs erfassen und an Ihr Google Cloud -Projekt senden. Für andere Dienste wie Compute Engine müssen Sie einen Agent installieren, der Ihre Logs erfasst und sendet. Informationen zu den von Ihnen installierten Agents finden Sie in der Übersicht zum Ops-Agent.
Sie müssen keine Agents installieren, um diese Beispiele zu verwenden.
Konfigurieren Sie Docker-Dateien. Alle Beispiele enthalten die folgenden YAML-Dateien:
docker-compose.yaml: Konfiguriert die Dienste für die Anwendung, den OpenTelemetry Collector und einen Load Generator.
Der Dienst für den OpenTelemetry Collector, otelcol, gibt beispielsweise ein Image, ein Volume und Umgebungsvariablen an.
Der Endpunkt für den OpenTelemetry Collector wird durch die Umgebungsvariable OTEL_EXPORTER_OTLP_ENDPOINT festgelegt, die im Dienst app angegeben ist.
otel-collector-config.yaml: Konfiguriert die Empfänger, Exporter, Prozessoren und Pipelines.
Im telemetry-Dienst werden Pipelines für Trace-, Messwert- und Logdaten definiert. Jeder Pipelineeintrag gibt einen Empfänger, einen Prozessor und einen Exporteur an. Für Messwerte und Traces wird derselbe Empfänger, otlp, verwendet.
Im Abschnitt exporters wird beschrieben, wie erfasste Daten in ein Google Cloud -Projekt exportiert werden. Für alle Telemetriedaten wird ein Google Cloud -Exporter verwendet. Der Exporter konvertiert die Telemetriedaten in ein Format, das mit der Cloud Trace API, der Cloud Monitoring API oder der Cloud Logging API kompatibel ist. Anschließend werden die transformierten Daten durch Ausführen eines API-Befehls an IhrGoogle Cloud -Projekt gesendet.
docker-compose.creds.yaml: Mit dieser Datei wird optional eineGoogle Cloud -Datei mit Anmeldedaten im otelcol-Container bereitgestellt. Diese Datei ist erforderlich, wenn ein Beispiel auf einem lokalen Computer ausgeführt wird, auf dem die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) nur als Datei verfügbar sind.
Erforderliche Berechtigungen
Wenn Sie die Beispiele in Cloud Shell, auf Google Cloud-Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die in diesem Abschnitt aufgeführten Berechtigungen aus. Bei Produktionsanwendungen werden die Anmeldedaten zum Schreiben von Log-, Messwert- und Tracedaten in der Regel von einem Dienstkonto bereitgestellt.
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie für die Beispielanwendungen zum Schreiben von Log-, Messwert- und Tracedaten benötigen:
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen Ihrer Log-, Messwert- und Tracedaten benötigen:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-12 (UTC)."],[],[],null,["# Instrumentation samples overview\n\nThis document describes the structure of the instrumentation samples provided\nfor the [Go](/stackdriver/docs/instrumentation/setup/go), [Java](/stackdriver/docs/instrumentation/setup/java),\n[Node.js](/stackdriver/docs/instrumentation/setup/nodejs), and [Python](/stackdriver/docs/instrumentation/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](/stackdriver/docs/instrumentation/setup/go).\n- [Java sample](/stackdriver/docs/instrumentation/setup/java).\n- [Node.js sample](/stackdriver/docs/instrumentation/setup/nodejs).\n- [Python sample](/stackdriver/docs/instrumentation/setup/python)."]]
