Sign In

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

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
}

contexts.trace
Recommended. A Transaction has to have a specific contexts.trace entry that contains tracing information. See the Trace Context documentation.

Copied
{
  "contexts": {
    "trace": {
      "op": "navigation",
      "description": "User clicked on <Link />",
      "trace_id": "743ad8bbfdd84e99bc38b4729e2864de",
      "span_id": "a0cfbde2bdff3adc",
      "status": "ok",
      "parent_span_id": "99659d76b7cdae94"
    }
  }
}

spans
Recommended. A list of Spans.

Copied
{
  "spans": [
    {
      "start_timestamp": 1588601261.481961,
      "description": "GET /sockjs-node/info",
      "tags": {
        "http.status_code": "200"
      },
      "timestamp": 1588601261.488901,
      "parent_span_id": "b0e6f15b45c36b12",
      "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
      "op": "http",
      "data": {
        "url": "http://localhost:8080/sockjs-node/info?t=1588601703755",
        "status_code": 200,
        "type": "xhr",
        "method": "GET"
      },
      "span_id": "b01b9f6349558cd1"
    },
    {
      "start_timestamp": 1588601261.535386,
      "description": "Vue <App>",
      "timestamp": 1588601261.544196,
      "parent_span_id": "9312d0d18bf51736",
      "trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
      "op": "update",
      "span_id": "b980d4dec78d7344"
    }
  ]
}

measurements
Optional. An object containing standard/custom measurements with keys signifying the name of the measurement.

  • Standard measurement keys currently supported are from the following list taken from here.
Copied
[
  // Web
  "fp",
  "fcp",
  "lcp",
  "fid",
  "cls",
  "ttfb",
  "ttfb.requesttime",

  // Mobile
  "app_start_cold",
  "app_start_warm",
  "frames_total",
  "frames_slow",
  "frames_frozen",

  // React native
  "frames_slow_rate",
  "frames_frozen_rate",
  "stall_count",
  "stall_total_time",
  "stall_longest_time",
  "stall_percentage"
]
  • For the well-known measurements listed above, Sentry automatically infers units. Custom measurements need units to be specified; if the units are missing, Relay will set them to "none" as a default. The full list of supported units is specified on Relay's MetricUnit. Sentry's event ingestion supports arbitrary custom units, but many SDKs will not expose a generic user-defined unit interface.
Copied
{
  "measurements": {
    "lcp": { "value": 100 },
    "fp": { "value": 123 },
    "my.custom.metric": { "value": 456, "unit": "millisecond" }
  }
}

transaction_info
Recommended. Additional information about the name of the transaction.

Copied
{
  "transaction_info": {
    "source": "route"
  }
}

transaction_info.source
Required. This information is required by dynamic sampling. Contains information about how the name of the transaction was determined. This will be used by the server to decide whether or not to scrub identifiers from the transaction name, or replace the entire name with a placeholder. The source should only be set by integrations and not by developers directly.

SourceDescription
Examples
customUser-defined name, see setTransactionName()my_transaction
urlRaw URL, potentially containing identifiers./auth/login/john123/
GET /auth/login/john123/
routeParametrized URL / route/auth/login/:userId/
GET /auth/login/{user}/
viewName of the view handling the request.UserListView
componentNamed after a software component, such as a function or class name.AuthLogin.login
LoginActivity.login_button
taskName of a background task (e.g. a Celery task)sentry.tasks.do_something
unknownValue set by Relay for legacy SDKs. SDKs must not set this value explicitly.

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.