Übersicht über Beispiele für die collectorbasierte Instrumentierung

Damit Ihr Anwendungscode anbieterunabhängig bleibt, während Sie Telemetriedaten an Google Cloudsenden, können Sie die auf OpenTelemetry Collector basierenden Instrumentierungsbeispiele für Go, Java, Node.js und Python verwenden.

In diesen Beispielen wird gezeigt, wie Sie ein OpenTelemetry SDK im Prozess konfigurieren, um Messwerte, Logs und Traces in einen lokalen OpenTelemetry Collector zu exportieren, der Ihre Telemetriedaten an weiterleitet Google Cloud. Die Beispiele senden Messwert- und Tracedaten im OpenTelemetry Protocol-Format (OTLP) mit der Telemetry API an Ihr Google Cloud Projekt und Logdaten mit einem Google Cloud Exporter.

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 stdoutder 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 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 sie dann an Ihr Google Cloud Projekt. Die Beispielanwendungen senden Messwert- und Tracedaten mit der Telemetry API an Ihr Projekt, die das OTLP-Format unterstützt.

In den Beispielen wird Folgendes gezeigt:

  1. OpenTelemetry so konfigurieren, dass Messwerte und Traces mit dem OpenTelemetry Collector erfasst werden.

    Die Komplexität dieses Schritts ist sprachabhängig. In Go aktualisieren Sie beispielsweise die Funktion main, um die Telemetriedatenerfassung zu initialisieren und den HTTP-Server und ‑Client zu konfigurieren.

  2. Ein Logging-Framework konfigurieren, um strukturierte Logs zu schreiben.

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

    Einige Dienste wie die Google Kubernetes Engine haben integrierte Agents, die strukturierte Logs erfassen und an Ihr Google Cloud Projekt senden. Bei anderen Diensten wie Compute Engine müssen Sie einen Agent installieren, der Ihre Logs erfasst 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. 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: Konfiguriert den OpenTelemetry Collector:

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

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

        Der Exporter otlphttp sendet Daten mit der 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 an Ihr Google Cloud Projekt.

    • docker-compose.creds.yaml: Mit dieser Datei wird optional eine Google Cloud Datei mit Anmeldedaten im otelcol Container eingebunden. 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 Tracedaten 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 Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen. 

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

Alternative Instrumentierungsansätze

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

  • Unter Vom Trace-Exporter zum OTLP-Endpunkt migrieren wird beschrieben, wie Sie die Instrumentierung im Prozess verwenden, um Tracedaten 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 Exporter im Prozess 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.

Nächste Schritte

Weitere Informationen zu Collectoren finden Sie unter Google-eigener OpenTelemetry Collector.

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