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:
You can use OpenTelemetry and the associated Cloud Trace exporter for the following programming languages:
OpenTelemetry SDK Example C++ SDK C++ example Go SDK Trace and metrics example and Trace example Java SDK Trace and metrics example and Trace example Node.js SDK Trace and metrics example and Trace example Python SDK Trace and metrics example and Trace example Ruby SDK See OpenTelemetry documentation. If you are writing applications that run on Compute Engine, then you can use the Ops Agent and the OpenTelemetry Protocol (OTLP) receiver to collect traces and metrics from your application. The Ops Agent can also collect logs, but not by using OTLP. For more information, see Use the Ops Agent and OTLP and Ops Agent overview.
You can use the client libraries or directly call the Cloud Trace API to send tracing data to Cloud Trace. However, we recommend that you use OpenTelemetry when your language is supported by that library.
You can configure a Zipkin server to receive traces from Zipkin clients and then forward those traces to Cloud Trace for analysis. For information about this approach, see Using Cloud Trace with Zipkin.
You can configure Spring Boot applications to forward the trace data it collects to Cloud Trace. For information about this procedure, see Spring Cloud for Google Cloud: Cloud Trace.
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 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.
Enable the required API.
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:
OpenTelemetry examples:
Client library examples: