--- title: "Span Protocol" url: https://develop.sentry.dev/sdk/telemetry/spans/span-protocol/ --- # Span Protocol This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. The SDK must implement a new "span v2" envelope item, which is used to emit spans to Sentry. ## [Span v2 Envelope Header](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-v2-envelope-header) The envelope header must contain the same properties as previously with transactions. There are no special requirements for the Span v2 envelope header. ```json { "sent_at": "2025-02-07T14:16:00Z", "dsn": "https://e12d836b15bb49d7bbf99e64295d995b@sentry.io/42", "sdk": { // ... }, "trace": { // ... } } ``` Unlike transactions, envelope headers for spans **require** [Dynamic sampling context](https://develop.sentry.dev/sdk/telemetry/traces/dynamic-sampling-context.md). Also see [Envelope Headers](https://develop.sentry.dev/sdk/foundations/transport/envelopes.md#headers). ## [Span v2 Envelope Item Header](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-v2-envelope-item-header) The envelope item header must contain the following properties: ```json { "type": "span", "item_count": 2, "content_type": "application/vnd.sentry.items.span.v2+json" } ``` ## [Span v2 Envelope Item Payload](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-v2-envelope-item-payload) The span v2 envelope item payload is a JSON object that **MUST** include an `items` array of span objects. The payload **MAY** also include top-level `version` and `ingest_settings` fields as specified in the next section. The container is defined as follows: ```json { "version": 2, "ingest_settings": { "infer_ip": "auto", "infer_useragent": "auto" }, "items": [{..span..}, {..span..}, {..span..}] } ``` ### [`version` and `ingest_settings` properties](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#version-and-ingest_settings-properties) Candidatespecified since 0.0.0 The span envelope item `ingest_settings` property is an optional JSON object that contains ingestion settings for Relay, for example, to infer certain data from the incoming request. | Field | Type | Required | Description | | ----------------- | ------ | ------------ | -------------------------------------------------------------------------------------------------- | | `infer_ip` | String | **OPTIONAL** | The setting to infer the IP address from the incoming request. One of `auto` or `never` (default). | | `infer_useragent` | String | **OPTIONAL** | The setting to infer the user agent from the incoming request. One of `auto` or `never` (default). | SDKs like Browser or React Native **MAY** set these to `"auto"` to instruct Relay to infer the IP address or user agent from the incoming request and put it onto the span as an attribute. For ingestion settings to take effect, the SDK **MUST** also set the `version` property to `2` (`number`) or higher. If `version` is omitted, Relay treats the payload as version `1` and doesn't apply `ingest_settings`. ### [`items` property - `span` Item Payload](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#items-property---span-item-payload) The `items` array **MUST** contain at least one and at most 1000 span objects: ```json { "items": [ { "trace_id": "6cf173d587eb48568a9b2e12dcfbea52", "span_id": "438f40bd3b4a41ee", "name": "GET /users", "status": "ok", "is_segment": true, "start_timestamp": 1742921669.158209, "end_timestamp": 1742921669.180536, "attributes": { "sentry.release": { "type": "string", "value": "1.0.0" }, "sentry.environment": { "type": "string", "value": "local" }, "sentry.platform": { "type": "string", "value": "php" }, "sentry.sdk.name": { "type": "string", "value": "sentry.php" }, "sentry.sdk.version": { "type": "string", "value": "4.10.0" }, "sentry.transaction_info.source": { "type": "string", "value": "route" }, "sentry.origin": { "type": "string", "value": "auto" }, "server.address": { "type": "string", "value": "127.0.0.1" }, "http.response.status_code": { "type": "integer", "value": 200 }, "session.duration": { "type": "integer", "value": 164, "unit": "second" } }, "links": [ { "span_id": "6c71fc6b09b8b716", "trace_id": "627a2885119dcc8184fae7eef09438cb", "sampled": true, "attributes": { "sentry.link.type": { "type": "string", "value": "previous_trace" } } } ] }, { "trace_id": "6cf173d587eb48568a9b2e12dcfbea52", "parent_span_id": "438f40bd3b4a41ee", "span_id": "f1196292f76e45c0", "name": "app.handle", "status": "ok", "is_segment": false, "start_timestamp": 1742921669.178306, "end_timestamp": 1742921669.180484, "attributes": { "sentry.origin": { "type": "string", "value": "auto" } } } ] } ``` ## [Span v2 Protocol Properties](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-v2-protocol-properties) ### [Envelope Item Header Properties](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#envelope-item-header-properties) | Property | Type | Required | Description | | -------------- | ------- | -------- | ---------------------------------------------------------------- | | `type` | string | Yes | Must be set to `"span"` to identify this as a span envelope item | | `item_count` | integer | Yes | Number of span items in the payload | | `content_type` | string | Yes | Must be set to `"application/vnd.sentry.items.span.v2+json"` | ### [Span Properties](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-properties) | Property | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | | `trace_id` | string | Yes | 32-character hexadecimal string (a valid uuid4 without dashes) | | `span_id` | string | Yes | 16-character hexadecimal string (a valid uuid4 without dashes) | | `parent_span_id` | string | No | 16-character hexadecimal string (a valid uuid4 without dashes) | | `name` | string | Yes | A low cardinality description of what the span represents (e.g., "GET /users", "database.query") | | `status` | string | Yes | Status of the span operation. Either `"ok"` or `"error"` | | `is_segment` | boolean | Yes | Whether the span is a segment span | | `start_timestamp` | number | Yes | Unix timestamp (with fractional microseconds) when the span was started | | `end_timestamp` | number | Yes | Unix timestamp (with fractional microseconds) when the span was ended | | `attributes` | object | No | Key-value pairs containing additional metadata about the span | | `links` | array | No | Array of links connecting this span to other spans or traces | #### [Common Attribute Keys](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#common-attribute-keys) All attributes mentioned below must be attached to every span being emitted from the SDK, depending on the platform. Empty attributes must be omitted. | Attribute Key | Type | Description | | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `sentry.op` | string | The [span op](https://develop.sentry.dev/sdk/telemetry/traces/span-operations.md) (e.g., "http.client", "db.query") of the span | | `sentry.release` | string | The release version of the application | | `sentry.environment` | string | The environment name (e.g., "production", "staging", "development") | | `sentry.segment.name` | string | The segment name (e.g., "GET /users") | | `sentry.segment.id` | string | The segment span id | | `sentry.span.source` | string | The source of the span name. **MUST** be set on segment spans, **MAY** be set on child spans. See [Sentry Conventions](https://github.com/getsentry/sentry-conventions/blob/main/model/attributes/sentry/sentry__span__source.json) for all supported sources. See [Transaction Annotations](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/transaction.md#transaction-annotations) and [Clustering](https://develop.sentry.dev/backend/application-domains/transaction-clustering.md#automatic-transaction-clustering) for more information. | | `sentry.profiler_id` | string | The id of the currently running profiler (continuous profiling) | | `sentry.replay_id` | string | The id of the currently running replay (if available) | | `os.name` | string | The operating system name (e.g., "Linux", "Windows", "macOS") | | `browser.name` | string | The browser name (e.g., "Chrome", "Firefox", "Safari") | | `user.id` | string | The user ID | | `user.email` | string | The user email | | `user.ip_address` | string | The user IP address | | `user.name` | string | The user username | | `thread.id` | string | The thread ID | | `thread.name` | string | The thread name | | `sentry.sdk.name` | string | Name of the Sentry SDK (e.g., "sentry.php", "sentry.javascript") | | `sentry.sdk.version` | string | Version of the Sentry SDK | Attributes outside of the above list MUST only be attached to the span they conceptually belong on, and not propagated to children spans. For instance, attributes mirroring transaction context data should only be set on the segment span. See also [the implementation guidelines](https://develop.sentry.dev/sdk/telemetry/spans/implementation.md#how-to-approach-span-first-in-sdks). See [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) for a full list of supported attributes. ### [Link Object Properties](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#link-object-properties) Links connect spans to other spans or traces, enabling distributed tracing: | Property | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------------------------- | | `span_id` | string | Yes | 16-character hexadecimal string (a valid uuid4 without dashes) | | `trace_id` | string | Yes | 32-character hexadecimal string (a valid uuid4 without dashes) | | `sampled` | boolean | No | Whether the linked trace was sampled | | `attributes` | object | No | Additional metadata about the link relationship | #### [Link Attribute Keys](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#link-attribute-keys) | Attribute Key | Type | Description | | ------------------ | ------ | --------------------------------------------------------------------------------- | | `sentry.link.type` | string | Type of link relationship (e.g., "previous\_trace", "child\_of", "follows\_from") | ## [Data Types and Formats](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#data-types-and-formats) ### [Timestamp Format](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#timestamp-format) Timestamps use Unix time with fractional microseconds as a floating-point number: ```bash 1742921669.158209 ``` ### [ID Formats](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#id-formats) * **Trace ID**: 32-character (128 bits) lowercase hexadecimal string (a valid uuid4 without dashes) * **Span ID**: 16-character (64 bits) lowercase hexadecimal string (a valid uuid4 without dashes) Example: ```bash trace_id: "6cf173d587eb48568a9b2e12dcfbea52" span_id: "438f40bd3b4a41ee" ``` ## [Span Attachments](https://develop.sentry.dev/sdk/telemetry/spans/span-protocol.md#span-attachments) Span attachments are an experimental feature that is still under development. To associate an attachment with a span, submit a [trace attachment](https://develop.sentry.dev/sdk/telemetry/attachments.md#trace-attachments) item with an additional `span_id` item header. The trace attachment *should* be submitted in the same envelope as the span itself. * `span_id` is the ID of the span that owns the attachment. If set, the attachment will be dropped with the span if the span is dropped by dynamic sampling, inbound filters or rate limits. That is, Relay treats `span_id` as the owner of the attachment. * The SDK *may* set the `span_id` item header to an explicit `null` value. `span_id: null` is treated as “owned by spans”, but not owned by a specific span. That is, the attachment can be dropped if the span quota is exceeded, but it will not be dropped with a specific span because of e.g. inbound filters.