--- title: "Debug Meta Interface" url: https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta/ --- # Debug Meta Interface The debug meta interface carries debug information for processing errors and crash reports. Sentry amends the information in this interface. ## [Attributes](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#attributes) * `sdk_info` An object describing the system SDK: `sdk_name`, `version_major`,`version_minor`, and `version_patchlevel`. This helps Sentry locate iOSsystem symbols, and is not required for other SDKs. ```json { "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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/stacktrace.md) 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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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 virtualaddress space of the process. Should be a string in hex representationprefixed with `"0x"`. * `image_size` The size of the image in virtual memory. If missing, Sentry will assume thatthe image spans up to the image with the next highest address, which might lead to invalid stack traces. * `debug_id` **Required**. Identifier of the dynamic library or executable. It is the valueof the `LC_UUID` load command in the Mach header, formatted as UUID. * `debug_file` *Optional*: Name or absolute path to the dSYM file containing debuginformation for this image. This value might be required to retrieve debugfiles from certain symbol servers. * `code_id` *Optional*. Identifier of the dynamic library or executable. It is the valueof the `LC_UUID` load command in the Mach header, formatted as UUID. Can beempty for Mach images, as it is equivalent to the debug identifier. * `code_file` *Optional*. The absolute path to the dynamic library or executable. This helpsto locate the file if it is missing on Sentry. * `image_vmaddr` *Optional*: Preferred load address of the image in virtual memory, as declaredin the headers of the image. When loading an image, the operating system maystill 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 bySentry. Example: ```json { "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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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 virtualaddress space of the process. Should be a string in hex representationprefixed with `"0x"`. * `image_size` **Required**. The size of the image in virtual memory. If missing, Sentry willassume that the image spans up to the next image, which might lead to invalidstack traces. * `debug_id` **Required**. Debug identifier of the dynamic library or executable. If a codeidentifier is available, the debug identifier is the *little-endian UUID*representation of the first 16-bytes of that identifier. Spaces are insertedfor readability, note the byte order of the first fields: ```bash 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 debuginformation for this image. This value might be required to retrieve debugfiles from certain symbol servers. * `code_id` *Optional*. Identifier of the dynamic library or executable. If the programwas compiled with a relatively recent compiler, this should be the hexrepresentation of the `NT_GNU_BUILD_ID` program header (type `PT_NOTE`), orthe 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 helpsto locate the file if it is missing on Sentry. * `image_vmaddr` *Optional*: Preferred load address of the image in virtual memory, as declaredin the headers of the image. When loading an image, the operating system maystill 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` *Optional*: Architecture of the module. If missing, this will be backfilled bySentry. Example: ```json { "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)](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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 virtualaddress space of the process. Should be a string in hex representationprefixed 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 leadto invalid stack traces. * `debug_id` **Required**. `signature` and `age` of the PDB file. Both values can be readfrom the CodeView PDB70 debug information header in the PE. The value shouldbe represented as *little-endian UUID*, with the age appended at the end. Notethat the byte order of the UUID fields must be swapped (spaces inserted forreadability): ```bash 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 thisimage. This value is often required to retrieve debug files from specificsymbol 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 optionalheader formatted together into a hex string using `%08x%X` (note that thesecond value is not padded): ```bash 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 locatethe file if it is missing on Sentry. The code file should be provided to allowserver-side stack walking of binary crash reports, such as Minidumps. * `image_vmaddr` *Optional*: Preferred load address of the image in virtual memory, as declaredin the headers of the image. When loading an image, the operating system maystill 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 bySentry. Example: ```json { "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](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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 valueof the `build_id` custom section and must be formatted as UUID truncated to theleading 16 bytes. * `debug_file` *Optional*. Name or absolute URL to the WASM file containing debuginformation for this image. This value might be required to retrieve debugfiles from certain symbol servers. This should correspond to the externalizedURL 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 casethe section contains a UUID (16 bytes). * `code_file` **Required**. The absolute URL to the wasm file. This helpsto locate the file if it is missing on Sentry. Example: ```json { "type": "wasm", "debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a", "debug_file": "sample.wasm" } ``` ### [Proguard Images](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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. Attributes: * `type` **Required**. Type of the debug image. Must be `"proguard"`. * `uuid` **Required**. The unique identifier assigned by the Java SDK. Example: ```json { "type": "proguard", "uuid": "395835f4-03e0-4436-80d3-136f0749a893" } ``` ### [Source Map Images](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#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 sourcefile. ```json { "type": "sourcemap", "code_file": "https://example.com/static/js/main.js", "debug_id": "395835f4-03e0-4436-80d3-136f0749a893" } ``` ## [Examples](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/debugmeta.md#examples) See examples for types of debug images above. ```json { "debug_meta": { "images": [], "sdk_info": { "sdk_name": "iOS", "version_major": 10, "version_minor": 3, "version_patchlevel": 0 } } } ```