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.

Attributes

event_id
Required. Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes are not allowed. Has to be lowercase.

Copied
{
  "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}

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"
  }
}

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"
  }
}

Examples

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"
      }
    },
    {
      "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
      "span_id": "b980d4dec78d7344",
      "parent_span_id": "9312d0d18bf51736",
      "op": "update",
      "description": "Vue <App>",
      "start_timestamp": 1588601261.535386,
      "timestamp": 1588601261.544196
    }
  ]
}
You can edit this page on GitHub.