Cloud Trace overview

Stay organized with collections Save and categorize content based on your preferences.

Cloud Trace, a distributed tracing system for Google Cloud, helps you understand how long it takes your application to handle incoming requests from users or other applications, and how long it takes to complete operations like RPC calls performed when handling the requests.

Because Cloud Trace collects latency data from App Engine, HTTP(S) load balancers, and applications instrumented with the Cloud Trace API, it can help you answer the following questions:

  • How long does it take my application to handle a given request?
  • Why is it taking my application so long to handle a request?
  • Why do some of my requests take longer than others?
  • What is the overall latency of requests to my application?
  • Has latency for my application increased or decreased over time?
  • What can I do to reduce application latency?
  • What are my application's dependencies?

For information about profiling your application, see Cloud Profiler.

Environment support

Cloud Trace runs on Linux in the following environments:

Cloud Trace provides client libraries for instrumenting your application to capture trace information. For per-language setup instructions, see Setting up Cloud Trace.

Configurations with automatic tracing

Some configurations result in automatic capture of trace data:

  • App Engine standard environment

    Java 8, Python 2, and PHP 5 applications don't need to use the Cloud Trace client libraries. These runtimes automatically send latency data to Cloud Trace for requests to application URIs. The requests include latency data for round-trip RPC calls to App Engine services. Cloud Trace works with all App Engine Admin APIs, with the exception of Cloud SQL.

  • Cloud Functions and Cloud Run

    For incoming and outgoing HTTP requests, latency data is automatically collected.

Language support

The following table summarizes the availability of Trace client libraries, the availability of OpenCensus libraries that include an Stackdriver exporter, and the availability of OpenTelemetry libraries that include an exporter to Cloud Trace:

Language Client library
library available
library available
C# ASP.NET Core Yes No No
C# ASP.NET Yes No No
Go Yes Yes Yes
Java Yes Yes Yes
Node.js Yes Yes Yes
PHP Yes Yes No
Python Yes Yes Yes
Ruby Yes No No

OpenTelemetry and OpenCensus libraries are simpler to use because they hide some of the complexity of the corresponding Cloud Trace client library. If you use these libraries, then instrument your application to use the Cloud Trace exporter.

For general setup instructions, see Setting up Cloud Trace.


Cloud Trace consists of a tracing client, which collects traces and sends them to your Google Cloud project. You can then use the Google Cloud console to view and analyze the data collected by the agent.

A trace describes the time it takes an application to complete a single operation. Each trace consists of one or more spans. A span describes how long it takes to perform a complete sub-operation. For example, a trace might describe how long it takes to process an incoming request from a user and return a response. A span might describe how long a particular RPC call requires. For more information, see Cloud Trace's Data model.

Tracing client

If an OpenCensus library is available for your programming language, you can simplify the process of creating and sending trace data by using OpenCensus. In addition to being simpler to use, OpenCensus implements batching which might improve performance.

If an OpenCensus library doesn't exist, instrument your code by importing the Trace SDK library and using the Cloud Trace API. The Cloud Trace API collects trace data and sends it to your Google Cloud project.

Tracing interface

After the agent has collected trace data, you can view and analyze that data in near real-time in the Cloud Trace interface. The interface contains three pages: Overview, Trace list, and Analysis reports.

To get started using Cloud Trace, in the Google Cloud console navigation pane, select Trace, or click the following button:

Go to Trace

The Trace console won't display data unless you have access to a Google Cloud project that is receiving Trace data.


The Overview page provides summary information about your application:

Cloud Trace overview page.

The Insights pane displays a list of performance insights for your application, if applicable. This pane highlights common problems in applications, such as consecutive calls to a function, that if batched, might be more efficient.

The Recent traces pane displays the most recent traces. For each, the latency, URI, and time are displayed. You can use this summary to understand the current activity in your application.

The Most frequent URIs and Most frequent RPCs list the most frequent URIs (and RPCs) from the previous day, along with the average latency. If you click a link in either of these tables, you open the Trace list page which is preconfigured to display matching requests. Using the Trace list page, you can view latency as a function of time, and investigate details of any individual trace.

The Chargeable Trace Spans pane displays the number of spans ingested in the current calendar month, and the total for the previous month. You can use this information to monitor your costs for using Cloud Trace. For more information on costs, see the Pricing section on this page.

The Daily analysis reports pane displays latency data for the previous day and compares it to the latency data from 7 days prior. Using this data, you can view if your latency behavior is changing over time. You can't change the format of the reports on this page. However, you can create custom analysis reports.

To learn more about the Cloud Trace Overview page, see View traces overview.

Trace list

The Trace list page lets you examine an individual traces in detail. By default, this view displays a plot of the latency for all traces and lists, in a table, the most recent traces.

If you select a specific trace to examine, two new panes are opened: a pane that displays all spans in the trace and an information pane that displays details about the selected span. By default, the root span is selected and the details include summary information about the request. To find traces for investigation, you use filters.

For more information on filtering and viewing trace details, see Find and view traces and View a trace.

Analysis reports

The Analysis reports page lets you to create custom reports. These reports can include all traces, or by specifying filters, only include a subset of traces. You can also create reports that compare two different sets of latency data. For more information, see Create and view reports.

Data security

Cloud Trace is a VPC Service Controls supported service. For more information, see VPC Service Controls documentation.

What's next