Übersicht über Beispiele für die collectorbasierte Instrumentierung

In diesem Dokument wird die Struktur der Instrumentierungsbeispiele beschrieben, die für die Sprachen Go, Java, Node.js und Python bereitgestellt werden. Diese Beispiele bieten eine Anleitung zur Instrumentierung einer Anwendung für die Verwendung des OpenTelemetry SDK und eines OpenTelemetry-Collectors.

Die Instrumentierung in diesen Beispielen, einschließlich der Verwendung des OpenTelemetry SDK und des In-Process-OTLP-Exporters des SDK, ist anbieterunabhängig. Der In-Process-Exporter sendet Telemetriedaten an den OpenTelemetry-Collector, der diese Daten empfängt und dann an Ihr Google Cloud Projekt weiterleitet. Der Collector enthält die Bindung zu Google Cloud. In diesen Beispielen werden Google Cloud Exporter verwendet, um Log- und Messwertdaten an Ihr Projekt zu senden. Trace-Daten werden jedoch über die Telemetry API an Ihr Projekt gesendet.

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

  • Unter Von Trace-Exporter zu OTLP-Endpunkt migrieren wird beschrieben, wie Sie die In-Process-Instrumentierung verwenden, um Trace-Daten direkt an Ihr Google Cloud Projekt zu senden.

    Wir empfehlen, einen OpenTelemetry-Collector zu verwenden, um Ihre Telemetriedaten zu exportieren, wenn Ihre Umgebung die Verwendung eines Collectors unterstützt. Wenn Sie keinen Collector verwenden können, müssen Sie einen In-Process-Exporter verwenden, der Daten direkt an Ihr Google Cloud Projekt sendet.

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

  • Unter Ops-Agent und OpenTelemetry Protocol (OTLP) verwenden wird beschrieben, wie Sie den Ops-Agent und einen OTLP-Empfänger konfigurieren können, um Messwerte und Traces aus einer Anwendung zu erfassen.

Funktionsweise der Beispiele

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 konfiguriert, um strukturierte Logs zu schreiben, und der OpenTelemetry-Collector wird so konfiguriert, dass er aus dem Stream der Anwendung liest.stdout 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 der 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 Telemetriedaten der Anwendung zu empfangen und anzureichern. Ein Exporter sendet diese Daten dann an Ihr Google Cloud Projekt. Die Beispielanwendungen senden Messwert- und Trace-Daten über die Telemetry API an Ihr Projekt, die das OTLP-Format unterstützt.

In den Beispielen wird Folgendes gezeigt:

  1. Konfigurieren Sie OpenTelemetry, um Messwerte und Traces mit dem OpenTelemetry Collector zu erfassen.

    Die Komplexität dieses Schritts ist sprachabhängig. Bei Go wird 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.

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

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

    Einige Dienste wie die Google Kubernetes Engine haben integrierte Agents, die strukturierte Logs extrahieren und an Ihr Google Cloud Projekt senden. Bei anderen Diensten wie Compute Engine müssen Sie einen Agent installieren, der Ihre Logs extrahiert und sendet. Weitere Informationen zu Agents, die Sie installieren, finden Sie unter Ops-Agent – Übersicht.

    Sie müssen keine Agents installieren, um diese Beispiele zu verwenden.

  3. 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 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: Konfiguriert OpenTelemetry:

      • In den Beispielen wird der Empfänger otlp für Messwert- und Trace-Daten und der Empfänger filelog für Logdaten verwendet.

      • In den Beispielen wird der otlphttp Exporter für Messwert- und Trace-Daten, und der Google Cloud Exporter für Logdaten verwendet.

        Der Exporter otlphttp sendet Daten über die Telemetry API an Ihr Projekt, die OTLP unterstützt. Der Google Cloud Exporter konvertiert Ihre Logdaten in ein Format, das mit der Cloud Logging API kompatibel ist, und sendet die transformierten Daten dann mit einem API-Befehl an Ihr Google Cloud Projekt.

    • docker-compose.creds.yaml: Mit dieser Datei kann optional eine Google Cloud Anmeldedatendatei im otelcol Container eingebunden werden. Sie benötigen diese Datei, wenn Sie ein Beispiel auf einem lokalen Computer ausführen, auf dem Standardanmeldedaten für Anwendungen (ADC) nur als Datei verfügbar sind.

Erforderliche Berechtigungen

  • Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, damit die Beispielanwendungen Log-, Messwert- und Trace-Daten schreiben können:

    Diese Berechtigungen reichen aus, wenn Sie das Beispiel in der Cloud Shell, auf Google Cloud Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen. Informationen zum Konfigurieren eines Kontingentprojekts finden Sie unter Kontingentprojekt festlegen.

Erforderliche APIs

Aktivieren Sie die Cloud Logging, Cloud Monitoring, Cloud Trace und Telemetry APIs:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen. 

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

Nächste Schritte

Weitere Informationen zu Collectors finden Sie unter Von Google entwickelter OpenTelemetry-Collector.

Sehen Sie sich die Beispiele an, in denen Collector-basierte Exporte verwendet werden.