Event Type Definitions

This page documents the event schema for errors, just like the other documents at Event Payloads do. However, the sections here are automatically generated from code, and because of that they are more complete and less out of date. We intend to make this page the single source of truth and replace all the other "interface" pages, but there is still some work to be done to make this more human-readable.

Go to our schemas repo to learn more.

Event

The sentry v7 event structure.

Properties:

breadcrumbs (optional): null | Breadcrumbs
List of breadcrumbs recorded before this event.
contexts (optional): { [key: string]: null | (DeviceContext | OSContext | RuntimeContext | AppContext | BrowserContext | GPUContext | TraceContext | ResponseContext | OtelContext | { [key: string]: any }) } | null
Contexts describing the environment (e.g. device, os or browser).
culprit (optional): null | string
Custom culprit of the event.
This field is deprecated and shall not be set by client SDKs.
debug_meta (optional): DebugMeta | null
Meta data for event processing and debugging.
dist (optional): null | string
Program's distribution identifier.
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.
environment (optional): null | string
The environment name, such as production or staging.
Copied
{ "environment": "production" }
errors (optional): Array<EventProcessingError | null> | null
Errors encountered during processing. Intended to be phased out in favor of annotation/metadata system.
event_id (optional): null | string
Unique identifier of this event.
Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes are not allowed. Has to be lowercase.
Even though this field is backfilled on the server with a new uuid4, it is strongly recommended to generate that uuid4 clientside. There are some features like user feedback which are easier to implement that way, and debugging in case events get lost in your Sentry installation is also easier.
Example:
Copied
{ "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0" }
exception (optional): null | Exception
One or multiple chained (nested) exceptions.

extra (optional): { [key: string]: any } | null

Arbitrary extra information set by the user.

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

fingerprint (optional): string[] | null
Manual fingerprint override.
A list of strings used to dictate how this event is supposed to be grouped with other events into issues. For more information about overriding grouping see Customize Grouping with Fingerprints.
Copied
{ "fingerprint": ["myrpc", "POST", "/foo.bar"] }
level (optional): Level | null
Severity level of the event. Defaults to error.
Example:
Copied
{"level": "warning"}
logentry (optional): LogEntry | null
Custom parameterized message for this event.
logger (optional): null | string
Logger that created the event.
modules (optional): { [key: string]: null | string } | null
Name and versions of all installed modules/packages/dependencies in the current environment/application.
Copied
{ "django": "3.0.0", "celery": "4.2.1" }
In Python this is a list of installed packages as reported by pkg_resources together with their reported version string.
This is primarily used for suggesting to enable certain SDK integrations from within the UI and for making informed decisions on which frameworks to support in future development efforts.
platform (optional): null | string
Platform identifier of this event (defaults to "other").
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, but also to enter or skip stacktrace processing.
Acceptable values are: as3, c, cfml, cocoa, csharp, elixir, haskell, go, groovy, java, javascript, native, node, objc, other, perl, php, python, ruby
received (optional): null | (number | string)
Timestamp when the event has been received by Sentry.
release (optional): null | string
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.
request (optional): Request | null
Information about a web request that occurred during the event.
sdk (optional): ClientSDKInfo | null
Information about the Sentry SDK that generated this event.
server_name (optional): null | string
Server or device name the event was generated on.
This is supposed to be a hostname.
stacktrace (optional): Stacktrace | null
Event stacktrace.
DEPRECATED: Prefer threads or exception depending on which is more appropriate.
tags (optional): null | (Array<Array<(null | string)> | null> | { [key: string]: null | string })
Custom tags for this event.
A map or list of tags for this event. Each tag must be less than 200 characters.
threads (optional): null | Threads
Threads that were active when the event occurred.
time_spent (optional): number | null
Time since the start of the transaction until the error occurred.
timestamp (optional): null | (number | string)
Timestamp when the event was created.
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.
Timezone is assumed to be UTC if missing.
Sub-microsecond precision is not preserved with numeric values due to precision limitations with floats (at least in our systems). With that caveat in mind, just send whatever is easiest to produce.
All timestamps in the event protocol are formatted this way.
Example
All of these are the same date:
Copied
{ "timestamp": "2011-05-02T17:41:36Z" } { "timestamp": "2011-05-02T17:41:36" } { "timestamp": "2011-05-02T17:41:36.000" } { "timestamp": 1304358096.0 }
transaction (optional): null | string
Transaction name of the event.
For example, in a web app, this might be the route name ("/users/<username>/" or UserView), in a task queue it might be the function + module name.
transaction_info (optional): TransactionInfo | null
Additional information about the name of the transaction.
type (optional): EventType | null
Type of the event. Defaults to default.
The event type determines how Sentry handles the event and has an impact on processing, rate limiting, and quotas. There are three fundamental classes of event types:
Copied
- **Error monitoring events**: Processed and grouped into unique issues based on their exception stack traces and error messages. - **Security events**: Derived from Browser security violation reports and grouped into unique issues based on the endpoint and violation. SDKs do not send such events. - **Transaction events** (`transaction`): Contain operation spans and collected into traces for performance monitoring.
Transactions must explicitly specify the "transaction" event type. In all other cases, Sentry infers the appropriate event type from the payload and overrides the stated type. SDKs should not send an event type other than for transactions.
Example:
Copied
{ "type": "transaction", "spans": [] }
user (optional): User | null
Information about the user who triggered this event.
version (optional): null | string
Version

Breadcrumbs

Properties:

values: Array<Breadcrumb | null>

The Breadcrumbs Interface specifies a series of application events, or "breadcrumbs", that occurred before an event.

An event may contain one or more breadcrumbs in an attribute named breadcrumbs. The entries are ordered from oldest to newest. Consequently, the last entry in the list should be the last entry before the event occurred.

While breadcrumb attributes are not strictly validated in Sentry, a breadcrumb is most useful when it includes at least a timestamp and type, category or message. The rendering of breadcrumbs in Sentry depends on what is provided.

The following example illustrates the breadcrumbs part of the event payload and omits other attributes for simplicity.

Copied
{
  "breadcrumbs": {
    "values": [
      {
        "timestamp": "2016-04-20T20:55:53.845Z",
        "message": "Something happened",
        "category": "log",
        "data": {
          "foo": "bar",
          "blub": "blah"
        }
      },
      {
        "timestamp": "2016-04-20T20:55:53.847Z",
        "type": "navigation",
        "data": {
          "from": "/login",
          "to": "/dashboard"
        }
      }
    ]
  }
}

Properties:

category (optional): null | string
A dotted string indicating what the crumb is or from where it comes. Optional.
Typically it is a module name or a descriptive string. For instance, ui.click could be used to indicate that a click happened in the UI or flask could be used to indicate that the event originated in the Flask framework.
data (optional): { [key: string]: any } | null
Arbitrary data associated with this breadcrumb.
Contains a dictionary whose contents depend on the breadcrumb type. Additional parameters that are unsupported by the type are rendered as a key/value table.
event_id (optional): null | string
Identifier of the event this breadcrumb belongs to.
Sentry events can appear as breadcrumbs in other events as long as they have occurred in the same organization. This identifier links to the original event.
level (optional): Level | null
Severity level of the breadcrumb. Optional.
Allowed values are, from highest to lowest: fatal, error, warning, info, and debug. Levels are used in the UI to emphasize and deemphasize the crumb. Defaults to info.
message (optional): null | string
Human readable message for the breadcrumb.
If a message is provided, it is rendered as text with all whitespace preserved. Very long text might be truncated in the UI.
timestamp (optional): null | (number | string)
The timestamp of the breadcrumb. Recommended.
A timestamp representing when the breadcrumb occurred. 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.
Breadcrumbs are most useful when they include a timestamp, as it creates a timeline leading up to an event.
type (optional): null | string
The type of the breadcrumb. Optional, defaults to default.
- default: Describes a generic breadcrumb. This is typically a log message or user-generated breadcrumb. The data field is entirely undefined and as such, completely rendered as a key/value table.
- navigation: Describes a navigation breadcrumb. A navigation event can be a URL change in a web application, or a UI transition in a mobile or desktop application, etc.
  Such a breadcrumb's data object has the required fields from and to, which represent an application route/url each.
- http: Describes an HTTP request breadcrumb. This represents an HTTP request transmitted from your application. This could be an AJAX request from a web application, or a server-to-server HTTP request to an API service provider, etc.
  Such a breadcrumb's data property has the fields url, method, status_code (integer) and reason (string).

Level

Severity level of an event or breadcrumb.

Variants:

"debug"
"error"
"fatal"
"info"
"warning"

DeviceContext

Device information.

Device context describes the device that caused the event. This is most appropriate for mobile applications.

Properties:

arch (optional): null | string
Native cpu architecture of the device.
battery_level (optional): number | null
Current battery level in %.
If the device has a battery, this can be a floating point value defining the battery level (in the range 0-100).
battery_status (optional): null | string
Status of the device's battery.
For example, Unknown, Charging, Discharging, NotCharging, Full.
boot_time (optional): null | string
Indicator when the device was booted.
brand (optional): null | string
Brand of the device.
charging (optional): boolean | null
Whether the device was charging or not.
cpu_description (optional): null | string
CPU description.
For example, Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz.
device_type (optional): null | string
Kind of device the application is running on.
For example, Unknown, Handheld, Console, Desktop.
device_unique_identifier (optional): null | string
Unique device identifier.
external_free_storage (optional): number | null
Free size of the attached external storage in bytes (eg: android SDK card).
external_storage_size (optional): number | null
Total size of the attached external storage in bytes (eg: android SDK card).
family (optional): null | string
Family of the device model.
This is usually the common part of model names across generations. For instance, iPhone would be a reasonable family, so would be Samsung Galaxy.
free_memory (optional): number | null
How much memory is still available in bytes.
free_storage (optional): number | null
How much storage is free in bytes.
low_memory (optional): boolean | null
Whether the device was low on memory.
manufacturer (optional): null | string
Manufacturer of the device.
memory_size (optional): number | null
Total memory available in bytes.
model (optional): null | string
Device model.
This, for example, can be Samsung Galaxy S3.
model_id (optional): null | string
Device model (internal identifier).
An internal hardware revision to identify the device exactly.
name (optional): null | string
Name of the device.
online (optional): boolean | null
Whether the device was online or not.
orientation (optional): null | string
Current screen orientation.
This can be a string portrait or landscape to define the orientation of a device.
processor_count (optional): number | null
Number of "logical processors".
For example, 8.
processor_frequency (optional): number | null
Processor frequency in MHz.
Note that the actual CPU frequency might vary depending on current load and power conditions, especially on low-powered devices like phones and laptops.
screen_density (optional): number | null
Device screen density.
screen_dpi (optional): number | null
Screen density as dots-per-inch.
screen_resolution (optional): null | string
Device screen resolution.
(e.g.: 800x600, 3040x1444)
simulator (optional): boolean | null
Simulator/prod indicator.
storage_size (optional): number | null
Total storage size of the device in bytes.
supports_accelerometer (optional): boolean | null
Whether the accelerometer is available on the device.
supports_audio (optional): boolean | null
Whether audio is available on the device.
supports_gyroscope (optional): boolean | null
Whether the gyroscope is available on the device.
supports_location_service (optional): boolean | null
Whether location support is available on the device.
supports_vibration (optional): boolean | null
Whether vibration is available on the device.
timezone (optional): null | string
Timezone of the device.
usable_memory (optional): number | null
How much memory is usable for the app in bytes.

OSContext

Operating system information.

OS context describes the operating system on which the event was created. In web contexts, this is the operating system of the browser (generally pulled from the User-Agent string).

Properties:

build (optional): null | string
Internal build number of the operating system.
kernel_version (optional): null | string
Current kernel version.
This is typically the entire output of the uname syscall.
name (optional): null | string
Name of the operating system.
raw_description (optional): null | string
Unprocessed operating system info.
An unprocessed description string obtained by the operating system. For some well-known runtimes, Sentry will attempt to parse name and version from this string, if they are not explicitly given.
rooted (optional): boolean | null
Indicator if the OS is rooted (mobile mostly).
version (optional): null | string
Version of the operating system.

RuntimeContext

Runtime information.

Runtime context describes a runtime in more detail. Typically, this context is present in contexts multiple times if multiple runtimes are involved (for instance, if you have a JavaScript application running on top of JVM).

Properties:

build (optional): null | string
Application build string, if it is separate from the version.
name (optional): null | string
Runtime name.
raw_description (optional): null | string
Unprocessed runtime info.
An unprocessed description string obtained by the runtime. For some well-known runtimes, Sentry will attempt to parse name and version from this string, if they are not explicitly given.
version (optional): null | string
Runtime version string.

AppContext

Application information.

App context describes the application. As opposed to the runtime, this is the actual application that was running and carries metadata about the current session.

Properties:

app_build (optional): null | string
Internal build ID as it appears on the platform.
app_identifier (optional): null | string
Version-independent application identifier, often a dotted bundle ID.
app_memory (optional): number | null
Amount of memory used by the application in bytes.
app_name (optional): null | string
Application name as it appears on the platform.
app_start_time (optional): null | string
Start time of the app.
Formatted UTC timestamp when the user started the application.
app_version (optional): null | string
Application version as it appears on the platform.
build_type (optional): null | string
String identifying the kind of build. For example, testflight.
device_app_hash (optional): null | string
Application-specific device identifier.
in_foreground (optional): boolean | null
A flag indicating whether the app is in foreground or not. An app is in foreground when it's visible to the user.

BrowserContext

Web browser information.

Properties:

name (optional): null | string
Display name of the browser application.
version (optional): null | string
Version string of the browser.

GPUContext

GPU information.

Example:

Copied
"gpu": {
  "name": "AMD Radeon Pro 560",
  "vendor_name": "Apple",
  "memory_size": 4096,
  "api_type": "Metal",
  "multi_threaded_rendering": true,
  "version": "Metal",
  "npot_support": "Full"
}

Properties:

api_type (optional): null | string
The device low-level API type.
Examples: "Apple Metal" or "Direct3D11"
graphics_shader_level (optional): null | string
Approximate "shader capability" level of the graphics device.
For Example: Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)
id (optional): any
The PCI identifier of the graphics device.
max_texture_size (optional): number | null
Largest size of a texture that is supported by the graphics hardware.
For Example: 16384
memory_size (optional): number | null
The total GPU memory available in Megabytes.
multi_threaded_rendering (optional): boolean | null
Whether the GPU has multi-threaded rendering or not.
name (optional): null | string
The name of the graphics device.
npot_support (optional): null | string
The Non-Power-Of-Two support.
supports_compute_shaders (optional): boolean | null
Whether compute shaders are available on the device.
supports_draw_call_instancing (optional): boolean | null
Whether GPU draw call instancing is supported.
supports_geometry_shaders (optional): boolean | null
Whether geometry shaders are available on the device.
supports_ray_tracing (optional): boolean | null
Whether ray tracing is available on the device.
vendor_id (optional): null | string
The PCI vendor identifier of the graphics device.
vendor_name (optional): null | string
The vendor name as reported by the graphics device.
version (optional): null | string
The Version of the graphics device.

TraceContext

Trace context

Properties:

client_sample_rate (optional): number | null
The client-side sample rate as reported in the envelope's trace.sample_rate header.
The server takes this field from envelope headers and writes it back into the event. Clients should not ever send this value.
exclusive_time (optional): number | null
The amount of time in milliseconds spent in this transaction span, excluding its immediate child spans.
op (optional): null | string
Span type (see OperationType docs).
parent_span_id (optional): null | string
The ID of the span enclosing this span.
span_id: null | string
The ID of the span.
status (optional): SpanStatus | null
Whether the trace failed or succeeded. Currently only used to indicate status of individual transactions.
trace_id: null | string
The trace ID.

SpanStatus

Trace status.

Values from https://github.com/open-telemetry/opentelemetry-specification/blob/8fb6c14e4709e75a9aaa64b0dbbdf02a6067682a/specification/api-tracing.md#status Mapping to HTTP from https://github.com/open-telemetry/opentelemetry-specification/blob/8fb6c14e4709e75a9aaa64b0dbbdf02a6067682a/specification/data-http.md#status

Variants:

"aborted"
"already_exists"
"cancelled"
"data_loss"
"deadline_exceeded"
"failed_precondition"
"internal_error"
"invalid_argument"
"not_found"
"ok"
"out_of_range"
"permission_denied"
"resource_exhausted"
"unauthenticated"
"unavailable"
"unimplemented"
"unknown"

ResponseContext

Response interface that contains information on a HTTP response related to the event.

Properties:

body_size (optional): number | null
HTTP response body size.
cookies (optional): null | (Array<Array<(null | string)> | null> | { [key: string]: null | string })
The cookie values.
Can be given unparsed as string, as dictionary, or as a list of tuples.
headers (optional): null | (Array<Array<(null | string)> | null> | { [key: string]: null | string })
A dictionary of submitted headers.
If a header appears multiple times it, needs to be merged according to the HTTP standard for header merging. Header names are treated case-insensitively by Sentry.
status_code (optional): number | null
HTTP status code.

OtelContext

OpenTelemetry Context

If an event has this context, it was generated from an OpenTelemetry signal (trace, metric, log).

Properties:

attributes (optional): { [key: string]: any } | null
Attributes of the OpenTelemetry span that maps to a Sentry event.
https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186
resource (optional): { [key: string]: any } | null
Information about an OpenTelemetry resource.
https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/resource/v1/resource.proto

DebugMeta

Debugging and processing meta information.

The debug meta interface carries debug information for processing errors and crash reports. Sentry amends the information in this interface.

Example (look at field types to see more detail):

Copied
{
  "debug_meta": {
    "images": [],
    "sdk_info": {
      "sdk_name": "iOS",
      "version_major": 10,
      "version_minor": 3,
      "version_patchlevel": 0
    }
  }
}

Properties:

images (optional): Array<null | (AppleDebugImage | NativeDebugImage | ProguardDebugImage | { [key: string]: any })> | null
List of debug information files (debug images).
sdk_info (optional): SystemSDKInfo | null
Information about the system SDK (e.g. iOS SDK).

AppleDebugImage

Legacy apple debug images (MachO).

This was also used for non-apple platforms with similar debug setups.

Properties:

arch (optional): null | string
CPU architecture target.
cpu_subtype (optional): number | null
MachO CPU subtype identifier.
cpu_type (optional): number | null
MachO CPU type identifier.
image_addr: null | string
Starting memory address of the image (required).
image_size: number | null
Size of the image in bytes (required).
image_vmaddr (optional): null | string
Loading address in virtual memory.
name: null | string
Path and name of the debug image (required).
uuid: null | string
The unique UUID of the image.

NativeDebugImage

A generic (new-style) native platform debug information file.

The type key must be one of:

macho
elf: ELF images are used on Linux platforms. Their structure is identical to other native images.

pe

Examples:

Copied
{
  "type": "elf",
  "code_id": "68220ae2c65d65c1b6aaa12fa6765a6ec2f5f434",
  "code_file": "/lib/x86_64-linux-gnu/libgcc_s.so.1",
  "debug_id": "e20a2268-5dc6-c165-b6aa-a12fa6765a6e",
  "image_addr": "0x7f5140527000",
  "image_size": 90112,
  "image_vmaddr": "0x40000",
  "arch": "x86_64"
}

Properties:

arch (optional): null | string
CPU architecture target.
Architecture of the module. If missing, this will be backfilled by Sentry.
code_file: null | string
Path and name of the image file (required).
The absolute path to the dynamic library or executable. This helps to locate the file if it is missing on Sentry.
- pe: The code file should be provided to allow server-side stack walking of binary crash reports, such as Minidumps.
code_id (optional): null | string
Optional identifier of the code file.
- elf: If the program was compiled with a relatively recent compiler, this should be the hex representation of the NT_GNU_BUILD_ID program header (type PT_NOTE), or the value of the .note.gnu.build-id note section (type SHT_NOTE). Otherwise, leave this value empty.
  Certain symbol servers use the code identifier to locate debug information for ELF images, in which case this field should be included if possible.
- pe: Identifier of the executable or DLL. It contains the values of the time_date_stamp from the COFF header and size_of_image from the optional header formatted together into a hex string using %08x%X (note that the second value is not padded):
  Copied
  time_date_stamp: 0x5ab38077 size_of_image: 0x9000 code_id: 5ab380779000
  The code identifier should be provided to allow server-side stack walking of binary crash reports, such as Minidumps.
- macho: Identifier of the dynamic library or executable. It is the value of the LC_UUID load command in the Mach header, formatted as UUID. Can be empty for Mach images, as it is equivalent to the debug identifier.
debug_checksum (optional): null | string
The optional checksum of the debug companion file.
- pe_dotnet: This is the hash algorithm and hex-formatted checksum of the associated PDB file. This should have the format $algorithm:$hash, for example SHA256:aabbccddeeff....
  See: https://github.com/dotnet/runtime/blob/main/docs/design/specs/PE-COFF.md#pdb-checksum-debug-directory-entry-type-19
debug_file (optional): null | string
Path and name of the debug companion file.
- elf: Name or absolute path to the file containing stripped debug information for this image. This value might be required to retrieve debug files from certain symbol servers.
- pe: Name of the PDB file containing debug information for this image. This value is often required to retrieve debug files from specific symbol servers.
- macho: Name or absolute path to the dSYM file containing debug information for this image. This value might be required to retrieve debug files from certain symbol servers.
debug_id: null | string
Unique debug identifier of the image.
- elf: Debug identifier of the dynamic library or executable. If a code identifier is available, the debug identifier is the little-endian UUID representation of the first 16-bytes of that identifier. Spaces are inserted for readability, note the byte order of the first fields:
  Copied
  code id: f1c3bcc0 2798 65fe 3058 404b2831d9e6 4135386c debug id: c0bcc3f1-9827-fe65-3058-404b2831d9e6
  If no code id is available, the debug id should be computed by XORing the first 4096 bytes of the .text section in 16-byte chunks, and representing it as a little-endian UUID (again swapping the byte order).
- pe: signature and age of the PDB file. Both values can be read from the CodeView PDB70 debug information header in the PE. The value should be represented as little-endian UUID, with the age appended at the end. Note that the byte order of the UUID fields must be swapped (spaces inserted for readability):
  Copied
  signature: f1c3bcc0 2798 65fe 3058 404b2831d9e6 age: 1 debug_id: c0bcc3f1-9827-fe65-3058-404b2831d9e6-1
- macho: Identifier of the dynamic library or executable. It is the value of the LC_UUID load command in the Mach header, formatted as UUID.
image_addr (optional): null | string
Starting memory address of the image (required).
Memory address, at which the image is mounted in the virtual address space of the process. Should be a string in hex representation prefixed with "0x".
image_size (optional): number | null
Size of the image in bytes (required).
The size of the image in virtual memory. If missing, Sentry will assume that the image spans up to the next image, which might lead to invalid stack traces.
image_vmaddr (optional): null | string
Loading address in virtual memory.
Preferred load address of the image in virtual memory, as declared in the headers of the image. When loading an image, the operating system may still choose to place it at a different address.
Symbols and addresses in the native image are always relative to the start of the image and do not consider the preferred load address. It is merely a hint to the loader.
- elf/macho: If this value is non-zero, all symbols and addresses declared in the native image start at this address, rather than 0. By contrast, Sentry deals with addresses relative to the start of the image. For example, with image_vmaddr: 0x40000, a symbol located at 0x401000 has a relative address of 0x1000.
  Relative addresses used in Apple Crash Reports and addr2line are usually in the preferred address space, and not relative address space.

ProguardDebugImage

Proguard mapping file.

Proguard images refer to mapping.txt files generated when Proguard obfuscates function names. The Java SDK integrations assign this file a unique identifier, which has to be included in the list of images.

Properties:

uuid: null | string
UUID computed from the file contents, assigned by the Java SDK.

SystemSDKInfo

Holds information about the system SDK.

This is relevant for iOS and other platforms that have a system SDK. Not to be confused with the client SDK.

Properties:

sdk_name (optional): null | string
The internal name of the SDK.
version_major (optional): number | null
The major version of the SDK as integer or 0.
version_minor (optional): number | null
The minor version of the SDK as integer or 0.
version_patchlevel (optional): number | null
The patch version of the SDK as integer or 0.

EventProcessingError

An event processing error.

Properties:

name (optional): null | string
Affected key or deep path.
type: null | string
The error kind.
value (optional): any
The original value causing this error.

Exception

Properties:

values: Array<ValueClass | null>

ValueClass

A single exception.

Multiple values inside of an event represent chained exceptions and should be sorted oldest to newest. For example, consider this Python code snippet:

Copied
try:
    raise Exception("random boring invariant was not met!")
except Exception as e:
    raise ValueError("something went wrong, help!") from e

Exception would be described first in the values list, followed by a description of ValueError:

Copied
{
  "exception": {
    "values": [
      {"type": "Exception": "value": "random boring invariant was not met!"},
      {"type": "ValueError", "value": "something went wrong, help!"},
    ]
  }
}

Properties:

mechanism (optional): Mechanism | null
Mechanism by which this exception was generated and handled.
module (optional): null | string
The optional module, or package which the exception type lives in.
stacktrace (optional): Stacktrace | null
Stack trace containing frames of this exception.
thread_id (optional): null | (number | string)
An optional value that refers to a thread.
type (optional): null | string
Exception type, e.g. ValueError.
At least one of type or value is required, otherwise the exception is discarded.
value (optional): null | string
Human readable display value.
At least one of type or value is required, otherwise the exception is discarded.

Mechanism

The mechanism by which an exception was generated and handled.

The exception mechanism is an optional field residing in the exception. It carries additional information about the way the exception was created on the target system. This includes general exception values obtained from the operating system or runtime APIs, as well as mechanism-specific values.

Properties:

data (optional): { [key: string]: any } | null
Arbitrary extra data that might help the user understand the error thrown by this mechanism.
description (optional): null | string
Optional human-readable description of the error mechanism.
May include a possible hint on how to solve this error.
handled (optional): boolean | null
Flag indicating whether this exception was handled.
This is a best-effort guess at whether the exception was handled by user code or not. For example:
- Exceptions leading to a 500 Internal Server Error or to a hard process crash are handled=false, as the SDK typically has an integration that automatically captures the error.
- Exceptions captured using capture_exception (called from user code) are handled=true as the user explicitly captured the exception (and therefore kind of handled it)
help_link (optional): null | string
Link to online resources describing this error.
meta (optional): MechanismMeta | null
Operating system or runtime meta information.
synthetic (optional): boolean | null
If this is set then the exception is not a real exception but some form of synthetic error for instance from a signal handler, a hard segfault or similar where type and value are not useful for grouping or display purposes.
type: null | string
Mechanism type (required).
Required unique identifier of this mechanism determining rendering and processing of the mechanism data.
In the Python SDK this is merely the name of the framework integration that produced the exception, while for native it is e.g. "minidump" or "applecrashreport".

MechanismMeta

Operating system or runtime meta information to an exception mechanism.

The mechanism metadata usually carries error codes reported by the runtime or operating system, along with a platform-dependent interpretation of these codes. SDKs can safely omit code names and descriptions for well-known error codes, as it will be filled out by Sentry. For proprietary or vendor-specific error codes, adding these values will give additional information to the user.

Properties:

errno (optional): CError | null
Optional ISO C standard error code.
mach_exception (optional): MachException | null
A Mach Exception on Apple systems comprising a code triple and optional descriptions.
ns_error (optional): NSError | null
An NSError on Apple systems comprising code and signal.
signal (optional): POSIXSignal | null
Information on the POSIX signal.

CError

POSIX signal with optional extended data.

Error codes set by Linux system calls and some library functions as specified in ISO C99, POSIX.1-2001, and POSIX.1-2008. See errno(3) for more information.

Properties:

name (optional): null | string
Optional name of the errno constant.
number (optional): number | null
The error code as specified by ISO C99, POSIX.1-2001 or POSIX.1-2008.

MachException

Mach exception information.

Properties:

code (optional): number | null
The mach exception code.
exception (optional): number | null
The mach exception type.
name (optional): null | string
Optional name of the mach exception.
subcode (optional): number | null
The mach exception subcode.

NSError

NSError informaiton.

Properties:

code (optional): number | null
The error code.
domain (optional): null | string
A string containing the error domain.

POSIXSignal

POSIX signal with optional extended data.

On Apple systems, signals also carry a code in addition to the signal number describing the signal in more detail. On Linux, this code does not exist.

Properties:

code (optional): number | null
An optional signal code present on Apple systems.
code_name (optional): null | string
Optional name of the errno constant.
name (optional): null | string
Optional name of the errno constant.
number (optional): number | null
The POSIX signal number.

Stacktrace

A stack trace of a single thread.

A stack trace contains a list of frames, each with various bits (most optional) describing the context of that frame. Frames should be sorted from oldest to newest.

For the given example program written in Python:

Copied
def foo():
    my_var = 'foo'
    raise ValueError()

def main():
    foo()

A minimalistic stack trace for the above program in the correct order:

Copied
{
  "frames": [
    {"function": "main"},
    {"function": "foo"}
  ]
}

The top frame fully symbolicated with five lines of source context:

Copied
{
  "frames": [{
    "in_app": true,
    "function": "myfunction",
    "abs_path": "/real/file/name.py",
    "filename": "file/name.py",
    "lineno": 3,
    "vars": {
      "my_var": "'value'"
    },
    "pre_context": [
      "def foo():",
      "  my_var = 'foo'",
    ],
    "context_line": "  raise ValueError()",
    "post_context": [
      "",
      "def main():"
    ],
  }]
}

A minimal native stack trace with register values. Note that the package event attribute must be "native" for these frames to be symbolicated.

Copied
{
  "frames": [
    {"instruction_addr": "0x7fff5bf3456c"},
    {"instruction_addr": "0x7fff5bf346c0"},
  ],
  "registers": {
    "rip": "0x00007ff6eef54be2",
    "rsp": "0x0000003b710cd9e0"
  }
}

Properties:

frames: Array<Frame | null> | null
Required. A non-empty list of stack frames. The list is ordered from caller to callee, or oldest to youngest. The last frame is the one creating the exception.
lang (optional): null | string
The language of the stacktrace.
registers (optional): { [key: string]: null | string } | null
Register values of the thread (top frame).
A map of register names and their values. The values should contain the actual register values of the thread, thus mapping to the last frame in the list.
snapshot (optional): boolean | null
Indicates that this stack trace is a snapshot triggered by an external signal.
If this field is false, then the stack trace points to the code that caused this stack trace to be created. This can be the location of a raised exception, as well as an exception or signal handler.
If this field is true, then the stack trace was captured as part of creating an unrelated event. For example, a thread other than the crashing thread, or a stack trace computed as a result of an external kill signal.

Frame

Holds information about a single stacktrace frame.

Each object should contain at least a filename, function or instruction_addr attribute. All values are optional, but recommended.

Properties:

abs_path (optional): null | string
Absolute path to the source file.
addr_mode (optional): null | string
Defines the addressing mode for addresses.
This can be:
- "abs" (the default): instruction_addr is absolute.
- "rel:$idx": instruction_addr is relative to the debug_meta.image identified by its index in the list.
- "rel:$uuid": instruction_addr is relative to the debug_meta.image identified by its debug_id.
  If one of the "rel:XXX" variants is given together with function_id, the instruction_addr is relative to the uniquely identified function in the references debug_meta.image.
colno (optional): number | null
Column number within the source file, starting at 1.
context_line (optional): null | string
Source code of the current line (lineno).
filename (optional): null | string
The source file name (basename only).
function (optional): null | string
Name of the frame's function. This might include the name of a class.
This function name may be shortened or demangled. If not, Sentry will demangle and shorten it for some platforms. The original function name will be stored in raw_function.
function_id (optional): null | string
(.NET) The function id / index that uniquely identifies a function inside a module.
This is the MetadataToken of a .NET MethodBase.
image_addr (optional): null | string
(C/C++/Native) Start address of the containing code module (image).
in_app (optional): boolean | null
Override whether this frame should be considered part of application code, or part of libraries/frameworks/dependencies.
Setting this attribute to false causes the frame to be hidden/collapsed by default and mostly ignored during issue grouping.
instruction_addr (optional): null | string
(C/C++/Native) An optional instruction address for symbolication.
This should be a string with a hexadecimal number that includes a 0x prefix. If this is set and a known image is defined in the [Debug Meta Interface]({%- link _documentation/development/sdk-dev/event-payloads/debugmeta.md -%}), then symbolication can take place.
lineno (optional): number | null
Line number within the source file, starting at 1.
module (optional): null | string
Name of the module the frame is contained in.
Note that this might also include a class name if that is something the language natively considers to be part of the stack (for instance in Java).
package (optional): null | string
Name of the package that contains the frame.
For instance this can be a dylib for native languages, the name of the jar or .NET assembly.
platform (optional): null | string
Which platform this frame is from.
This can override the platform for a single frame. Otherwise, the platform of the event is assumed. This can be used for multi-platform stack traces, such as in React Native.
post_context (optional): Array<null | string> | null
Source code of the lines after lineno.
pre_context (optional): Array<null | string> | null
Source code leading up to lineno.
raw_function (optional): null | string
A raw (but potentially truncated) function value.
The original function name, if the function name is shortened or demangled. Sentry shows the raw function when clicking on the shortened one in the UI.
If this has the same value as function it's best to be omitted. This exists because on many platforms the function itself contains additional information like overload specifies or a lot of generics which can make it exceed the maximum limit we provide for the field. In those cases then we cannot reliably trim down the function any more at a later point because the more valuable information has been removed.
The logic to be applied is that an intelligently trimmed function name should be stored in function and the value before trimming is stored in this field instead. However also this field will be capped at 256 characters at the moment which often means that not the entire original value can be stored.
stack_start (optional): boolean | null
Marks this frame as the bottom of a chained stack trace.
Stack traces from asynchronous code consist of several sub traces that are chained together into one large list. This flag indicates the root function of a chained stack trace. Depending on the runtime and thread, this is either the main function or a thread base stub.
This field should only be specified when true.
symbol (optional): null | string
Potentially mangled name of the symbol as it appears in an executable.
This is different from a function name by generally being the mangled name that appears natively in the binary. This is relevant for languages like Swift, C++ or Rust.
symbol_addr (optional): null | string
(C/C++/Native) Start address of the frame's function.
We use the instruction address for symbolication, but this can be used to calculate an instruction offset automatically.
vars (optional): { [key: string]: any } | null
Mapping of local variables and expression names that were available in this frame.

LogEntry

A log entry message.

A log message is similar to the message attribute on the event itself but can additionally hold optional parameters.

Copied
{
  "message": {
    "message": "My raw message with interpreted strings like %s",
    "params": ["this"]
  }
}

Properties:

formatted (optional): null | string
The formatted message. If message and params are given, Sentry will attempt to backfill formatted if empty.
It must not exceed 8192 characters. Longer messages will be truncated.
message (optional): null | string
The log message with parameter placeholders.
This attribute is primarily used for grouping related events together into issues. Therefore this really should just be a string template, i.e. Sending %d requests instead of Sending 9999 requests. The latter is much better at home in formatted.
It must not exceed 8192 characters. Longer messages will be truncated.
params (optional): any
Parameters to be interpolated into the log message. This can be an array of positional parameters as well as a mapping of named arguments to their values.

Request

Http request information.

The Request interface contains information on a HTTP request related to the event. In client SDKs, this can be an outgoing request, or the request that rendered the current web page. On server SDKs, this could be the incoming web request that is being handled.

The data variable should only contain the request body (not the query string). It can either be a dictionary (for standard HTTP requests) or a raw request body.

Ordered Maps

In the Request interface, several attributes can either be declared as string, object, or list of tuples. Sentry attempts to parse structured information from the string representation in such cases.

Sometimes, keys can be declared multiple times, or the order of elements matters. In such cases, use the tuple representation over a plain object.

Example of request headers as object:

Copied
{
  "content-type": "application/json",
  "accept": "application/json, application/xml"
}

Example of the same headers as list of tuples:

Copied
[
  ["content-type", "application/json"],
  ["accept", "application/json"],
  ["accept", "application/xml"]
]

Example of a fully populated request object:

Copied
{
  "request": {
    "method": "POST",
    "url": "http://absolute.uri/foo",
    "query_string": "query=foobar&page=2",
    "data": {
      "foo": "bar"
    },
    "cookies": "PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; _gat=1;",
    "headers": {
      "content-type": "text/html"
    },
    "env": {
      "REMOTE_ADDR": "192.168.0.1"
    }
  }
}

Properties:

body_size (optional): number | null
HTTP request body size.
cookies (optional): null | (Array<Array<(null | string)> | null> | { [key: string]: null | string })
The cookie values.
Can be given unparsed as string, as dictionary, or as a list of tuples.
data (optional): any
Request data in any format that makes sense.
SDKs should discard large and binary bodies by default. Can be given as string or structural data of any format.
env (optional): { [key: string]: any } | null
Server environment data, such as CGI/WSGI.
A dictionary containing environment information passed from the server. This is where information such as CGI/WSGI/Rack keys go that are not HTTP headers.
Sentry will explicitly look for REMOTE_ADDR to extract an IP address.
fragment (optional): null | string
The fragment of the request URL.
headers (optional): null | (Array<Array<(null | string)> | null> | { [key: string]: null | string })
A dictionary of submitted headers.
If a header appears multiple times it, needs to be merged according to the HTTP standard for header merging. Header names are treated case-insensitively by Sentry.
inferred_content_type (optional): null | string
The inferred content type of the request payload.
method (optional): null | string
HTTP request method.
query_string (optional): null | (string | (Array<Array<(null | string)> | null> | { [key: string]: null | string }))
The query string component of the URL.
Can be given as unparsed string, dictionary, or list of tuples.
If the query string is not declared and part of the url, Sentry moves it to the query string.
url (optional): null | string
The URL of the request if available.
The query string can be declared either as part of the url, or separately in query_string.

ClientSDKInfo

The SDK Interface describes the Sentry SDK and its configuration used to capture and transmit an event.

Properties:

integrations (optional): Array<null | string> | null
List of integrations that are enabled in the SDK. Optional.
The list should have all enabled integrations, including default integrations. Default integrations are included because different SDK releases may contain different default integrations.
name: null | string
Unique SDK name. Required.
The name of the SDK. The format is entity.ecosystem[.flavor] where entity identifies the developer of the SDK, ecosystem refers to the programming language or platform where the SDK is to be used and the optional flavor is used to identify standalone SDKs that are part of a major ecosystem.
Official Sentry SDKs use the entity sentry, as in sentry.python or sentry.javascript.react-native. Please use a different entity for your own SDKs.
packages (optional): Array<ClientSDKPackage | null> | null
List of installed and loaded SDK packages. Optional.
A list of packages that were installed as part of this SDK or the activated integrations. Each package consists of a name in the format source:identifier and version. If the source is a Git repository, the source should be git, the identifier should be a checkout link and the version should be a Git reference (branch, tag or SHA).
version: null | string
The version of the SDK. Required.
It should have the Semantic Versioning format MAJOR.MINOR.PATCH, without any prefix (no v or anything else in front of the major version number).
Examples: 0.1.0, 1.0.0, 4.3.12

ClientSDKPackage

An installed and loaded package as part of the Sentry SDK.

Properties:

name (optional): null | string
Name of the package.
version (optional): null | string
Version of the package.

Threads

Properties:

values: Array<Thread | null>

Thread

A process thread of an event.

The Threads Interface specifies threads that were running at the time an event happened. These threads can also contain stack traces.

An event may contain one or more threads in an attribute named threads.

The following example illustrates the threads part of the event payload and omits other attributes for simplicity.

Copied
{
  "threads": {
    "values": [
      {
        "id": "0",
        "name": "main",
        "crashed": true,
        "stacktrace": {}
      }
    ]
  }
}

Properties:

crashed (optional): boolean | null
A flag indicating whether the thread crashed. Defaults to false.
current (optional): boolean | null
A flag indicating whether the thread was in the foreground. Defaults to false.
id (optional): null | (number | string)
The ID of the thread. Typically a number or numeric string.
Needs to be unique among the threads. An exception can set the thread_id attribute to cross-reference this thread.
main (optional): boolean | null
A flag indicating whether the thread was responsible for rendering the user interface.
name (optional): null | string
Display name of this thread.
stacktrace (optional): Stacktrace | null
Stack trace containing frames of this exception.
The thread that crashed with an exception should not have a stack trace, but instead, the thread_id attribute should be set on the exception and Sentry will connect the two.

TransactionInfo

Additional information about the name of the transaction.

Properties:

changes (optional): Array<TransactionNameChange | null> | null
A list of changes prior to the final transaction name.
This list must be empty if the transaction name is set at the beginning of the transaction and never changed. There is no placeholder entry for the initial transaction name.
original (optional): null | string
The unmodified transaction name as obtained by the source.
This value will only be set if the transaction name was modified during event processing.
propagations (optional): number | null
The total number of propagations during the transaction.
source (optional): TransactionSource | null
Describes 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.

TransactionNameChange

Properties:

propagations (optional): number | null
The number of propagations from the start of the transaction to this change.
source (optional): TransactionSource | null
Describes how the previous transaction name was determined.
timestamp (optional): null | (number | string)
Timestamp when the transaction name was changed.
This adheres to the event timestamp specification.

TransactionSource

Describes how the name of the transaction was determined.

Variants:

"component"
"custom"
"route"
"task"
"url"
"unknown"
"view"

EventType

The type of an event.

The event type determines how Sentry handles the event and has an impact on processing, rate limiting, and quotas. There are three fundamental classes of event types:

Error monitoring events (default, error): Processed and grouped into unique issues based on their exception stack traces and error messages. - Security events (csp, hpkp, expectct, expectstaple): Derived from Browser security violation reports and grouped into unique issues based on the endpoint and violation. SDKs do not send such events. - Transaction events (transaction): Contain operation spans and collected into traces for performance monitoring.

Variants:

"csp"
"default"
"error"
"expectct"
"expectstaple"
"hpkp"
"transaction"

User

Information about the user who triggered an event.

Copied
{
  "user": {
    "id": "unique_id",
    "username": "my_user",
    "email": "foo@example.com",
    "ip_address": "127.0.0.1",
    "subscription": "basic"
  }
}

Properties:

data (optional): { [key: string]: any } | null
Additional arbitrary fields, as stored in the database (and sometimes as sent by clients). All data from self.other should end up here after store normalization.
email (optional): null | string
Email address of the user.
geo (optional): Geo | null
Approximate geographical location of the end user or device.
id (optional): null | string
Unique identifier of the user.
ip_address (optional): null | string
Remote IP address of the user. Defaults to "{{auto}}".
name (optional): null | string
Human readable name of the user.
segment (optional): null | string
The user segment, for apps that divide users in user segments.
username (optional): null | string
Username of the user.

Geo

Geographical location of the end user or device.

Properties:

city (optional): null | string
Human readable city name.
country_code (optional): null | string
Two-letter country code (ISO 3166-1 alpha-2).
region (optional): null | string
Human readable region name or code.

You can edit this page on GitHub.

Docs

General

Development

Application

Self-Hosted

Frontend

Backend

Services

SDK Development

Integrations

Resources

Meta Documentation

Event Type Definitions

Event

Example

Breadcrumbs

Breadcrumb

Level

DeviceContext

OSContext

RuntimeContext

AppContext

BrowserContext

GPUContext

TraceContext

SpanStatus

ResponseContext

OtelContext

DebugMeta

AppleDebugImage

NativeDebugImage

ProguardDebugImage

SystemSDKInfo

EventProcessingError

Exception

ValueClass

Mechanism

MechanismMeta

CError

MachException

NSError

POSIXSignal

Stacktrace

Frame

LogEntry

Request

Ordered Maps

ClientSDKInfo

ClientSDKPackage

Threads

Thread

TransactionInfo

TransactionNameChange

TransactionSource

EventType

User

Geo