Contexts Interface
The Contexts Interface provides additional context data. Typically, this is data
related to the current user and the environment. For example, the device or
application version. Its canonical name is contexts
.
The contexts
type can be used to define arbitrary contextual data on the
event. It accepts an object of key/value pairs. The key is the “alias” of the
context and can be freely chosen. However, as per policy, it should match the
type of the context unless there are two values for a type. You can omit type
if the key name is the type.
When adding additional data to the event data model contexts are a good fit when you have all the data available at a single point in time. Contexts are not well suited to data that is collected over time as the SDK interfaces for contexts don't afford merging of data.
Unknown data for the contexts is rendered as a key/value list.
For more details about sending additional data with your event, see the full documentation on Additional Data.
Device Context
Device context describes the device that caused the event. This is most appropriate for mobile applications.
The type
and default key is "device"
.
name
- Required. The name of the device. This is typically a hostname.
family
- Optional. The family of the device. This is usually the common part of model
names across generations. For instance,
iPhone
would be a reasonable family, so would beSamsung Galaxy
.
model
- Optional. The model name. This, for example, can be
Samsung Galaxy S3
.
model_id
- Optional. An internal hardware revision to identify the device exactly.
arch
- Optional. The CPU architecture.
battery_level
- Optional. If the device has a battery, this can be a floating point value defining the battery level (in the range 0-100).
orientation
- Optional. This can be a string
portrait
orlandscape
to define the orientation of a device.
manufacturer
- Optional. The manufacturer of the device.
brand
- Optional. The brand of the device.
screen_resolution
- Optional. The screen resolution. (e.g.: 800x600, 3040x1444).
screen_height_pixels
- Optional. The height of the screen.
screen_width_pixels
- Optional. The width of the screen.
screen_density
- Optional. A floating point denoting the screen density.
screen_dpi
- Optional. A decimal value reflecting the DPI (dots-per-inch) density.
online
- Optional. Whether the device was online or not.
charging
- Optional. Whether the device was charging or not.
low_memory
- Optional. Whether the device was low on memory.
simulator
- Optional. A flag indicating whether this device is a simulator or an actual device.
memory_size
- Optional. Total system memory available in bytes.
free_memory
- Optional. Free system memory in bytes.
usable_memory
- Optional. Memory usable for the app in bytes.
storage_size
- Optional. Total device storage in bytes.
free_storage
- Optional. Free device storage in bytes.
external_storage_size
- Optional. Total size of an attached external storage in bytes (for example, android SDK card).
external_free_storage
- Optional. Free size of an attached external storage in bytes (for example, android SDK card).
boot_time
- Optional. A formatted UTC timestamp when the system was booted. For example,
"2018-02-08T12:52:12Z"
.
timezone
- Optional. The timezone of the device. For example,
Europe/Vienna
.
language
- Optional. The language of the device. For example,
en-US
.
processor_count
- Optional. Number of "logical processors". For example,
8
.
cpu_description
- Optional. CPU description. For example,
Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz
.
processor_frequency
- Optional. 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.
device_type
- Optional. Kind of device the application is running on. For example,
Unknown, Handheld, Console, Desktop
.
battery_status
- Optional. Status of the device's battery. For example,
Unknown, Charging, Discharging, NotCharging, Full
.
device_unique_identifier
- Optional. Unique device identifier. This value might only be used if
sendDefaultPii
is enabled.
supports_vibration
- Optional. Is vibration available on the device?
supports_accelerometer
- Optional. Is accelerometer available on the device?
supports_gyroscope
- Optional. Is gyroscope available on the device?
supports_audio
- Optional. Is audio available on the device?
supports_location_service
- Optional. Is the device capable of reporting its location?
OS Context
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).
The type
and default key is "os"
.
name
- Recommended. The name of the operating system. It might be derived from
raw_description
. It is required ifraw_description
is not provided.
version
- Optional. The version of the operating system.
build
- Optional. The internal build revision of the operating system.
kernel_version
- Optional. An independent kernel version string. This is typically the entire
output of the
uname
syscall.
rooted
- Optional. A flag indicating whether the OS has been jailbroken or rooted.
theme
- Optional. Either
light
ordark
. Describes whether the OS runs in dark mode or not.
raw_description
- Optional. An unprocessed description string obtained by the operating
system. For some well-known runtimes, Sentry will attempt to parse
name
andversion
from this string, if they are not explicitly given.
Example
The OS Context for the 3 major OSs should look like this:
{
"windows": {
"type": "os",
"name": "Windows",
"version": "10.0.19041",
"build": "662",
},
"mac": {
"type": "os",
"name": "macOS",
"version": "11.1.0",
"build": "20C69",
"kernel_version": "20.2.0"
},
"linux": {
"type": "os",
"name": "Linux",
"version": "5.10.6",
"build": "arch1-1"
}
}
Runtime Context
Runtime context describes a runtime in more detail. Typically, this context is used multiple times if multiple runtimes are involved (for instance, if you have a JavaScript application running on top of JVM).
The type
and default key is "runtime"
.
name
- Recommended. The name of the runtime. It might be derived from
raw_description
. It is required ifraw_description
is not provided.
version
- Optional. The version identifier of the runtime.
raw_description
- Optional. An unprocessed description string obtained by the runtime. For
some well-known runtimes, Sentry will attempt to parse
name
andversion
from this string, if they are not explicitly given.
App Context
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.
The type
and default key is "app"
.
app_start_time
- Optional. Formatted UTC timestamp when the user started the application.
device_app_hash
- Optional. Application-specific device identifier.
build_type
- Optional. String identifying the kind of build. For example,
testflight
.
app_identifier
- Optional. Version-independent application identifier, often a dotted bundle ID.
app_name
- Optional. Human readable application name, as it appears on the platform.
app_version
- Optional. Human readable application version, as it appears on the platform.
app_build
- Optional. Internal build identifier, as it appears on the platform.
Browser Context
Browser context carries information about the browser or user agent for web-related errors. This can either be the browser this event occurred in or the user agent of a web request that triggered the event.
The type
and default key is "browser"
.
name
- Required. Display name of the browser application.
version
- Optional. Version string of the browser.
GPU Context
GPU context describes the GPU of the device.
name
- Required. The name of the graphics device.
version
- Optional. The Version of the graphics device.
id
- Optional. The PCI identifier of the graphics device.
vendor_id
- Optional. The PCI vendor identifier of the graphics device.
vendor_name
- Optional. The vendor name as reported by the graphics device.
memory_size
- Optional. The total GPU memory available in Megabytes.
api_type
- Optional. The device low-level API type.
Examples: "Apple Metal"
or "Direct3D11"
multi_threaded_rendering
- Optional. Whether the GPU has multi-threaded rendering or not.
npot_support
- Optional. The Non-Power-Of-Two-Support support.
max_texture_size
- Optional. Largest size of a texture that is supported by the graphics hardware. For example,
16384
.
graphics_shader_level
- Optional. 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)
.
supports_draw_call_instancing
- Optional. Is GPU draw call instancing supported?
supports_ray_tracing
- Optional. Is ray tracing available on the device?
supports_compute_shaders
- Optional. Are compute shaders available on the device?
supports_geometry_shaders
- Optional. Are geometry shaders available on the device?
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"
}
State Context
State context describes the state of the application (e.g.: Redux store object).
The type
and default key is "state"
.
state
- Required. Object with two keys: Optional
type
for naming the state library (e.g.: Redux, MobX, Vuex) and Requiredvalue
that holds the state object.
Example:
"state": {
"state": {
"type": "MobX",
"value": {
"flights": [],
"airports": [],
"showModal": false
}
},
}
Examples
The following example illustrates the contexts part of the event payload and omits other attributes for simplicity.
{
"contexts": {
"os": {
"name": "Windows"
},
"electron": {
"type": "runtime",
"name": "Electron",
"version": "4.0"
}
}
}
Culture Context
Culture Context describes certain properties of the culture in which the software is used.
The type
and default key is "culture"
.
calendar
- Optional. For example
GregorianCalendar
. Free form string.
display_name
- Optional. Human readable name of the culture. For example
English (United States)
locale
- Optional. The name identifier, usually following the RFC 4646. For example
en-US
orpt-BR
.
is_24_hour_format
- Optional. boolean, either
true
orfalse
.
timezone
- Optional. The timezone of the locale. For example,
Europe/Vienna
.