Ü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 mithilfe der 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 zu 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. Diese werden dann mit einem Google Cloud Exporter an Ihr Google 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 werden die transformierten Daten durch Ausführen eines API-Befehls an Ihr Google Cloud Projekt gesendet.

In den Beispielen wird gezeigt, wie Sie Folgendes tun:

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

    Wenn Sie sich die Beispiele ansehen, werden Sie feststellen, dass die Komplexität dieses Schritts von der Sprache abhängt. Bei Go wird beispielsweise die Funktion main so konfiguriert, dass eine Funktion aufgerufen wird, die die Erfassung von Messwerten und Traces konfiguriert. Bei 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, wodurch die Log-Nutzlast als JSON-Objekt formatiert wird. Für diese Logs können Sie Abfragen erstellen, mit denen Sie nach bestimmten JSON-Pfaden suchen, 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 den OpenTelemetry-Collector. Dieser Collector gibt Empfänger, Exporter, Prozessoren und Pipelines an.

      Der Dienst telemetry definiert Pipelines für Trace-, Messwert- und Logdaten. Jeder Pipelineeintrag gibt einen Empfänger, einen Prozessor und einen Exporter 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 Log- und Messwertdaten, Google Cloud werden Exporter verwendet. Diese Exporter konvertieren die Telemetriedaten in ein Format, das mit der entsprechenden API kompatibel ist, und senden die transformierten Daten dann durch Ausführen eines API-Befehls an Ihr Google Cloud Projekt. Trace-Daten werden dagegen mithilfe der Telemetry API an Ihr Projekt gesendet, die OTLP unterstützt.

    • docker-compose.creds.yaml: Mit dieser Datei wird optional eine Google Cloud Datei mit Anmeldedaten im otelcol Container eingebunden. Diese Datei ist erforderlich, wenn ein Beispiel auf einem lokalen Computer ausgeführt wird, auf dem die Standardanmeldedaten für Anwendungen (ADC) nur als Datei verfügbar sind.

Erforderliche Berechtigungen

  • Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, 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.

Erforderliche APIs

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

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. Weitere 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.