Stackdriver Trace API

The Stackdriver Trace API allows you to send and retrieve latency data to and from Google Stackdriver Trace. This API provides low-level interfaces for interacting directly with the feature. The following SDKs provide additional wrapper functionality that makes it easy to write latency data from your applications to Stackdriver Trace:

Traces can also be received from Zipkin tracers via the Stackdriver Trace Zipkin Collector

By default, Stackdriver Trace collects data from any Google App Engine application where the feature is enabled. The Stackdriver Trace API allows you to send latency data to Stackdriver Trace from any other application. This includes applications you run locally, run on Google Compute Engine or run in hosting environments completely separate from Google Cloud Platform. You can also use the Stackdriver Trace API to customize or enhance the data sent from App Engine by default. Data sent to Stackdriver Trace using this API is available for display, reporting and analysis in the Google Cloud Platform Console.

Interfaces

The Stackdriver Trace API provides two interfaces:

A REST interface, which allows you to send and retrieve latency data in JSON format over HTTP.
An RPC interface, which allows you to send and retrieve latency data using gRPC. We don't provide gRPC client libraries at this time. If you want to use this interface, you can generate gRPC client code from the service definition (available soon) following the instructions in the gRPC documentation.

Data model

The Stackdriver Trace API defines two entities: traces and spans.

Traces

A trace describes the amount of time it takes an application to complete a single operation. For example, it can describe how long it takes for the application to process an incoming request from a user and return a response. Each trace consists of one or more spans, each of which describes the amount of time it takes to complete a suboperation.

Traces are represented by the Trace resource in the REST interface and the Trace message in the RPC interface. A trace entity contains fields that specify the associated Cloud project as well as its subspans.

Spans

A span describes the amount of time it takes an application to complete a suboperation in a trace. For example, it can describe how long it takes for the application to perform a round-trip RPC call to another system when handling a request, or how long it takes to perform another task that is part of a larger operation.

Spans are represented by the TraceSpan resource in the REST interface and the TraceSpan message in the RPC interface. A span entity contains fields that specify its type, its start and end times, and labels that describe it. A span can be nested within a trace. If so, it specifies its parent span.

Operations

You can do the following with the Stackdriver Trace API:

Send traces to Stackdriver Trace
Update existing traces
Get lists of traces
Get the details of a single trace

Send traces

You can send one or more new traces to Stackdriver Trace by assembling trace entities in your client application and then passing them to the REST patchTraces or RPC PatchTracesRequest methods.

Update existing traces

You can update one or more new traces in Stackdriver Trace by updating existing trace entities and then passing them to the REST patchTraces or RPC PatchTracesRequest methods. This works in a similar way to sending new traces. However, if the ID of a trace that you send matches that of an existing trace, any fields in the existing trace and its spans are overwritten by the provided values, and any new fields provided are merged with the existing trace data.

Get a list of traces

You can get a list of traces from Stackdriver Trace by sending a request to the REST list or RPC ListTracesRequest methods. You can pass a filter condition to these requests to retrieve only those traces that were sent between a specific start and end time. The list and ListTracesRequest methods return a set of trace entities.

Get trace details

After you get a list of traces, you can get the details for a particular trace by sending a request to the REST get or RPC GetTraceRequest methods. The request specifies the trace by its ID. These methods return a single trace entity.

Authorization

The Stackdriver Trace API uses OAuth 2.0 for user authorization. This means that you must set up web application credentials in the Google Cloud Platform Console for your project and implement an OAuth 2.0 authorization flow in your client application in order to use the API. See Using OAuth 2.0 to Access Google APIs for more information. You can also see the Authentication page on the gRPC site for information specific to gRPC.

Explore the API

You can use the in-page Try It! feature in the REST interface documentation to explore the API functionality. Try It! helps you understand how to assemble the data that you pass to the API, as well as the structure and content of the data it returns. See the documentation of the list method for an example.