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.
Note on backwards compatibility
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"
}
}
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).
{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee"
}
contexts.trace
A Transaction has to have a specific contexts.trace
entry that contains data from the Span.
op
- Recommended. Short code identifying the type of operation the span is measuring.
For more details, see Sentry's conventions around span operations.
{
"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.
{
"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 thetimestamp
value, otherwise the Span is discarded as invalid.
{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}
or:
{
"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.
{
"timestamp": "2011-05-02T17:41:36.955Z"
}
or:
{
"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 |
{
"status": "ok"
}
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"
}
}
Examples
{
"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
"stall_count",
"stall_total_time",
"stall_longest_time"
]
For the well-known measurements listed above, Sentry automatically infers units. Custom measurements need units to be specified, defaulting to "none"
if missing. 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": "url"
}
}
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.
Source | Description | Examples |
---|---|---|
custom | User-defined name, see setTransactionName() | my_transaction |
url | Raw URL, potentially containing identifiers. | /auth/login/john123/ GET /auth/login/john123/ |
route | Parametrized URL / route | /auth/login/:userId/ GET /auth/login/{user}/ |
view | Name of the view handling the request. | UserListView |
component | Named after a software component, such as a function or class name. | AuthLogin.login LoginActivity.login_button |
task | Name of a background task (e.g. a Celery task) | sentry.tasks.do_something |
unknown | Value set by Relay for legacy SDKs. SDKs must not set this value explicitly. |