The Stackdriver Trace API allows you to send and retrieve latency data to and from Stackdriver Trace. This API provides low-level interfaces for interacting directly with the feature. For some languages, you have the option to make use of OpenCensus, a set of open source tracing and stats instrumentation libraries that work with multiple backends.
You can use the Stackdriver Trace API from applications you run locally or on Compute Engine, App Engine, or hosting environments completely separate from Google Cloud. Data sent to Stackdriver Trace using this API is available for display, reporting and analysis in the Google Cloud Console.
Versions and interfaces
There are two versions of the API:
- Stackdriver Trace API v1 is fully supported.
Stackdriver Trace API v2 is in Beta release.
Both APIs have two interfaces:
v1 REST and v2 REST interfaces let you send and retrieve latency data in JSON format over HTTP.
v1 and v2 RPC interfaces let you to send and retrieve latency data using gRPC.
For more details on how to automatically collect traces from an application, go to the Client libraries page.
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 sub-operation.
In the v1 API, 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 Platform project as well as its subspans.
In the v2 API, the concept of a trace is still present, but there is no explicit trace object. The trace ID you include in your spans identifies the associated trace.
Spans
A span describes the amount of time it takes an application to complete a sub-operation 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.
In the v1 API, 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.
In the v2 API, spans are represented by the Span resource. The
labels in the v1 API spans are replaced by attributes of specific kinds in v2.
Generating trace_id and span_id
The client libraries for Trace automatically generate the
trace_id and the span_id. You need to generate the values for these
fields if you don't use the Trace client libraries or the
OpenCensus client libraries. In this case,
you should use a pseudo-random or random algorithm. Don't derive these fields
from need-to-know data or from personally identifiable information.
Operations
You can do the following with the Stackdriver Trace API:
- Send traces to Stackdriver Trace
- Update existing traces (v1 only)
- Get lists of traces (v1 only)
- Get the details of a single trace (v1 only)
The v2 API only supports sending trace data. There are no methods to retrieve the data.
Send traces
In the v1 API, 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
PatchTraces methods.
In the v2 API, you send trace data to Stackdriver Trace by using the REST
batchWrite method or the RPC batchWriteSpans
method. The V2 REST API method
createSpan
doesn't offer any advantages over batchWrite.
Update existing traces
In the v1 API, 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
PatchTraces
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.
In the v2 API, there are no trace objects to update. Of course, you can add additional spans to a trace.
Get a list of traces
In the v1 API, you can get a list of traces from Stackdriver Trace by sending a
request to the REST list
or RPC ListTraces
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.
In the v2 API, you cannot retrieve traces or their spans.
Get trace details
In the v1 API, 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.
In the v2 API, you cannot retrieve traces or their spans.
Authorization
To use the Stackdriver Trace API, a user or service account must have authorization to do so. Cloud Identity and Access Management defines permissions and roles you can use for authorization. For more information, see Stackdriver Trace access control.
When running on Google Cloud, authorization is normally provided by default. When running outside of Google Cloud, you obtain authorization by creating a service account in your Google Cloud project and copying the private key credentials for that service account to the computer with the application using the Stackdriver Trace API.
For more information, see Setting up authentication.
Explore the API
You can use the in-page Try It! feature in the REST interface documentation
to explore the API functionality. Using 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
v1 API list method for an example.
Hai bisogno di assistenza? Visita la nostra