Java und OpenTelemetry

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Java-Anwendungen mithilfe von OpenTelemetry erfassen möchten. OpenTelemetry besteht aus einer Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten. Diese Bibliotheken verwenden mehrere Back-Ends. Gehen Sie wie auf dieser Seite beschrieben vor, um Traces mit OpenTelemetry und Java zu erfassen:

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

Versionshinweise:

Aktuelle Informationen zu OpenTelemetry für Java sowie weitere Dokumentationen 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 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 zum Erfassen von Traces der Maven- oder Gradle-Datei Ihrer Anwendung den OpenTelemetry-Tracing- und Cloud Trace-Exporter für OpenTelemetry hinzu:

  • Eine aktuelle Liste der OpenTelemetry-Abhängigkeiten finden Sie unter Maven und Gradle.

  • Informationen zu den erforderlichen Abhängigkeiten des Exporteurs 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 den neuesten Exporterrelease 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 den neuesten Exporterrelease auswählen.

Exportieren von Spans nach Cloud Trace

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

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Sie können auch eine Konfiguration angeben und diese dann an den Exporter übergeben. Mit dem folgenden Code wird beispielsweise das Google Cloud-Projekt festgelegt:

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

Nachdem der Exporter konfiguriert wurde, legen Sie den 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 Einrichtungsbereich des Cloud Trace-Exporters für OpenTelemetry.

Spans erstellen

Informationen zum Konfigurieren Ihrer Anwendung zum Erfassen von Trace-Spans finden Sie unter Tracing von OpenTelemetry. Auf dieser Seite wird Folgendes beschrieben:

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

Stichprobenerhebung konfigurieren

Informationen zum Konfigurieren, wann Traces erstellt 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, müssen Sie dafür sorgen, dass der Zugriffsbereiche für die Cloud Trace API aktiviert ist:

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

  • gcloud-Nutzer geben Zugriffsbereiche mit dem Flag --scopes an und fügen den Zugriffsbereiche trace.append der Cloud Trace API mit 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 geben diese Anmeldedaten an, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

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 im Trace Viewer der Cloud Console anzeigen.

Trace-Anzeige öffnen

Fehlerbehebung

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

Ressourcen