Ü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 dazu, wie Sie eine Anwendung instrumentieren, um das OpenTelemetry SDK und einen OpenTelemetry-Collector zu verwenden.

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

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 In-Process-Instrumentierung 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 In-Process-Exporter verwenden, der Daten direkt an Ihr Google Cloud -Projekt sendet.

  • Im Artikel 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. Sie können Beispiele verwenden, um Ihre Trace- und Messwertdaten zu korrelieren.

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

öffnen.

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 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 Telemetriedaten der Anwendung zu empfangen und anzureichern. Die Daten werden dann mit einem Google Cloud -Exporter an IhrGoogle 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 einen API-Befehl an IhrGoogle Cloud -Projekt gesendet.

In den Beispielen wird Folgendes gezeigt:

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

    Wenn Sie sich die Beispiele ansehen, werden Sie feststellen, dass die Komplexität dieses Schritts sprachabhängig ist. In Go wird in diesem Schritt 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, wodurch die Log-Nutzlast als JSON-Objekt formatiert wird. Für diese Logs können Sie Abfragen erstellen, mit denen Sie bestimmte JSON-Pfade durchsuchen, und bestimmte Felder in der Log-Nutzlast indexieren.

    Einige Dienste wie Google Kubernetes Engine haben integrierte Agents, die strukturierte Logs erfassen und an Ihr Google Cloud -Projekt senden. Für andere Dienste wie Compute Engine müssen Sie einen Agent installieren, der Ihre Logs erfasst und sendet. Informationen zu den von Ihnen installierten Agents finden Sie in der Übersicht zum Ops-Agent.

    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 Load Generator. 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. Dieser Collector gibt Empfänger, Exporteure, Prozessoren und Pipelines an.

      Der telemetry-Dienst definiert Pipelines für Trace-, Messwert- und Logdaten. Jeder Pipelineeintrag gibt einen Empfänger, einen Prozessor und einen Exporteur 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 werdenGoogle Cloud -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 IhrGoogle Cloud -Projekt. Im Gegensatz dazu werden Trace-Daten mithilfe der Telemetry API, die OTLP unterstützt, an Ihr Projekt gesendet.

    • docker-compose.creds.yaml: Mit dieser Datei wird optional eineGoogle Cloud -Datei mit Anmeldedaten im otelcol-Container bereitgestellt. Diese Datei ist erforderlich, wenn ein Beispiel auf einem lokalen Computer ausgeführt wird, auf dem die Standardanmeldedaten für Anwendungen (Application Default Credentials, 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 Tracedaten schreiben können:

    Wenn Sie die Beispiele in Cloud Shell, auf Google Cloud Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die vorherigen Berechtigungen aus, um Log-, Messwert- und Tracedaten zu schreiben. Für Produktionsanwendungen werden die erforderlichen Anmeldedaten in der Regel über ein Dienstkonto bereitgestellt.

Erforderliche APIs

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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.