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 useOpenTelemetry.OpenTelemetry is a Google-supported open source project with Googleengineers staffed to ensure support for Cloud Trace.For more information about instrumenting an application,including instrumentation examples, seeInstrumentation and observability.

To retrieve data from Cloud Trace, we recommend that you use theCloud Trace API. By using the API, you have access to the exact datastored by Cloud Trace.

You can use the Cloud Trace API from applications you run locally or on any ofthe following environments:

• Compute Engine
• Google Kubernetes Engine (GKE)
• Apigee (Public Preview)
• App Engine flexible environment
• App Engine standard environment
• Cloud Run
• Cloud Service Mesh
• Cloud SQL query insights
• Non-Google Cloud environments

Data sent to Cloud Traceusing this API is available for display, reporting, and analysis in theGoogle Cloud console.

Versions and interfaces

There are two supported versions of the API:

• Cloud Trace API v1 lets you send and retrieve latency databy using HTTP or by using RPC. For more information,seev1 REST andv1 RPC.

• Cloud Trace API v2 lets you send latency data by using HTTPor by usinggRPC. For more information,seev2 REST andv2 RPC.

For more details on how to automatically collect traces from an application,see theClient libraries documentation.

Data model

For information about the data model, seeTraces and spans.

Generatingtrace_id andspan_id

The client libraries for Trace automatically generate thetrace_id and thespan_id. If you don't use the Trace clientlibraries or the OpenTelemetry client libraries, then you must generate thevalues for these fields. In this case,you should use a pseudo-random or random algorithm. Don't derive these fieldsfrom 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 toretrieve the data.

Send spans

Note: Cloud Trace quotas restrict the number of write operations performed.When you are developing or testing code, the v2 REST API methodcreateSpan can be useful. However,in production code, to make best use of your quota, use thebatchWrite method.

In the v2 API, you send trace data to Cloud Trace by using the REST methodbatchWrite or the RPC methodbatchWriteSpans.

In the v1 API, you construct aTrace object andthen pass that to either a REST or gRPC method. TheTrace objectcontains a collection spans. For the REST API, use the methodpatchTraces. For the RPC API, use the methodPatchTraces.

Get a list of traces

To get a list of stored traces, send arequest to the RESTlistor RPCListTraces methods.You can pass a filter condition to these requests to retrieve onlythose traces that were sent between a specific start and end time. ThelistandListTraces methods return a set of trace entities.

Get trace details

To get the details of particular trace, do the following:

1. Find the ID of the trace. One way that you can find this informationis by running thelist command.

2. Send a request to the RESTget or RPCGetTracemethods. The request specifies the trace by its ID. These methods return asingle trace entity.

Authorization

To use the Cloud Trace API, you or the service account must haveauthorization to do so.Identity and Access Managementdefines permissions and roles you can use for authorization. For moreinformation, seeCloud Trace access control.

When running on Google Cloud, authorization is normally provided bydefault. When running outside of Google Cloud, you obtain authorizationby creating a service account and then copy its private key credentialsto the computer with the application using the Cloud Trace API.

For more information, seeSetting up authentication.

Explore the API

You can use the in-pageTry It! feature in the REST interface documentationto explore the API functionality. UsingTry It! helps you understand howto assemblethe data that you pass to the API and the structure and content of thedata it returns. See the documentation of thev1 APIlist method for an example.