Cloud Trace für Java einrichten

Sie können Cloud Trace für Java-Anwendungen mithilfe von OpenCensus aktivieren. OpenCensus ist eine Sammlung von Instrumentenbibliotheken zum Erfassen von Trace- und Messwertdaten, die mit mehreren Back-Ends funktionieren. Die neuesten Informationen zu OpenCensus für Java sowie weitere Dokumentation und Beispiele finden Sie unter census-instrumentation/opencensus-java.

Bibliothek installieren

Fügen Sie das OpenCensus-Tracing und den Stackdriver-Exporter der Maven- oder Gradle-Datei Ihrer Anwendung hinzu, um Traces zu erfassen:

Maven

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.28.3</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.28.3</version>
  <exclusions>
    <exclusion>
      <groupId>io.grpc</groupId>
      <artifactId>grpc-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.28.3</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.10</version>
</dependency>
<dependency>
  <groupId>com.google.api</groupId>
  <artifactId>gax-grpc</artifactId>
  <version>2.4.1</version>
</dependency>

Gradle

compile 'io.opencensus:opencensus-api:0.28.3'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.28.3'
runtime 'io.opencensus:opencensus-impl:0.28.3'

Stackdriver-Exporter konfigurieren

Verwenden Sie zum Exportieren der erfassten Trace-Daten ein StackdriverTraceExporter-Objekt:

public static void createAndRegisterGoogleCloudPlatform(String projectId) throws IOException {
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder().setProjectId(projectId).build());
}

Wenn Sie mit der Google Cloud-Infrastruktur arbeiten, müssen Sie setProjectID nicht aufrufen und Ihre Google Cloud-Projekt-ID angeben. Wenn Sie dieses Feld nicht festlegen, erfasst die Clientbibliothek für Java diese Daten automatisch von einem Google Cloud-Metadatenserver.

Wenn Sie nicht die Google Cloud-Infrastruktur ausführen, müssen Sie Ihre Google Cloud-Projekt-ID für Ihre Anwendung angeben.

Wenn Sie die Google Cloud-Projekt-ID nicht explizit festlegen, legt die Java-Bibliothek google-cloud automatisch fest, ob die Umgebungsvariable GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn diese Variable festgelegt ist, verwendet die Bibliothek den Wert von GOOGLE_CLOUD_PROJECT als Google Cloud-Projekt-ID.

Weitere Informationen finden Sie unter google-cloud-library-Projekt-ID angeben. So legen Sie die Umgebungsvariable fest:

Linux oder macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

Benutzerdefinierten Trace-Span hinzufügen

Die OpenCensus-Bibliothek enthält zwar automatische Integrationen für mehrere gängige Web-Frameworks und RPC-Frameworks, Sie können aber auch benutzerdefinierte Traces erstellen:

private static final Tracer tracer = Tracing.getTracer();

public static void doWork() {
  // Create a child Span of the current Span.
  try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

private static void doInitialWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Doing initial work");
  // ...
}

private static void doFinalWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Hello world!");
  // ...
}

Integration mit Cloud Logging konfigurieren

Informationen zum Senden von Cloud Trace-Daten an Cloud Logging finden Sie unter Integration in Cloud Logging.

Vollständiges Abtasten aktivieren

Standardmäßig wird von 10.000 Traces nur ein Trace als Stichprobe verwendet.

In einer Entwicklerumgebung ist diese Sampling-Rate möglicherweise zu langsam, um Ihnen Trace-Daten anzuzeigen. Wenn die Probenahme aller Traces erfolgen soll, verwenden Sie die Option alwaysSample.

Verwenden Sie die Methode setSampler und geben Sie die Option alwaysSample an, um das vollständige Probenahme zu aktivieren:

public static void doWorkFullSampled() {
  try (Scope ss =
      tracer
          .spanBuilder("MyChildWorkSpan")
          .setSampler(Samplers.alwaysSample())
          .startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

Automatische Authentifizierung überschreiben

Sie können die automatische Authentifizierung und die Projektauswahl überschreiben. Im folgenden Beispiel wird gezeigt, wie Sie einen Exporteur erstellen, dessen Anmeldedaten 60 Sekunden nach der Erstellung ablaufen:

public static void createAndRegisterWithToken(String accessToken) throws IOException {
  Date expirationTime = DateTime.now().plusSeconds(60).toDate();

  GoogleCredentials credentials =
      GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder()
          .setProjectId("MyStackdriverProjectId")
          .setCredentials(credentials)
          .build());
}

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 der 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.

  • Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Zugriffsbereich trace.append der Cloud Trace API hinzu. 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