--- title: "Span Interface" url: https://develop.sentry.dev/sdk/foundations/transport/event-payloads/span/ --- # Span Interface The Span Interface specifies a series of *timed* application events that have a start and end time. A [Transaction](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/transaction.md) may contain zero or more Spans in an array attribute named `spans`. Spans in the list don't have to be ordered, they will be ordered by start / end time on the Server. While Span attributes will be normalized on the server, a Span is most useful when it includes at least an `op` and `description`. ## [Attributes](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/span.md#attributes) `span_id`: *Required*. A random hex string with a length of 16 characters. ```json { "span_id": "99659d76b7cdae94" } ``` `parent_span_id`: *Optional*. If this Span should be rendered as a child of another Span, set this property to the id of the parent. ```json { "parent_span_id": "b0e6f15b45c36b12" } ``` `trace_id`: *Required*. Determines which `trace` the Span belongs to. The value should be 16 random bytes encoded as a hex string (32 characters long). ```json { "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee" } ``` `op` *Recommended*. Short code identifying the type of operation the span is measuring. For more details, see [Sentry's conventions around span operations](https://develop.sentry.dev/sdk/performance/span-operations.md). ```json { "op": "db.query" } ``` `description` *Optional*. Longer description of the span's operation, which uniquely identifies the span but is consistent across instances of the span. ```json { "description": "SELECT * FROM users WHERE last_active < DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)`" } ``` `start_timestamp` *Required*. A timestamp representing when the measuring started. The format is either a string as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339) or a numeric (integer or float) value representing the number of seconds that have elapsed since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). The `start_timestamp` value must be less than or equal to the `timestamp` value, otherwise the Span is discarded as invalid. ```json { "start_timestamp": "2011-05-02T17:41:36.242Z" } ``` or: ```json { "start_timestamp": 1304358096.242 } ``` `timestamp` *Required*. A timestamp representing when the measuring finished. The format is either a string as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339) or a numeric (integer or float) value representing the number of seconds that have elapsed since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). ```json { "timestamp": "2011-05-02T17:41:36.955Z" } ``` or: ```json { "timestamp": 1304358096.955 } ``` `status` *Optional*. Describes the `status` of the Span/Transaction. | State | Description | HTTP status code equivalent | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------- | | `ok` | Not an error, returned on success | 200 and 2XX HTTP statuses | | `cancelled` | The operation was cancelled, typically by the caller | 499 | | `unknown` or `unknown_error` | An unknown error raised by APIs that don't return enough error information | 500 | | `invalid_argument` | The client specified an invalid argument | 400 | | `deadline_exceeded` | The deadline expired before the operation could succeed | 504 | | `not_found` | Content was not found or request was denied for an entire class of users | 404 | | `already_exists` | The entity attempted to be created already exists | 409 | | `permission_denied` | The caller doesn't have permission to execute the specified operation | 403 | | `resource_exhausted` | The resource has been exhausted e.g. per-user quota exhausted, file system out of space | 429 | | `failed_precondition` | The client shouldn't retry until the system state has been explicitly handled | 400 | | `aborted` | The operation was aborted | 409 | | `out_of_range` | The operation was attempted past the valid range e.g. seeking past the end of a file | 400 | | `unimplemented` | The operation is not implemented or is not supported/enabled for this operation | 501 | | `internal_error` | Some invariants expected by the underlying system have been broken. This code is reserved for serious errors | 500 | | `unavailable` | The service is currently available e.g. as a transient condition | 503 | | `data_loss` | Unrecoverable data loss or corruption | 500 | | `unauthenticated` | The requester doesn't have valid authentication credentials for the operation | 401 | ```json { "status": "ok" } ``` `tags` *Optional*. A map or list of tags for this event. Tags must have string values, and each tag must be less than 200 characters. ```json { "tags": { "ios_version": "4.0", "context": "production" } } ``` * `data` *Optional*. Arbitrary data associated with this Span. The semantic conventions for the `data` field are described in [Sentry's Span Convention Documentation](https://develop.sentry.dev/sdk/performance/span-data-conventions.md). ```json { "data": { "url": "http://localhost:8080/sockjs-node/info?t=1588601703755", "status_code": 200, "type": "xhr", "method": "GET" } } ``` * `origin` *Optional*. The origin of the span indicates what created the span. For more details, see [trace origin](https://develop.sentry.dev/sdk/performance/trace-origin.md). ## [Examples](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/span.md#examples) The following example illustrates the Span as part of the [Transaction](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/transaction.md) and omits other attributes for simplicity. ```json { "spans": [ { "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee", "span_id": "b01b9f6349558cd1", "parent_span_id": "b0e6f15b45c36b12", "op": "http", "description": "GET /sockjs-node/info", "status": "ok", "start_timestamp": 1588601261.481961, "timestamp": 1588601261.488901, "tags": { "http.status_code": "200" }, "data": { "url": "http://localhost:8080/sockjs-node/info?t=1588601703755", "status_code": 200, "type": "xhr", "method": "GET" }, "origin": "auto.http" }, { "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee", "span_id": "b980d4dec78d7344", "parent_span_id": "9312d0d18bf51736", "op": "update", "description": "Vue ", "start_timestamp": 1588601261.535386, "timestamp": 1588601261.544196 } ] } ```