The Cloud Trace API lets you send latency data to, and retrieve latency data from, Cloud Trace. To send data to Cloud Trace, we recommend that you use OpenTelemetry. OpenTelemetry is a Google-supported open source project with Google engineers staffed to ensure support for Cloud Trace.
To retrieve data from Cloud Trace, we recommend that you use the Cloud Trace API. By using the API, you have access to the exact data stored by Cloud Trace.
You can use the Cloud Trace API from applications you run locally or on any of the following environments:
- Compute Engine
- Google Kubernetes Engine (GKE)
- App Engine flexible environment
- App Engine standard environment
- Cloud Run
- Non-Google Cloud environments
Data sent to Cloud Trace using this API is available for display, reporting, and analysis in the Google Cloud console.
Versions and interfaces
There are two supported versions of the API:
Cloud Trace API v1 lets you send and retrieve latency data by using HTTP or by using RPC. For more information, see v1 REST and v1 RPC.
Cloud Trace API v2 lets you send latency data by using HTTP or by using gRPC. For more information, see v2 REST and v2 RPC.
For more details on how to automatically collect traces from an application, see the Client libraries documentation.
Data model
For information about the data model, see Traces and spans.
Generating trace_id
and span_id
The client libraries for Trace automatically generate the
trace_id
and the span_id
. If you don't use the Trace client
libraries or the OpenTelemetry client libraries, then you must generate the
values for these fields. 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 Cloud Trace API:
- Send traces to Cloud 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 spans
In the v2 API, you send trace data to Cloud Trace by using the REST method
batchWrite
or the RPC method
batchWriteSpans
.
In the v1 API, you construct a Trace
object and
then pass that to either a REST or gRPC method. The Trace
object
contains a collection spans. For the REST API, use the method
patchTraces
. For the RPC API, use the method
PatchTraces
.
Get a list of traces
To get a list of stored traces, send 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 ListTraces
methods return a set of trace entities.
Get trace details
To get the details of particular trace, do the following:
Find the ID of the trace. One way that you can find this information is by running the
list
command.Send a request to the REST
get
or RPCGetTrace
methods. The request specifies the trace by its ID. These methods return a single trace entity.
Authorization
To use the Cloud Trace API, you or the service account must have authorization to do so. Identity and Access Management defines permissions and roles you can use for authorization. For more information, see Cloud 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 and then copy its private key credentials to the computer with the application using the Cloud 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 and the structure and content of the
data it returns. See the documentation of the
v1 API list
method for an example.