This document describes the format in which trace spans are stored. The format
of the data is generally consistent with the proto files defined by the
[OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otlp).
However, fields might be converted from an OpenTelemetry-specific data type to a
JSON data type before storage.

The [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview.md.txt)
uses the [OpenTelemetry Protocol](https://opentelemetry.io/docs/specs/otlp).
This protocol relies on the [`trace_service.proto`](https://github.com/open-telemetry/opentelemetry-proto/blob/v1.5.0/opentelemetry/proto/collector/trace/v1/trace_service.proto)
and [`trace.proto`](https://github.com/open-telemetry/opentelemetry-proto/blob/v1.5.0/opentelemetry/proto/trace/v1/trace.proto) files. For information about
field limits,
see [Telemetry API limits](https://docs.cloud.google.com/stackdriver/quotas.md.txt#telemetry-api-limits).

The Cloud Trace API doesn't use the OpenTelemetry OTLP Protocol and defines a
proprietary data format. Trace data sent to your Google Cloud project through
this API is converted to the format described by this document. However, the
limits for the Cloud Trace API apply.

## Span storage format

<br />

<br />

Field Description `trace_id` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Globally unique identifier for the
[trace](https://docs.cloud.google.com/trace/docs/traces-and-spans.md.txt).
This identifier is a 128-bit numeric value formatted as a 16-byte
hexadecimal string. For example,
`382d4f4c6b7bb2f4a972559d9085001d`.
To learn more about this identifier, see
[W3C `trace-id`](https://www.w3.org/TR/trace-context/#trace-id).

A numeric value of zero is invalid.

The `trace_id` is used by visualization and analysis
tools to identify the spans associated with a trace. For this reason,
every end-to-end operation must have a unique identifier. Don't
reuse a trace identifier.
`span_id` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Required. Identifier for the
[span](https://docs.cloud.google.com/trace/docs/traces-and-spans.md.txt).
Must be unique within a trace.
This identifier is a 64-bit numeric value
formatted as an 8-byte hexadecimal string.
For example, `9046a5b9f7c12500`.

A numeric value of zero is invalid.
`trace_state` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

This field corresponds to the
[`tracestate` header](https://www.w3.org/TR/trace-context/#tracestate-header),
as defined by [W3C Trace Context](https://www.w3.org/TR/trace-context/).
This header contains configuration information that is included in
requests when applications are instrumented to collect trace data.
For example, an application can specify the
[probability sampling](https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling-experimental/)
settings, or it can include vendor-specific content.

OpenTelemetry libraries automatically record the value of the
`tracestate` header when they generate spans.
`parent_span_id` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Optional. Identifies the operation which invoked this span.
The "root" span has the parent span ID set to null.

The parent-child relationship between spans is used by visualization
tools to construct the tree structure.
`name` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Required. The name of the operation that was performed.

The name can be a method name or some other per-call site name.
For the same executable and the same endpoint, using a consistent name
makes it easier to correlate cross-trace spans. For best practices, see
[How to Name Your Spans](https://opentelemetry.io/blog/2025/how-to-name-your-spans/).

The span name is sanitized and displayed in the Google Cloud console.
`kind` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

Specifies where in the system the operation took place.
The value corresponds to the [OpenTelemetry: Span Kind](https://opentelemetry.io/docs/concepts/signals/traces/#span-kind) enumeration:
ValueOpenTelemetry enumeration 0SPAN_KIND_UNSPECIFIED 1SPAN_KIND_INTERNAL 2SPAN_KIND_SERVER 3SPAN_KIND_CLIENT 4SPAN_KIND_PRODUCER 5SPAN_KIND_CONSUMER `start_time` [**`Timestamp`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#timestamp_type)

Required. Start time of the span, to the nearest nanosecond.
`start_time_unix_nano` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The start time in nanoseconds, according to the UNIX epoch.
`end_time` [**`Timestamp`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#timestamp_type)

Required. End time of the span, to the nearest nanosecond.
`end_time_unix_nano` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The end time in nanoseconds, according to the UNIX epoch.
`receive_time` [**`Timestamp`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#timestamp_type)

Required. Receive time of the span, to the nearest nanosecond.
`receive_time_unix_nano` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The end time in nanoseconds, according to the UNIX epoch.
`duration_unix_nano` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The duration in nanoseconds.
`attributes` [**`JSON type`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#json_type)

Each attribute is a key-value pair.
The attributes available to you
are dependent on your trace data. The structure of attributes follow the
OpenTelemetry standard. To learn more, see [OpenTelemetry: Attributes](https://opentelemetry.io/docs/concepts/signals/traces/#attributes).

OpenTelemetry specificies semantic conventions for attributes. To learn
about these conventions, see
[Trace semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/trace/).

The following are examples of attributes:

```
"yourcompany.your.own.key": "your own value"
"network.protocol.name": "http"
"network.protocol.version": "1.1"
"http.response.status_code": "200"
"network.peer.address": "REDACTED"
```
`dropped_attributes_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of attributes that were discarded.
Attributes can discarded because their keys are too long or because there are
too many attributes. When this value is zero, no attributes were discarded.

This value might be set by the client-side instrumentation or by an
application. The value can be incremented by the server.
`events` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) with repeated fields

A point in time event. Each event contains the following fields.
FieldDescription `time`[**`Timestamp`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#timestamp_type)
`time_unix_nano`[**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)
`name` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Required. Name of the event.
`attributes` [**`JSON type`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#json_type)

Each attribute is a key-value pair.
The attributes available to you
are dependent on your trace data. The structure of attributes follow the
OpenTelemetry standard. To learn more, see [OpenTelemetry: Attributes](https://opentelemetry.io/docs/concepts/signals/traces/#attributes).
`dropped_attributes_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of attributes that were discarded.
Attributes can discarded because their keys are too long or because there are
too many attributes. When this value is zero, no attributes were discarded.

This value might be set by the client-side instrumentation or by an
application. The value can be incremented by the server.
`dropped_events_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of events that were discarded. Events can discarded
because there are too many events. When this value is zero, no
events were discarded.
`links` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) with repeated fields

Links associated with the span. Links are references from this span
to another span in the same or different trace.

Links provide a mechanism to correlate spans from one trace with
spans in another trace. For example, suppose one operation causes
an asynchronous operation to occur. In this scenario, there are two
traces, one for the original operation and one for the asynchronous
operation. You can use links to correlate the spans in these traces.

Each link contains the following fields.
FieldDescription `trace_id`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Required.
`span_id`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

Required.
`trace_state`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`attributes` [**`JSON type`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#json_type)

Each attribute is a key-value pair.
The attributes available to you
are dependent on your trace data. The structure of attributes follow the
OpenTelemetry standard. To learn more, see [OpenTelemetry: Attributes](https://opentelemetry.io/docs/concepts/signals/traces/#attributes).
`dropped_attributes_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of attributes that were discarded.
Attributes can discarded because their keys are too long or because there are
too many attributes. When this value is zero, no attributes were discarded.

This value might be set by the client-side instrumentation or by an
application. The value can be incremented by the server.
`dropped_links_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of links that were discarded. Links can discarded
because there are too many links. When this value is zero, no
links were discarded.
`status` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) without repeated fields

This field records the completion status for a span.
The value of the `code` subfield corresponds to the
[OpenTelemetry: Span Status](https://opentelemetry.io/docs/concepts/signals/traces/#span-status) enumeration:
ValueOpenTelemetry  
enumerationDescription 0 `UNSET` Operation completed successfully. 1 `OK` Operation was marked as error-free by a human. 2 `ERROR` The operation completed with an error. For example, if the status is 400 (BAD REQUEST) on a client span, then this field is set to `ERROR`.

The `message` subfield, which is formatted a string,
contains error information.
`resource` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) without repeated fields

This field identifies the infrastructure or hosting system from which
the telemetry was collected or that the telemetry is about. For example,
consider an application running on Google Kubernetes Engine. Attributes
for this resource might include the process name and namespace.

This field contains the following subfields:
FieldDescription `attributes` [**`JSON type`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#json_type)

Each attribute is a key-value pair.
The attributes available to you
are dependent on your trace data. The structure of attributes follow the
OpenTelemetry standard. To learn more, see [OpenTelemetry: Attributes](https://opentelemetry.io/docs/concepts/signals/traces/#attributes).

The following are examples of resource attributes:

```
cloud.account.id: "my-project"
cloud.platform: "gcp_kubernetes_engine"
cloud.provider: "gcp"
cloud.region: "us-central1"
gcp.project_id: "my-project"
host.id: "REDACTED"
host.name: "gke-otel-demo"
k8s.cluster.name: "otel-demo"
k8s.deployment.name: "otel-demo-frontendproxy"
```
`dropped_attributes_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of attributes that were discarded.
Attributes can discarded because their keys are too long or because there are
too many attributes. When this value is zero, no attributes were discarded.

This value might be set by the client-side instrumentation or by an
application. The value can be incremented by the server.

To learn more, see [OpenTelemetry: Resources](https://opentelemetry.io/docs/concepts/resources/).
`instrumentation_scope` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) without repeated fields

This field identifies the library or application component for
the specified `resource` that is collecting telemetry. The
span represents a specific operation passing through that scope,
that is, through the library or component, within the resource.

For example, suppose the application "checkout-service" is deployed
to Cloud Run, which means that the `resource`
is a specific Cloud Run instance. Also, assume that the
resource has several instrumentation scopes, like
"request-authorization-library" and "payment-processor-library".

A client span, like "WritePaymentInfoToStripe", might be a span that
is reported by the "payment-processor-library", which is
inside the Cloud Run service named "checkout-service".

This field contains the following subfields:
FieldDescription `name`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`version`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`attributes` [**`JSON type`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#json_type)

Each attribute is a key-value pair.
The attributes available to you
are dependent on your trace data. The structure of attributes follow the
OpenTelemetry standard. To learn more, see [OpenTelemetry: Attributes](https://opentelemetry.io/docs/concepts/signals/traces/#attributes).
`dropped_attributes_count` [**`integer`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#integer_type)

The number of attributes that were discarded.
Attributes can discarded because their keys are too long or because there are
too many attributes. When this value is zero, no attributes were discarded.

This value might be set by the client-side instrumentation or by an
application. The value can be incremented by the server.

To learn more, see
[OpenTelemetry: Instrumentation scope](https://opentelemetry.io/docs/concepts/instrumentation-scope/).
`resource_schema_link` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

These fields must be a URL formatted as a string.

These fields contain a URL that returns a schema file for a resource.
The format of the schema file and data is defined by OpenTelemetry. For more
information, see [OpenTelemetry: Schemas](https://opentelemetry.io/docs/specs/otel/schemas/).

These fields can only be set when using the Telemetry API.
That API doesn't validate that the data conforms to the declared
schema.
`scope_schema_link` [**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)

These fields must be a URL formatted as a string.

These fields contain a URL that returns a schema file for a scope.
The format of the schema file and data is defined by OpenTelemetry. For more
information, see [OpenTelemetry: Schemas](https://opentelemetry.io/docs/specs/otel/schemas/).

These fields can only be set when using the Telemetry API.
That API doesn't validate that the data conforms to the declared
schema.
`apphub` [**`record`**](https://docs.cloud.google.com/bigquery/docs/nested-repeated.md.txt) without repeated fields

Application-specific labels are available when trace spans are
generated by [App Hub](https://docs.cloud.google.com/app-hub/docs/overview.md.txt)
applications, when those applications run on
[supported infrastructure](https://docs.cloud.google.com/stackdriver/docs/observability/application-monitoring-services.md.txt)
or have been instrumented.
To learn more about Application Monitoring and when these labels are available,
see Application Monitoring overview.

This field contains `application`, `service`,
and `workload` subfields.
Application subfieldDescription `container`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`location`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`id`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
Service/workload  
subfieldDescription `id`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`environment_type`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)
`criticality_type`[**`string`**](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/data-types.md.txt#string_type)