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 | ProfileContext | ReplayContext | UserReportV2Context | ResponseContext | OtelContext | CloudResourceContext | NelContext | PerformanceScoreContext | { [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.
```
{ "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:
```
{
  "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.

{
    "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.
```
{
    "fingerprint": ["myrpc", "POST", "/foo.bar"]
}
```
level (optional): Level | null

Severity level of the event. Defaults to error.

Example:
```
{"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.
```
{ "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:
```
{ "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:
```
- **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:
```
{
  "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>

Breadcrumb

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.

{
  "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.
locale (optional): null | string

ISO 639-1 code of the locale the device is set to.
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_height_pixels (optional): number | null

Height of the screen in pixels.
screen_resolution (optional): null | string

Device screen resolution.

(e.g.: 800x600, 3040x1444)
screen_width_pixels (optional): number | null

Width of the screen in pixels.
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.
uuid (optional): null | string

UUID of the device.

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.
distribution (optional): LinuxDistribution | null

Meta-data for the Linux Distribution.
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.

LinuxDistribution

Metadata for the Linux Distribution.

Properties:

name (optional): null | string

An index-able name that is stable for each distribution.
pretty_name (optional): null | string

A full rendering of name + version + release name (not available in all distributions).
version (optional): null | string

The version of the distribution (missing in distributions with solely rolling release).

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.
view_names (optional): Array<null | string> | null

The names of the currently visible views.

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:

"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.
data (optional): SpanData | null

Data of the trace's root span.
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).
origin (optional): null | string

The origin of the trace indicates what created the trace (see [OriginType] docs).
parent_span_id (optional): null | string

The ID of the span enclosing this span.
sampled (optional): boolean | null

Track whether the trace connected to this event has been sampled entirely.

This flag only applies to events with [Error] type that have an associated dynamic sampling context.
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.

SpanData

Arbitrary additional data on a span.

Besides arbitrary user data, this type also contains SDK-provided fields used by the product (see https://develop.sentry.dev/sdk/performance/span-data-conventions/).

Properties:

ai.completion_tokens.used (optional): any

The output tokens used by an LLM call (the ones the LLM actually generated)
ai.input_messages (optional): any

The input messages to an AI model call
ai.model_id (optional): any

The Model ID of an AI pipeline, e.g., gpt-4
ai.pipeline.name (optional): any

The 'name' field of the ancestor span with op ai.pipeline.*
ai.prompt_tokens.used (optional): any

The input tokens used by an LLM call (usually cheaper than output tokens)
ai.responses (optional): any

The responses to an AI model call
ai.total_tokens.used (optional): any

The total tokens that were used by an LLM call
app_start_type (optional): any

Mobile app start variant.

Can be either "cold" or "warm".
browser.name (optional): null | string

The client's browser name.
cache.hit (optional): any

Whether cache was hit or miss on a read operation.
cache.item_size (optional): any

The size of the cache item.
cache.key (optional): any

The name of the cache key.
client.address (optional): null | string

The client's IP address.
code.filepath (optional): any

The source code file name that identifies the code unit as uniquely as possible.
code.function (optional): any

The method or function name, or equivalent.

Usually rightmost part of the code unit's name.
code.lineno (optional): any

The line number in code.filepath best representing the operation.
code.namespace (optional): any

The "namespace" within which code.function is defined.

Usually the qualified class or module name, such that code.namespace + some separator + code.function form a unique identifier for the code unit.
db.operation (optional): any

The name of the operation being executed.

E.g. the MongoDB command name such as findAndModify, or the SQL keyword. Based on OpenTelemetry's call level db attributes.
db.system (optional): any

An identifier for the database management system (DBMS) product being used.

See OpenTelemetry docs for a list of well-known identifiers.
frames.delay (optional): any
http.decoded_response_content_length (optional): any

The decoded body size of the response (in bytes).
http.request_method (optional): any

The HTTP method used.
http.response.status_code (optional): any

The status HTTP response.
http.response_content_length (optional): any

The encoded body size of the response (in bytes).
http.response_transfer_size (optional): any

The transfer size of the response (in bytes).
messaging.destination.name (optional): null | string
messaging.message.body.size (optional): any

Message Body Size
messaging.message.id (optional): null | string

Message ID
messaging.message.receive.latency (optional): any

Message Receive Latency
messaging.message.retry.count (optional): any

Message Retry Count
previousRoute (optional): Route | null

The previous route in the application

Set by React Native SDK.
resource.render_blocking_status (optional): any

The render blocking status of the resource.
route (optional): Route | null

The current route in the application.

Set by React Native SDK.
sentry.environment (optional): null | string

The sentry environment.
sentry.frames.frozen (optional): any

Frozen Frames
sentry.frames.slow (optional): any

Slow Frames
sentry.frames.total (optional): any

Total Frames
sentry.release (optional): null | string

The release version of the project.
sentry.replay.id (optional): any

Replay ID
sentry.sdk.name (optional): null | string

The sentry SDK (see [crate::protocol::ClientSdkInfo]).
sentry.sdk.version (optional): null | string

The sentry SDK version (see [crate::protocol::ClientSdkInfo]).
sentry.segment.name (optional): null | string

Name of the segment that this span belongs to (see segment_id).

This corresponds to the transaction name in the transaction-based model.

For INP spans, this is the route name where the interaction occurred.
server.address (optional): any

Name of the web server host.
thread.id (optional): null | (number | string)

ID of thread from where the span originated.
thread.name (optional): null | string

Label identifying a thread from where the span originated.
ui.component_name (optional): any

Name of the UI component (e.g. React).
url.full (optional): null | string

Absolute URL of a network resource.
url.scheme (optional): any

The URL scheme, e.g. "https".
user (optional): any

User Display
user_agent.original (optional): null | string

Value of the HTTP User-Agent header sent by the client.

Route

The route in the application, set by React Native SDK.

Properties:

name (optional): null | string

The name of the route.
params (optional): { [key: string]: any } | null

Parameters assigned to this route.

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"

ProfileContext

Profile context

Properties:

profile_id (optional): null | string

The profile ID.
profiler_id (optional): null | string

The profiler ID.

ReplayContext

Replay context.

The replay context contains the replay_id of the session replay if the event occurred during a replay. The replay_id is added onto the dynamic sampling context on the javascript SDK which propagates it through the trace. In relay, we take this value from the DSC and create a context which contains only the replay_id This context is never set on the client for events, only on relay.

Properties:

replay_id (optional): null | string

The replay ID.

UserReportV2Context

Feedback context.

This contexts contains user feedback specific attributes. We don't PII scrub contact_email as that is provided by the user. TODO(jferg): rename to FeedbackContext once old UserReport logic is deprecated.

Properties:

contact_email (optional): null | string

an email optionally provided by the user, which can be different from user.email
message (optional): null | string

The feedback message which contains what the user has to say.

ResponseContext

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

The data variable should only contain the response body. It can either be a dictionary (for standard HTTP responses) or a raw response body.

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.
data (optional): any

Response data in any format that makes sense.

SDKs should discard large and binary bodies by default. Can be given as a string or structural data of any format.
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 response payload.
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

CloudResourceContext

Cloud Resource Context.

This context describes the cloud resource the event originated from.

Example:

"cloud_resource": {
    "cloud.account.id": "499517922981",
    "cloud.provider": "aws",
    "cloud.platform": "aws_ec2",
    "cloud.region": "us-east-1",
    "cloud.vavailability_zone": "us-east-1e",
    "host.id": "i-07d3301208fe0a55a",
    "host.type": "t2.large"
}

Properties:

cloud.account.id (optional): null | string

The cloud account ID the resource is assigned to.
cloud.availability_zone (optional): null | string

The zone where the resource is running.
cloud.platform (optional): null | string

The cloud platform in use. The prefix of the service SHOULD match the one specified in cloud_provider.
cloud.provider (optional): null | string

Name of the cloud provider.
cloud.region (optional): null | string

The geographical region the resource is running.
host.id (optional): null | string

Unique host ID.
host.type (optional): null | string

Machine type of the host.

NelContext

Contains NEL report information.

Network Error Logging (NEL) is a browser feature that allows reporting of failed network requests from the client side. See the following resources for more information:

Properties:

elapsed_time (optional): number | null

The number of milliseconds between the start of the resource fetch and when it was aborted by the user agent.
error_type (optional): null | string

If request failed, the type of its network error. If request succeeded, "ok".
phase (optional): null | (PurpleNetworkReportPhases | FluffyNetworkReportPhases | TentacledNetworkReportPhases | string)

If request failed, the phase of its network error. If request succeeded, "application".
sampling_fraction (optional): number | null

The sampling rate.
server_ip (optional): null | string

Server IP where the requests was sent to.

PurpleNetworkReportPhases

Properties:

FluffyNetworkReportPhases

Properties:

TentacledNetworkReportPhases

Properties:

PerformanceScoreContext

Performance Score context.

The performance score context contains the version of the profile used to calculate the performance score.

Properties:

score_profile_version (optional): null | string

The performance score profile version.

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

{
  "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 | SourceMapDebugImage | JVMDebugImage | { [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:

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

{
  "type": "pe",
  "code_id": "57898e12145000",
  "code_file": "C:\\Windows\\System32\\dbghelp.dll",
  "debug_id": "9c2a902b-6fdf-40ad-8308-588a41d572a0-1",
  "debug_file": "dbghelp.pdb",
  "image_addr": "0x70850000",
  "image_size": "1331200",
  "image_vmaddr": "0x40000",
  "arch": "x86"
}

{
  "type": "macho",
  "debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a",
  "debug_file": "libDiagnosticMessagesClient.dylib",
  "code_file": "/usr/lib/libDiagnosticMessagesClient.dylib",
  "image_addr": "0x7fffe668e000",
  "image_size": 8192,
  "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):
```
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:
```
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):
```
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.

SourceMapDebugImage

A debug image pointing to a source map.

Examples:

{
  "type": "sourcemap",
  "code_file": "https://example.com/static/js/main.min.js",
  "debug_id": "395835f4-03e0-4436-80d3-136f0749a893"
}

Note: Stack frames and the correlating entries in the debug image here for code_file/abs_path are not PII stripped as they need to line up perfectly for source map processing.

Properties:

code_file: null | string

Path and name of the image file as URL. (required).

The absolute path to the minified JavaScript file. This helps to correlate the file to the stack trace.
debug_file (optional): null | string

Path and name of the associated source map.
debug_id: null | string

Unique debug identifier of the source map.

JVMDebugImage

A debug image consisting of source files for a JVM based language.

Examples:

{
  "type": "jvm",
  "debug_id": "395835f4-03e0-4436-80d3-136f0749a893"
}

Properties:

debug_id: null | string

Unique debug identifier of the bundle.

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:

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:

{
  "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.
exception_id (optional): number | null

An optional numeric value providing an ID for the exception relative to this specific event. It is referenced by the parent_id to reconstruct the logical tree of exceptions in an exception group.

This should contain an unsigned integer value starting with 0 for the last exception in the exception values list, then 1 for the previous exception, etc.
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.
is_exception_group (optional): boolean | null

An optional boolean value, set true when the exception is the platform-specific exception group type. Defaults to false.

For example, exceptions of type ExceptionGroup (Python), AggregateException (.NET), and AggregateError (JavaScript) should have "is_exception_group": true. Other exceptions can omit this field.
meta (optional): MechanismMeta | null

Operating system or runtime meta information.
parent_id (optional): number | null

An optional numeric value pointing at the exception_id that is the direct parent of this exception, used to reconstruct the logical tree of exceptions in an exception group.

The last exception in the exception values list should omit this field, because it is the root exception and thus has no parent.
source (optional): null | string

An optional string value describing the source of the exception.

For chained exceptions, this should contain the platform-specific name of the property or attribute (on the parent exception) that this exception was acquired from. In the case of an array, it should include the zero-based array index as well.
- Python Examples: "__context__", "__cause__", "exceptions[0]", "exceptions[1]"
- .NET Examples: "InnerException", "InnerExceptions[0]", "InnerExceptions[1]"
- JavaScript Examples: "cause", "errors[0]", "errors[1]"
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:

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

def main():
    foo()

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

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

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

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

{
  "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.
instruction_addr_adjustment (optional): InstructionAddrAdjustment | null

Optional. A flag that indicates if, and how, instruction_addr values need to be adjusted before they are symbolicated.
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.
lock (optional): LockReason | null

A possible lock (java monitor object) held by this frame.
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.

LockReason

Represents an instance of a held lock (java monitor object) in a thread.

Properties:

address (optional): null | string

Address of the java monitor object.
class_name (optional): null | string

Class name of the java monitor object.
package_name (optional): null | string

Package name of the java monitor object.
thread_id (optional): null | (number | string)

Thread ID that's holding the lock.
type: LockReasonType | null

Type of lock on the thread with available options being blocked, waiting, sleeping and locked.

LockReasonType

Possible lock types responsible for a thread's blocked state

Variants:

"blocked"
"locked"
"sleeping"
"waiting"

InstructionAddrAdjustment

Controls the mechanism by which the instruction_addr of a [Stacktrace] [Frame] is adjusted.

The adjustment tries to transform return addresses to call addresses for symbolication. Typically, this adjustment needs to be done for all frames but the first, as the first frame is usually taken directly from the cpu context of a hardware exception or a suspended thread and the stack trace is created from that.

When the stack walking implementation truncates frames from the top, "all" frames should be adjusted. In case the stack walking implementation already does the adjustment when producing stack frames, "none" should be used here.

Variants:

"all"
"all_but_first"
"auto"
"none"

LogEntry

A log entry message.

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

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

{
  "logentry": {
    "message": "My raw message with interpreted strings like {foo}",
    "params": {"foo": "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:

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

Example of the same headers as list of tuples:

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

Example of a fully populated request object:

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

api_target (optional): null | string

The API target/specification that made the request.

Values can be graphql, rest, etc.

The data field should contain the request and response bodies based on its target specification.

This information can be used for better data scrubbing and normalization.
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 a 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 URI.
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.
protocol (optional): null | string

HTTP protocol.
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:

features (optional): Array<null | string> | null

List of features that are enabled in the SDK. Optional.

A list of feature names identifying enabled SDK features. This list should contain all enabled SDK features. On some SDKs, enabling a feature in the options also adds an integration. We encourage tracking such features with either integrations or features but not both to reduce the payload size.
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.

{
  "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.
held_locks (optional): { [key: string]: LockReason | null } | null

Represents a collection of locks (java monitor objects) held by a thread.

A map of lock object addresses and their respective lock reason/details.
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.
state (optional): null | string

Thread state at the time of the crash.

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"
"sanitized"
"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"
"nel"
"transaction"
"userreportv2"

User

Information about the user who triggered an event.

{
  "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.
sentry_user (optional): null | string

The user string representation as handled in Sentry.

This field is computed by concatenating the name of specific fields of the User struct with their value. For example, if id is set, sentry_user will be equal to `"id:id-of-the-user".
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.
subdivision (optional): null | string

Human readable subdivision name.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support