Instrument for Cloud Trace

This document provides a brief overview on how to instrument your application for Cloud Trace. For detailed instructions on setting up Cloud Trace, see 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.

When to instrument your application

When trace data isn't automatically captured, you need to instrument your application to collect this data.

You can instrument your application so that it collects application-specific information. Several open-source instrumentation frameworks let you collect metrics, logs, and traces from your application and send that data to any vendor, including Google Cloud. To instrument your application, we recommend that you use a vendor-neutral instrumentation framework that is open source, such as OpenTelemetry, instead of vendor- and product-specific APIs or client libraries.

For information about instrumenting your applications by using vendor-neutral instrumentation frameworks, see Instrumentation and observability.

How to instrument applications

For recommendations about instrumenting your applications to collect logs, metrics, and traces, see Choose an instrumentation approach.

To instrument your applications to collect trace data, you can do any of the following:

When to create spans

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.

When to provide authentication credentials

You generally 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. Also, if you use Autopilot mode for Google Kubernetes Engine, or if you enable Workload Identity, then you must configure your application to use Workload Identity.

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.

How to force a request to be traced

Unless your application always samples every span, it isn't possible, in general, to force a request to be traced end-to-end because each component in an end-to-end request makes its own sampling decision. However, you can influence the decision by adding to the trace header a sampled flag, with this flag set to true. This setting is a hint to child components to sample the request. For more information about trace headers, see Protocols for context propagation.

For downstream components whose code you own, you must determine whether your instrumentation logic respects the sampled flag. For example, when using OpenTelemetry for instrumentation, you can use the ParentBased sampler to ensure that the parent sampled flag is respected.

Google Cloud services that record tracing information to Cloud Trace typically accept the parent sampling flag as a hint; however, most services also rate-limit sampling. Each Google Cloud service determines whether the it supports tracing, how the parent sampling flag is utilized, and the rate limit on sampling.

Enable the Cloud Trace API

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. However, you might need to enable the Cloud Trace API if you have modified the access scopes of your Google Cloud project.

To enable the Cloud Trace API, do the following:

  1. In the navigation panel of the Google Cloud console, select APIs & Services, click Enable APIs and Services, and then enable the Cloud Trace API:

    Go to Cloud Trace API settings

  2. If API enabled is displayed, then the API is already enabled. If not, click the Enable button.

What's next

For detailed configuration information, samples, and links to GitHub and other open source repositories, go to the setup page for your language: