This page provides a brief overview on how to instrument your application for Cloud Trace. For detailed instructions on setting up Cloud Trace, go to the language-specific setup pages.
Cloud Trace provides distributed tracing data for your applications. After instrumenting your application, you can inspect latency data for a single request and view the aggregate latency for an entire application in the Cloud Trace console.
Instrumenting tracing for applications
There are three ways to implement tracing for your applications:
Use OpenTelemetry and the associated Cloud Trace client library. This is the recommended way to instrument your applications.
Use OpenCensus if an OpenTelemetry client library is not available for your language.
Use the Cloud Trace API and write custom methods to send tracing data to Cloud Trace.
Recommended client libraries
OpenTelemetry is not available for all languages yet. See the following table for the recommended client library for the language you're using:
|Language||Recommended client library|
|C# .NET||Cloud Trace API|
|Ruby||Cloud Trace API|
When to instrument your application
For your application to submit traces to Cloud Trace, it must be instrumented. You can instrument your code by using the Google client libraries. However, it's recommended that you use OpenTelemetry or OpenCensus to instrument your application. These are open source tracing packages. OpenTelemetry is actively in development and is the preferred package.
The Cloud 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.
The current active span can be accessed by the global trace context, which is sometimes wrapped in a Tracer object. You can add information relevant to your application by using custom annotations and tags to existing spans, or you can create new child spans with their own annotations and tags to trace the application's behavior with finer granularity. Because the context is global, multi-threaded applications that update the context must use appropriate isolation.
You don't need to provide authentication credentials to your application or specify your Google Cloud project ID in your application when you are running on Google Cloud. For some languages, you do need to specify your Google Cloud project ID even if you are running on Google Cloud.
If you are running outside of Google Cloud, you need to provide authentication credentials to your application. You also need to specify your Google Cloud project ID in your application.
For details, go to the language-specific setup pages.
Configuring your Google Cloud project
To use Cloud Trace, your Google Cloud project must have the Cloud Trace API enabled. This setting lets your Google Cloud project receive trace data from authenticated sources.
By default, Google Cloud projects have the Cloud Trace API enabled and you don't need to take any action. If you have modified the access scopes of your Google Cloud project and want to verify your settings, do the following:
From the Google Cloud 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.
Cloud Trace doesn't sample every request. For example, if you use Java and OpenCensus, then only 1 request out of every 10,000 is traced. If you are using App Engine, requests are sampled at a rate of 0.1 requests per second for each App Engine instance. If you use the Cloud Trace API, then you can configure customer rates. Some packages, such as the Java OpenCensus package, support configuring the sampling rate.
Forcing a request to be traced
To force a specific request to be traced, add an
header to the request. The header specification is:
TRACE_IDis a 32-character hexadecimal value representing a 128-bit number. It should be unique between your requests, unless you intentionally want to bundle the requests together. You can use UUIDs.
SPAN_IDis the decimal representation of the (unsigned) span ID. It should be randomly generated and unique in your trace. For subsequent requests, set
SPAN_IDto the span ID of the parent request. See the description of
TraceSpan(REST, RPC) for more information about nested traces.
1to trace this request. Specify
0to not trace the request.
For example, to force a trace with curl:
curl "http://www.example.com" --header "X-Cloud-Trace-Context: 105445aa7843bc8bf206b12000100000/1;o=1"
For detailed configuration information, samples, and links to GitHub and other open source repositories, go to the setup page for your language: