Event Payloads

Events are the fundamental data that clients, often through the use of an SDK, send to the Sentry server. Event payload size limit is 200kb.

The API endpoint on the Sentry server where event payloads are sent is /api/{PROJECT_ID}/store/.

Required Attributes

Attributes are simple data that Sentry understands to provide the most basic information about events. These are things like the unique ID of an event or the time when it occurred.

The following attributes are required for all events.

Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: the interface for a Sentry Span, the Relay spec for a Sentry Span and the spec for an OpenTelemetry span.

This is based on a mapping done as part of work on the OpenTelemetry Sentry Exporter.

Currently there is no spec for how Span.link in OpenTelemetry should appear in Sentry.

Span Status

In OpenTelemetry, Span Status is an enum of 3 values, while Sentry's Span Status is an enum of 17 values that map to the GRPC status codes. Each of the Sentry Span Status codes also map to HTTP codes. Sentry adopted it's Span Status spec from OpenTelemetry, who used the GRPC status code spec, but later on changed to the current spec it uses today.

To map from OpenTelemetry Span Status to, you need to rely on both OpenTelemetry Span Status and Span attributes. This approach was adapted from a PR by GH user @anguisa to the OpenTelemetry Sentry Exporter.

// OpenTelemetry span status can be Unset, Ok, Error. HTTP and Grpc codes contained in tags can make it more detailed.

// canonicalCodesHTTPMap maps some HTTP codes to Sentry's span statuses. See possible mapping in https://develop.sentry.dev/sdk/event-payloads/span/
var canonicalCodesHTTPMap = map[string]sentry.SpanStatus{
	"400": sentry.SpanStatusFailedPrecondition, // SpanStatusInvalidArgument, SpanStatusOutOfRange
	"401": sentry.SpanStatusUnauthenticated,
	"403": sentry.SpanStatusPermissionDenied,
	"404": sentry.SpanStatusNotFound,
	"409": sentry.SpanStatusAborted, // SpanStatusAlreadyExists
	"429": sentry.SpanStatusResourceExhausted,
	"499": sentry.SpanStatusCanceled,
	"500": sentry.SpanStatusInternalError, // SpanStatusDataLoss, SpanStatusUnknown
	"501": sentry.SpanStatusUnimplemented,
	"503": sentry.SpanStatusUnavailable,
	"504": sentry.SpanStatusDeadlineExceeded,
}

// canonicalCodesGrpcMap maps some GRPC codes to Sentry's span statuses. See description in grpc documentation.
var canonicalCodesGrpcMap = map[string]sentry.SpanStatus{
	"1":  sentry.SpanStatusCanceled,
	"2":  sentry.SpanStatusUnknown,
	"3":  sentry.SpanStatusInvalidArgument,
	"4":  sentry.SpanStatusDeadlineExceeded,
	"5":  sentry.SpanStatusNotFound,
	"6":  sentry.SpanStatusAlreadyExists,
	"7":  sentry.SpanStatusPermissionDenied,
	"8":  sentry.SpanStatusResourceExhausted,
	"9":  sentry.SpanStatusFailedPrecondition,
	"10": sentry.SpanStatusAborted,
	"11": sentry.SpanStatusOutOfRange,
	"12": sentry.SpanStatusUnimplemented,
	"13": sentry.SpanStatusInternalError,
	"14": sentry.SpanStatusUnavailable,
	"15": sentry.SpanStatusDataLoss,
	"16": sentry.SpanStatusUnauthenticated,
}

code := spanStatus.Code()
if code < 0 || int(code) > 2 {
    return sentry.SpanStatusUnknown, fmt.Sprintf("error code %d", code)
}
httpCode, foundHTTPCode := tags["http.status_code"]
grpcCode, foundGrpcCode := tags["rpc.grpc.status_code"]
var sentryStatus sentry.SpanStatus
switch {
case code == 1 || code == 0:
    sentryStatus = sentry.SpanStatusOK
case foundHTTPCode:
    httpStatus, foundHTTPStatus := canonicalCodesHTTPMap[httpCode]
    switch {
    case foundHTTPStatus:
        sentryStatus = httpStatus
    default:
        sentryStatus = sentry.SpanStatusUnknown
    }
case foundGrpcCode:
    grpcStatus, foundGrpcStatus := canonicalCodesGrpcMap[grpcCode]
    switch {
    case foundGrpcStatus:
        sentryStatus = grpcStatus
    default:
        sentryStatus = sentry.SpanStatusUnknown
    }
default:
    sentryStatus = sentry.SpanStatusUnknown
}
return sentryStatus

Span Events

OpenTelemetry, has the concept of Span Events. As per the spec:

An event is a human-readable message on a span that represents “something happening” during it’s lifetime

In Sentry, we have two options for how to treat span events. First, we can add them as breadcrumbs to the transaction the span belongs to. Second, we can create an artificial "point-in-time" span (a span with 0 duration), and add it to the span tree. TODO on what approach we take here.

In the special case that the span event is an exception span, where the name of the span event is exception, we also have the possibility of generating a Sentry error from an exception. In this case, we can create this exception based on the attributes of an event, which include the error message and stacktrace. This exception can also inherit all other attributes of the span event + span as tags on the event.

In the OpenTelemetry Sentry exporter, we've used this strategy to generate Sentry errors.

timestamp

Indicates when the event was created in the Sentry SDK. 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:36Z"
}

or:

{
  "timestamp": 1304358096.0
}

platform

A string representing the platform the SDK is submitting from. This will be used by the Sentry interface to customize various components in the interface.

{
  "platform": "python"
}

Acceptable values are:

• as3
• c
• cfml
• cocoa
• csharp
• elixir
• haskell
• go
• groovy
• java
• javascript
• native
• node
• objc
• other
• perl
• php
• python
• ruby

Optional Attributes

Additionally, there are several optional values which Sentry recognizes and are highly encouraged:

level

The record severity.

Defaults to error.

The value needs to be one on the supported level string values.

{
  "level": "warning"
}

Acceptable values are:

• fatal
• error
• warning
• info
• debug

logger

The name of the logger which created the record.

{
  "logger": "my.logger.name"
}

transaction

The name of the transaction which caused this exception.

For example, in a web app, this might be the route name.

{
  "transaction": "/users/<username>/"
}

server_name

Identifies the host from which the event was recorded.

{
  "server_name": "foo.example.com"
}

release

The release version of the application.

Release versions must be unique across all projects in your organization. This value can be the git SHA for the given project, or a product identifier with a semantic version (suggested format my-project-name@1.0.0).

{
  "release": "my-project-name@1.0.0"
}

dist

The distribution of the application.

Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an XCode build or the version code of an Android build.

{
  "release": "721e41770371db95eee98ca2707686226b993eda",
  "dist": "14G60"
}

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

environment

The environment name, such as production or staging. The default value should be production.

{
  "environment": "production"
}

modules

A list of relevant modules and their versions.

{
  "modules": {
    "my.module.name": "1.0"
  }
}

extra

An arbitrary mapping of additional metadata to store with the event.

{
  "extra": {
    "my_key": 1,
    "some_other_value": "foo bar"
  }
}

fingerprint

A list of strings used to dictate the deduplication of this event.

{
  "fingerprint": ["myrpc", "POST", "/foo.bar"]
}

For information about overriding grouping see Customize Grouping with Fingerprints.

errors

A list of errors in capturing or handling this event. This provides meta data about event capturing and processing itself, not about the error or transaction that the event represents.

This list is primarily populated by Sentry when receiving and processing the event. SDKs are only encouraged to add entries here if there are severe conditions that Sentry cannot detect by inspecting the remaining payload.

Errors must contain a required type field, which can be one of the types declared in the Sentry EventError model. If there is no applicable type variant, consider opening an issue to suggest the addition.

Apart from types, any attribute is valid. There are conventions for the semantics of common error attributes, if they are included:

• name: A string declaring the path to the payload field that causes or exhibits the error. For example modules[0].name.
• value: The original value of a field that causes or exhibits the error.

{
  "errors": [
    {
      "type": "unknown_error",
      "path": "/var/logs/errors.log.1",
      "details": "Failed to read attachment"
    }
  ]
}

Core Interfaces

All values in the event payload that are not basic attributes are data interfaces. The key is the canonical interface short name, and the value is the data expected by the interface (usually a dictionary).

For the most part, interfaces are an evolving part of Sentry. Like with attributes, SDKs are expected to assume that more interfaces will be added at any point in the future.

The core data interfaces are:

• Exception Interface
• Message Interface
• Stack Trace Interface
• Template Interface

Scope Interfaces

• Breadcrumbs Interface
• User Interface
• Request Interface
• Contexts Interface
• Threads Interface

Other Interfaces

• Debug Meta Interface
• SDK Interface

Type Definitions

• Event Type Definitions