Transaction Payloads

Transactions are used to send tracing events to Sentry.

Transactions must be wrapped in an Envelope and therefore also be sent to the Envelope endpoint.

Anatomy

A Transaction is basically a Span combined with an Event. When using tracing with our SDKs you usually create a Span tree, the root node and therefore the whole tree is considered to be the Transaction. So technically a Transaction is just a Span. A Transaction must also have a contexts.trace (which contains some data of the Span) and some other properties that will be covered in the next section.

Transactions are Events enriched with Span data. We are only going to list here what is important for a Transaction.

event_id

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

{
  "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}

tags

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

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

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

or:

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

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

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

[
  // 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.

{
  "measurements": {
    "lcp": { "value": 100 },
    "fp": { "value": 123 },
    "my.custom.metric": { "value": 456, "unit": "millisecond" }
  }
}

Transaction Annotations

transaction_info

Recommended. Additional information about the name of the transaction.

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