Beispiele für Instrumentierung – Übersicht

In diesem Dokument wird die Struktur der Instrumentierungsbeispiele für die Sprachen Go, Java, Node.js und Python beschrieben. Diese Beispiele enthalten eine Anleitung zum Instrumentieren einer Anwendung.

Möglicherweise interessieren Sie sich auch für andere Beispiele, die verschiedene Konfigurationen veranschaulichen:

  • Im Artikel Messwerte und Traces mithilfe von Beispielen korrelieren wird beschrieben, wie Sie eine Go-Anwendung zum Generieren von Musterbeispielen konfigurieren. Ein Beispiel ist ein Beispieldatenpunkt, der an einen Messwertdatenpunkt angehängt ist. Mit Musterbeispielen können Sie Ihre Trace- und Messwertdaten korrelieren.

  • Im Hilfeartikel Ops-Agent und OpenTelemetry Protocol (OTLP) verwenden wird beschrieben, wie Sie den Ops-Agent und einen OTLP-Empfänger so konfigurieren, dass Messwerte und Traces aus einer Anwendung erfasst werden.

Funktionsweise der Samples

In den Beispielen für Go, Java, Node.js und Python werden Trace- und Messwertdaten mit dem OpenTelemetry-Protokoll erfasst. 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 zu ergänzen. Diese wird dann über einen Google Cloud Exporter an Ihr Google Cloud-Projekt gesendet. Der Exporter wandelt die Telemetrie in ein Format um, das mit der Cloud Trace API, der Cloud Monitoring API oder der Cloud Logging API kompatibel ist. Als Nächstes sendet er die transformierten Daten mit einem API-Befehl an Ihr Google Cloud-Projekt.

In den Beispielen wird Folgendes veranschaulicht:

  1. Konfigurieren Sie OpenTelemetry mit dem OpenTelemetry-Collector so, dass Messwerte und Traces erfasst werden.

    Wenn Sie sich die Beispiele ansehen, werden Sie feststellen, dass die Komplexität dieses Schritts von der Sprache abhängt. Bei Go wird mit diesem Schritt beispielsweise die Funktion main so konfiguriert, dass sie eine Funktion aufruft, die die Erfassung von Messwerten und Traces konfiguriert. Bei Go werden auch der HTTP-Server und der Client aktualisiert.

  2. Konfigurieren Sie ein Logging-Framework, um strukturierte Protokolle zu schreiben.

    Wir empfehlen, dass Ihre Anwendungen strukturierte Protokolle schreiben, wodurch die Protokollnutzlast als JSON-Objekt formatiert wird. Für diese Logs können Sie Abfragen erstellen, mit denen bestimmte JSON-Pfade durchsucht werden, und bestimmte Felder in der Lognutzlast indexieren.

    Einige Dienste wie die Google Kubernetes Engine haben integrierte Agenten, die strukturierte Protokolle abrufen und an Ihr Google Cloud-Projekt senden. Bei anderen Diensten wie der Compute Engine müssen Sie einen Agenten installieren, der Ihre Protokolle erfasst und sendet. Informationen zu den von Ihnen installierten Agents finden Sie unter Ops-Agent – Übersicht.

    Sie müssen keine Agenten installieren, um diese Samples zu verwenden.

  3. Docker-Dateien konfigurieren Alle Beispiele enthalten die folgenden YAML-Dateien:

    • docker-compose.yaml: Konfiguriert die Dienste für die Anwendung, den OpenTelemetry Collector und einen Lastgenerator. Für den Dienst für den OpenTelemetry Collector, otelcol, werden beispielsweise ein Image, ein Volume und Umgebungsvariablen angegeben. 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: Hier werden die Empfänger, Exporteure, Prozessoren und Pipelines konfiguriert.

      Der telemetry-Dienst definiert Pipelines für Trace-, Mess- und Protokolldaten. Für jeden Pipelineeintrag werden ein Empfänger, ein Prozessor und ein Exporteur angegeben. Für Messwerte und Traces wird derselbe Empfänger, otlp, verwendet.

      Im Abschnitt exporters wird beschrieben, wie erhobene Daten in ein Google Cloud-Projekt exportiert werden. Für alle Telemetry-Daten wird ein Google Cloud -Export verwendet. Der Exporter konvertiert die Telemetrie in ein Format, das mit der Cloud Trace API, der Cloud Monitoring API oder der Cloud Logging API kompatibel ist. Als Nächstes werden die transformierten Daten über einen API-Befehl an Ihr Google Cloud-Projekt gesendet.

    • docker-compose.creds.yaml: Diese Datei kann optional eineGoogle Cloud -Anmeldedatendatei im otelcol-Container bereitstellen. Diese Datei ist erforderlich, wenn ein Beispiel auf einem lokalen Computer ausgeführt wird, auf dem die Standardanmeldedaten für Anwendungen nur als Datei verfügbar sind.

Erforderliche Berechtigungen

Wenn Sie die Samples 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 stellt in der Regel ein Dienstkonto die Anmeldedaten zum Schreiben von Protokoll-, Messwert- und Ablaufdaten bereit.

  • Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendungen Protokoll-, Mess- und Ablaufdaten schreiben können:

Erforderliche APIs

Im Folgenden finden Sie Informationen zu den APIs, die zum Senden von Telemetry-Daten an ein Google Cloud-Projekt erforderlich sind:

Google Cloud Console

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Google Cloud CLI

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs: 

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

Nächste Schritte