Java and OpenTelemetry

Stay organized with collections Save and categorize content based on your preferences.

This page is designed for application developers who want to collect Cloud Trace data for Java applications by using OpenTelemetry. OpenTelemetry is a set of instrumentation libraries for collecting trace and metric data; these libraries work with multiple backends. To collect traces with OpenTelemetry and Java, you do the following, as described on this page:

  • Install the OpenTelemetry packages.
  • Configure your application to export spans to Cloud Trace.
  • Configure your platform.

For release information, see the following:

For OpenTelemetry reference content, see the following:

For the latest details about OpenTelemetry for Java, along with additional documentation and examples, see OpenTelemetry.

Before you begin

  • You must use Java 8 or later.
  • Verify that the Cloud Trace API is enabled for your Google Cloud project:

    1. Click the following button or, in the Google Cloud console, select APIs & Services, and then select Cloud Trace API:

      Go to Trace API

    2. On the Cloud Trace API page, if a button labeled Enable is displayed, then click it. If this button isn't displayed, then the Cloud Trace API is enabled for the selected project.

Install the OpenTelemetry packages

To collect traces, add OpenTelemetry tracing and the Cloud Trace exporter for OpenTelemetry to your application's Maven or Gradle file:

  • For the most recently published list of OpenTelemetry dependencies, see Maven and Gradle.

  • For the required exporter dependencies, see the following table:

    Maven

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

    The previous statements specify an exporter version. Ensure that you select the latest exporter release.

    Gradle

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

    The previous statement specifies an exporter version. Ensure that you select the latest exporter release.

Configure the export of spans to Cloud Trace

To export the collected Trace data, use a TraceExporter object. The following illustrates how to create this object with a default configuration:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

You can also specify a configuration and then pass that to the exporter. For example, the following code sets the Google Cloud project:

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

After the exporter is configured, set the TracerProvider:

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

In the previous example, the call to BatchSpanProcessor configures the provider to send spands with a background process. We recommend that you use this configuration unless you are using Cloud Run. Cloud Run doesn't support background processes.

For information about how to set authentication fields, see the setup section of Cloud Trace exporter for OpenTelemetry.

Create spans

For information about how to configure your application to capture trace spans, see OpenTelemetry Tracing. This page describes how to do all of the following:

  • Create a span
  • Create nested spans
  • Set span attributes
  • Create spans with events
  • Create spans with links

Configure sampling

For information about how to configure when traces are sampled, see OpenTelemetry Sampler. This page describes the sampling options that are available to you.

Sample application

For a sample application, see TraceExporterExample.java.

Configure your platform

You can use Cloud Trace on Google Cloud and other platforms.

Running on Google Cloud

When your application is running on Google Cloud, you don't need to provide authentication credentials in the form of a service account to the client library. However, you do need to ensure that your Google Cloud platform has the Cloud Trace API access scope enabled.

For a list of supported Google Cloud environments, see Environment support.

For the following configurations, the default access-scope settings enable the Cloud Trace API:

  • App Engine flexible environment

  • App Engine standard environment

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

If you use custom access scopes, then you must ensure that Cloud Trace API access scope is enabled:

  • For information about how to configure the access scopes for your environment by using the Google Cloud console, see Configuring your Google Cloud project.

  • For gcloud users, specify access scopes using the --scopes flag and include the trace.append Cloud Trace API access scope. For example, to create a GKE cluster with only the Cloud Trace API enabled, do the following:

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

Running locally and elsewhere

If your application is running outside of Google Cloud, then you must provide authentication credentials in the form of a service account to the client library. The service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.

Google Cloud client libraries use Application Default Credentials (ADC) to find your application's credentials.

You can provide these credentials in one of three ways:

  • Run gcloud auth application-default login

  • Place the service account in a default path for your operating system. The following lists the default paths for Windows and Linux:

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

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

  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path to your service account:

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"

Viewing the traces

After deployment, you can view the traces in the Google Cloud console Trace Viewer.

Go to the Trace Viewer page

Troubleshooting

For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.

Resources