You can enable Stackdriver Trace for Java applications
by using OpenCensus. OpenCensus is
a set of instrumentation libraries for collecting trace and metric data that
work with multiple backends. For the latest details about OpenCensus
for Java, along with additional documentation and examples, go to
census-instrumentation/opencensus-java
.
Installing the library
To collect traces, add OpenCensus tracing and the Stackdriver exporter to your application's Maven or Gradle file:
Maven
Gradle
compile 'io.opencensus:opencensus-api:0.12.2' compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.12.2' runtime 'io.opencensus:opencensus-impl:0.12.2'
Configuring the Stackdriver exporter
In order to export the collected Trace data, use a
StackdriverTraceExporter
object:
If you are running on Google Cloud infrastructure, then
you don't need to call setProjectID
and supply your Google Cloud
project ID. If you don't set this field, the client library for Java
automatically gathers this data from a Google Cloud metadata server.
If you aren't running on Google Cloud infrastructure, then you must supply your Google Cloud project ID to your application.
Regardless of your infrastructure,
when you don't explicitly set the Google Cloud project ID,
the google-cloud
Java library, which is invoked by OpenCensus,
automatically determines if
the environment variable GOOGLE_CLOUD_PROJECT
is set, and if so, the
library uses the value of GOOGLE_CLOUD_PROJECT
as your Google Cloud
project ID. For more information, go to
google-cloud-library
specifying a project id.
To set the environment variable, do the following:
Linux or macOS
export GOOGLE_CLOUD_PROJECT=your-project-id
Windows
set GOOGLE_CLOUD_PROJECT=your-project-id
PowerShell:
$env:GOOGLE_CLOUD_PROJECT="your-project-id"
Add a custom Trace span
While the OpenCensus library contains automatic integrations for several popular web and RPC frameworks, you can also create custom traces:
Enabling full sampling
By default, only 1 in 10,000 traces is sampled.
In a developer environment, this sampling rate might be too slow to show you
trace data. You can use the alwaysSample
option to sample all traces.
To enable full sampling, use the setSampler
method and specify the
alwaysSample
option:
Overriding automatic authentication
With Java, you can override the automatic authentication and project selection. For example, the following sample illustrates how to create an exporter whose credentials expire 60 seconds from creation time:
Configuring your platform
You can use Trace on Google Cloud and when your application runs outside of Google Cloud.
Running on Google Cloud
When your application is running on Google Cloud, your application is automatically authenticated and you don't need to provide authentication credentials. However, you do need to ensure that your Google Cloud platform has the Stackdriver Trace API access scope enabled.
For the following configurations, the default settings for the access scopes have the Stackdriver Trace API enabled:
- App Engine flexible environment
App Engine standard environment
Google Kubernetes Engine
Compute Engine
If you use custom access scopes, then you must ensure that
Stackdriver Trace API access scope
enabled. For gcloud
users, specify access scopes using the --scopes
flag
and include the trace.append
Stackdriver Trace API access scope.
For example, to create a GKE cluster with only
the Stackdriver 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
When your application is running outside of Google Cloud, 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 provide these credentials
by setting the GOOGLE_APPLICATION_CREDENTIALS
environment variable:
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 Cloud Console Trace Viewer.