This page contains general information about instrumenting your application to use Stackdriver Trace.
For all supported languages, you can instrument your application by using the Stackdriver Trace API.
When an OpenCensus library is available for a language, the instructions and sample code use that library and there aren't samples that use the Stackdriver Trace API.
When an OpenCensus library isn't available for a language, the instructions and sample code use the Trace client library.
When to instrument your application
You need to instrument your application when it's running on App Engine, VMs or containers. This includes the following Google Cloud Platform (GCP) platforms:
- Compute Engine
- Google Kubernetes Engine
- App Engine
You also need to instrument your application when it's running on other cloud providers or on-premises.
In the App Engine standard environment, Java 8, Python 2, and PHP 5 applications don't need to use the Stackdriver Trace client libraries. By default, these runtimes automatically send latency data to Stackdriver Trace for requests to application URIs during application runtime. The requests include latency data for round-trip RPC calls to App Engine services. Stackdriver Trace is integrated with all App Engine Admin APIs, with the exception of Cloud SQL.
You don't need to modify your Dockerfile statements for Trace to be able to capture and transmit trace data to your GCP project.
The Trace client libraries typically maintain a global trace context that holds information about the current span, including its trace ID and whether the trace is sampled. These libraries usually create spans on RPC boundaries. However, you might need to create spans if the default creation algorithm isn't sufficient for your needs. When you create spans, you need to access the globally available span and then add information, such as annotations, tags, or custom spans. Due the use of a global context, care needs to be taken in multi-threading situations where you might need to manually propagate the trace context.
In the general case, you don't need to provide authentication credentials to your application or specify your GCP project ID in your application when you are running on GCP. For some languages, you do need to specify your GCP project ID even if you are running on GCP.
If you are running outside of GCP, you need to provide authentication credentials to your application. You also need to specify your GCP project ID in your application.
For details, go to the language-specific setup pages listed in a later section on this page.
Configuring your GCP project
To use Stackdriver Trace, your GCP project must have the Stackdriver Trace API enabled. This setting lets your GCP project receive trace data from authenticated sources.
By default, GCP projects have the Stackdriver Trace API enabled and you don't need to take any action. If you have modified the access scopes of your GCP project and want to verify your settings, do the following:
From the Google Cloud Platform Console, go to APIs and Services:
Click Enable APIs and services
In the search bar, enter Trace API.
If API enabled is displayed, this API is already enabled and there is nothing for you to do. Otherwise, click Enable.
For detailed configuration information, samples, and links to GitHub and other open source repositories, go to the setup page for your language: