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

Properties:

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:

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:

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.

  • 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:

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:

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.