Übersicht über Beispiele für die collectorbasierte Instrumentierung

Wenn Sie Ihren Anwendungscode herstellerneutral halten und gleichzeitig Telemetriedaten erfassen und an Google Cloudsenden möchten, können Sie die OpenTelemetry-Collector-basierten Instrumentierungsbeispiele für Go, Java, Node.js und Python verwenden.

In diesen Beispielen wird gezeigt, wie Sie ein prozessinternes OpenTelemetry SDK konfigurieren, um Messwerte, Logs und Traces in einen lokalen OpenTelemetry-Collector zu exportieren, der Ihre Telemetriedaten an Google Cloudweiterleitet. Die Beispiele senden Log-, Messwert- und Trace-Daten im OTLP-Format (OpenTelemetry Protocol) über die Telemetry API an Ihr Google Cloud Projekt.

Funktionsweise der Beispiele

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 so konfiguriert, dass strukturierte Logs geschrieben werden, und der OpenTelemetry-Collector wird so konfiguriert, dass er aus dem stdout-Stream der Anwendung liest. 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 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 dann an Ihr Google Cloud -Projekt. In den Beispielen werden Log-, Messwert- und Trace-Daten mithilfe der Telemetry API, die das OTLP-Format unterstützt, an Ihr Projekt gesendet.

In den Beispielen wird Folgendes gezeigt:

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

    Die Komplexität dieses Schritts hängt von der Sprache ab. In Go aktualisieren Sie beispielsweise die Funktion main, um die Telemetrieerfassung zu initialisieren und den HTTP-Server und -Client zu konfigurieren.

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

    Wir empfehlen, dass Ihre Anwendungen strukturierte Logs schreiben, die die Log-Nutzlast als JSON-Objekt formatieren. Für diese Logs können Sie Abfragen erstellen, die bestimmte JSON-Pfade durchsuchen, 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. Informationen zu den von Ihnen installierten Agents 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. 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 den OpenTelemetry-Collector:

      • 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 Log-, Messwert- und Trace-Daten verwendet.

        Der otlphttp-Exporter sendet Daten mithilfe der Telemetry API, die OTLP unterstützt, an Ihr Projekt.

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

Erforderliche Berechtigungen

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

    Diese Berechtigungen sind ausreichend, wenn Sie das Beispiel in 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, falls sie noch nicht aktiviert sind:

Erforderliche Rollen zum Aktivieren von APIs

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 Inhaberrolle (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

Vielleicht interessieren Sie sich für andere Beispiele, die verschiedene Konfigurationen veranschaulichen:

  • Unter Vom Trace-Exporter zum OTLP-Endpunkt migrieren wird beschrieben, wie Sie mit prozessinterner Instrumentierung Trace-Daten direkt an Ihr Google Cloud -Projekt senden.

    Wir empfehlen, einen OpenTelemetry-Collector zum Exportieren Ihrer Telemetriedaten zu verwenden, 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 Exemplars korrelieren wird beschrieben, wie Sie eine Go-Anwendung so konfigurieren, dass Exemplars generiert werden. Ein Beispiel ist ein Beispieldatenpunkt, der an einen Messwertdatenpunkt angehängt ist. Mit Beispielen können Sie Ihre Trace- und Messwertdaten korrelieren.

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

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.