About Cloud Trace

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 debugging or profiling your application, see Application Performance Management.

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.

In the 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.

Language support

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

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

OpenCensus libraries are simpler to use because they hide some of the complexity of the corresponding Cloud Trace client library. If you use OpenCensus, select the Stackdriver exporter.

For general setup instructions, see Setting up Cloud Trace.

Components

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 of 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 windows: Overview, Trace list, and Analysis reports.

To get started using Cloud Trace, in the 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.

Overview

The Overview window 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 window which is preconfigured to display matching requests. Using the Trace list window, 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 window, see Viewing Traces in the Cloud Console.

Trace list

The Trace list window 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 Finding and viewing traces and Viewing trace details.

Analysis reports

The Analysis reports window 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 Creating analysis reports.

Pricing

Latency data is packaged into a trace, which is composed of spans. The spans are ingested by the Cloud Trace backend which then makes the data available for real-time viewing and reporting in the Cloud Console. When you view trace data, the stored spans are scanned as part of the retrieval process.

Cloud Trace pricing is determined by the number of Trace spans ingested, and scanned, on a monthly basis. For more information, see Trace pricing.

You can create an alert to notify you if your ingested span count exceeds a predefined threshold. For more information, see Creating alerting policies.

Quota

Cloud Trace enforces a rate quota on your of API requests and an ingestion quota on the spans you sent to Trace. For more information, see Quotas and limits.

To view your current usage:

  1. In the Google Cloud Console, select APIs & Services, and then select Cloud Trace API, or use the following button:

    Go to Trace API

  2. Click Quotas.

You can create an alert to notify you if you have exceeded your quotas. For more information, see Creating alerting policies.

Data security

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

What's next