Span Interface

The Span Interface specifies a series of timed application events that have a start and end time.

A Transaction 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.

span_id:

Required. A random hex string with a length of 16 characters.

Copied
{
  "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.

Copied
{
  "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).

Copied
{
  "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.

Copied
{
  "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.

Copied
{
  "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 or a numeric (integer or float) value representing the number of seconds that have elapsed since the Unix epoch. The start_timestamp value must be less than or equal to the timestamp value, otherwise the Span is discarded as invalid.

Copied
{
  "start_timestamp": "2011-05-02T17:41:36.242Z"
}

or:

Copied
{
  "start_timestamp": 1304358096.242
}

timestamp

Required. A timestamp representing when the measuring finished. The format is either a string as defined in RFC 3339 or a numeric (integer or float) value representing the number of seconds that have elapsed since the Unix epoch.

Copied
{
  "timestamp": "2011-05-02T17:41:36.955Z"
}

or:

Copied
{
  "timestamp": 1304358096.955
}

status

Optional. Describes the status of the Span/Transaction.

StateDescriptionHTTP status code equivalent
okNot an error, returned on success200 and 2XX HTTP statuses
cancelledThe operation was cancelled, typically by the caller499
unknown or unknown_errorAn unknown error raised by APIs that don't return enough error information500
invalid_argumentThe client specified an invalid argument400
deadline_exceededThe deadline expired before the operation could succeed504
not_foundContent was not found or request was denied for an entire class of users404
already_existsThe entity attempted to be created already exists409
permission_deniedThe caller doesn't have permission to execute the specified operation403
resource_exhaustedThe resource has been exhausted e.g. per-user quota exhausted, file system out of space429
failed_preconditionThe client shouldn't retry until the system state has been explicitly handled400
abortedThe operation was aborted409
out_of_rangeThe operation was attempted past the valid range e.g. seeking past the end of a file400
unimplementedThe operation is not implemented or is not supported/enabled for this operation501
internal_errorSome invariants expected by the underlying system have been broken. This code is reserved for serious errors500
unavailableThe service is currently available e.g. as a transient condition503
data_lossUnrecoverable data loss or corruption500
unauthenticatedThe requester doesn't have valid authentication credentials for the operation401
Copied
{
  "status": "ok"
}

tags

Optional. A map or list of tags for this event. Each tag must be less than 200 characters.

Copied
{
  "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.

Copied
{
  "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.

The following example illustrates the Span as part of the Transaction and omits other attributes for simplicity.

Copied
{
  "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 <App>",
      "start_timestamp": 1588601261.535386,
      "timestamp": 1588601261.544196
    }
  ]
}
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").