Java und OpenTelemetry

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Java-Anwendungen mithilfe von OpenTelemetry erfassen möchten. OpenTelemetry bietet eine Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten. Diese Bibliotheken funktionieren mit mehreren Back-Ends. So erfassen Sie Traces mit OpenTelemetry und Java:

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung für den Export von Spans nach Cloud Trace konfigurieren
  • Konfigurieren Sie Ihre Plattform.

Releaseinformationen finden Sie hier:

Aktuelle Informationen zu OpenTelemetry für Java sowie zusätzliche Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweis

  • Sie müssen Java 8 oder höher verwenden.
  • Prüfen Sie, ob die Cloud Trace API für Ihr Google Cloud-Projekt aktiviert ist:

    1. Klicken Sie auf die folgende Schaltfläche oder wählen Sie in der Google Cloud Console APIs &Dienste und dann Cloud Trace API aus:

      Zur Trace API

    2. Wenn auf der Seite Cloud Trace API eine Schaltfläche mit der Bezeichnung Aktivieren angezeigt wird, klicken Sie darauf. Wenn diese Schaltfläche nicht angezeigt wird, ist die Cloud Trace API für das ausgewählte Projekt aktiviert.

OpenTelemetry-Pakete installieren

Fügen Sie das OpenTelemetry-Tracing und den Cloud Trace Exporter für OpenTelemetry der Maven- oder Gradle-Datei Ihrer Anwendung hinzu, um Traces zu erfassen:

  • Eine zuletzt veröffentlichte Liste von OpenTelemetry-Abhängigkeiten finden Sie unter Maven und Gradle.

  • Informationen zu den erforderlichen Exporter-Abhängigkeiten finden Sie in der folgenden Tabelle:

    Maven

    <dependency>
      <groupId>com.google.cloud.opentelemetry</groupId>
      <artifactId>exporter-trace</artifactId>
      <version>0.15.0</version>
    </dependency>
    

    Die vorherigen Anweisungen geben eine Exporter-Version an. Achten Sie darauf, dass Sie die neueste Exporter-Version auswählen.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'
    

    Die vorherige Anweisung gibt eine Exporter-Version an. Achten Sie darauf, dass Sie die neueste Exporter-Version auswählen.

Export von Spans nach Cloud Trace konfigurieren

Verwenden Sie zum Exportieren der erfassten Trace-Daten ein TraceExporter-Objekt. Im Folgenden wird gezeigt, wie dieses Objekt mit einer Standardkonfiguration erstellt wird:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Sie können auch eine Konfiguration angeben und diese dann an den Exporter übergeben. Der folgende Code legt beispielsweise das Google Cloud-Projekt fest:

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

Nachdem der Exporter konfiguriert wurde, legen Sie TracerProvider fest:

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

Im vorherigen Beispiel konfiguriert der Aufruf von BatchSpanProcessor den Anbieter so, dass Spans mit einem Hintergrundprozess gesendet werden. Wir empfehlen, diese Konfiguration zu verwenden, es sei denn, Sie verwenden Cloud Run. Cloud Run unterstützt keine Hintergrundprozesse.

Informationen zum Festlegen von Authentifizierungsfeldern finden Sie im Abschnitt zur Einrichtung des Cloud Trace-Exporters für OpenTelemetry.

Spans erstellen

Wie Sie Ihre Anwendung für die Erfassung von Trace-Spans konfigurieren, erfahren Sie unter OpenTelemetry-Tracing. Auf dieser Seite wird beschrieben, wie Sie die folgenden Schritte ausführen:

  • Span erstellen
  • Verschachtelte Spans erstellen
  • Span-Attribute festlegen
  • Spans mit Ereignissen erstellen
  • Spans mit Links erstellen

Stichproben konfigurieren

Informationen zum Konfigurieren, wenn Traces als Stichprobe erfasst werden, finden Sie unter OpenTelemetry-Sampler. Auf dieser Seite werden die Stichprobenoptionen beschrieben, die Ihnen zur Verfügung stehen.

Beispielanwendung

Eine Beispielanwendung finden Sie unter TraceExporterExample.java.

Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

  • Flexible App Engine-Umgebung
  • App Engine-Standardumgebung

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

  • Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mithilfe der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.

  • Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle "Cloud Trace-Agent" enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen für die Suche nach den Anmeldedaten Ihrer Anwendung.

Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

  • Führen Sie gcloud auth application-default login aus

  • Legen Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem ab. Im Folgenden sind die Standardpfade für Windows und Linux aufgeführt:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Traces ansehen

Nach der Bereitstellung können Sie die Traces in der Trace-Anzeige der Google Cloud Console ansehen.

Trace-Anzeige öffnen

Problembehebung

Informationen zur Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.

Ressourcen