Debug Meta Interface

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

sdk_info: An object describing the system SDK: sdk_name, version_major,
version_minor, and version_patchlevel. This helps Sentry locate iOS
system symbols, and is not required for other SDKs.

Copied

{
  "sdk_name": "iOS",
  "version_major": 10,
  "version_minor": 3,
  "version_patchlevel": 0
}

images: A list of dynamic libraries loaded into the process (see below).

The list of debug images contains all dynamic libraries loaded into the process and their memory addresses. Instruction addresses in the Stack Trace are mapped into the list of debug images in order to retrieve debug files for symbolication.

There are three kinds of debug images:

Native debug images with types macho, elf, and pe
Android debug images with type proguard
JavaScript source map debug images with type sourcemap

Mach-O images are used on Apple platforms. Their structure is identical to other native images.

Attributes:

type: Required. Type of the debug image. Must be "macho".
image_addr: 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: 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.
debug_id: Required. Identifier of the dynamic library or executable. It is the value
of the LC_UUID load command in the Mach header, formatted as UUID.
debug_file: Optional: 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.
code_id: Optional. 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.
code_file: Optional. The absolute path to the dynamic library or executable. This helps
to locate the file if it is missing on Sentry.
image_vmaddr: Optional: 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.

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.

arch: Optional: Architecture of the module. If missing, this will be backfilled by
Sentry.

Example:

Copied

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

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

Attributes:

type: Required. Type of the debug image. Must be "elf".
image_addr: 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: 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.
debug_id: Required. 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).

debug_file: Optional: 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.
code_id: Optional. Identifier of the dynamic library or executable. 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.

code_file: Optional. The absolute path to the dynamic library or executable. This helps
to locate the file if it is missing on Sentry.
image_vmaddr: Optional: 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.

Relative addresses used in addr2line are usually in the preferred address space, and not relative address space.

arch: Optional: Architecture of the module. If missing, this will be backfilled by
Sentry.

Example:

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

PE images are used on Windows platforms and are accompanied by PDB files for debugging. Their structure is identical to other native images.

type: Required. Type of the debug image. Must be "pe".
image_addr: 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: Required. The actual 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.
debug_id: Required. 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

debug_file: Required: Name of the PDB file containing debug information for this
image. This value is often required to retrieve debug files from specific
symbol servers.
code_id: Optional. 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.

code_file: Optional. The absolute path to the DLL or executable. This helps to locate
the file if it is missing on Sentry. The code file should be provided to allow
server-side stack walking of binary crash reports, such as Minidumps.
image_vmaddr: Optional: 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.

arch: Optional: Architecture of the module. If missing, this will be backfilled by
Sentry.

Example:

Copied

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

WASM images are used on for WebAssembly. Their structure is identical to other native images.

Attributes:

type: Required. Type of the debug image. Must be "wasm".
debug_id: Required. Identifier of the dynamic library or executable. It is the value
of the build_id custom section and must be formatted as UUID truncated to the
leading 16 bytes.
debug_file: Optional. Name or absolute URL to the WASM file containing debug
information for this image. This value might be required to retrieve debug
files from certain symbol servers. This should correspond to the externalized
URL pulled from the external_debug_info custom section.
code_id: Optional. Identifier of the WASM file. It is the value of the
build_id custom section formatted as HEX string. It can be omitted in case
the section contains a UUID (16 bytes).
code_file: Required. The absolute URL to the wasm file. This helps
to locate the file if it is missing on Sentry.

Example:

Copied

{
  "type": "wasm",
  "debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a",
  "debug_file": "sample.wasm"
}

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.

uuid: Required. The unique identifier assigned by the Java SDK.

Example:

Copied

{
  "uuid": "395835f4-03e0-4436-80d3-136f0749a893"
}

Source Map images are used to provide information about which artifact (i.e. source map) should be used to resolve a particular JavaScript file to its original source. We use the abs_path property of a stack frame and the code_file field in the image to query for a source map file via the debug_id field.

Attributes:

type: Required. Type of the debug image. Must be "sourcemap".
code_file: Required. Path/Url of the file that should be mapped. Corresponds to the
abs_path property inside a stack frame.
debug_id: Required. Identifier of the file that will be used to resolve the source
file.

Copied

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

See examples for types of debug images above.

Copied

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

Breadcrumbs Interface

Lock Reason Interface

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