Cloud Trace API

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:

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

The Cloud 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.

In the v1 API, a trace is 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 Google Cloud project and 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 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. For another example, a span could describe how long it takes to perform one task that is part of a larger operation.

In the v1 API, a span is 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, a span is represented by the Span resource. In the v2 API, Attributes replace the v1 API labels field.

When a span is received for a trace, all relevant processing for that span and trace occurs. The processing has no dependencies on timestamps of any other spans received for that trace.

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 traces

In the v1 API, you can send one or more new traces to Cloud Trace by assembling trace entities in your client application and then passing them to the correct API method. For the REST API, use the method patchTraces. For the RPC API, use the method PatchTraces.

In the v2 API, you send trace data to Cloud 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 Cloud Trace by updating existing trace entities and then passing them to the correct API method. For the REST API, use the method patchTraces. For the RPC API, use the method PatchTraces. This update works in a similar way to sending new traces. However, if the ID of a trace that you send matches the ID of an existing trace, the following occurs:

  • Any fields in the existing trace and its spans are overwritten by the provided values.
  • Any new fields provided are merged with the existing trace data.

In the v2 API, there are no trace objects to update. You can add multiple spans to a trace.

Get a list of traces

In the v1 API, you can get a list of traces from Cloud 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 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.