Debug Meta Interface

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

Attributes

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.

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

images

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

Debug Images

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

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

OptionalName 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

OptionalPreferred 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

OptionalArchitecture of the module. If missing, this will be backfilled by Sentry.

Example:

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

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:

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

OptionalName 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

OptionalPreferred 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 addr2line are usually in the preferred address space, and not relative address space.

arch

OptionalArchitecture of the module. If missing, this will be backfilled by Sentry.

Example:

{
  "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 (PDBs)

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

signature: f1c3bcc0 2798 65fe 3058 404b2831d9e6
age:                                            1
debug_id:  c0bcc3f1-9827-fe65-3058-404b2831d9e6-1

debug_file

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

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

OptionalPreferred 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

OptionalArchitecture of the module. If missing, this will be backfilled by Sentry.

Example:

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

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:

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

Proguard Images

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:

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

Source Map Images

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.

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

Examples

See examples for types of debug images above.

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