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:
- Stackdriver Trace SDK for Java
- Stackdriver Trace SDK for Node.js
- Stackdriver Trace SDK for Go
- Stackdriver Trace SDK for Ruby
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.
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.
The Stackdriver Trace API defines two entities: traces and spans.
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
message in the RPC interface. A trace entity contains fields that specify the
associated Cloud project as well as its subspans.
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
resource in the REST interface and the
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.
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
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
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
list or RPC
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
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
methods. The request specifies the trace by its ID. These methods return a
single trace entity.
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