Struct NativeDebugImage

pub struct NativeDebugImage {
    pub code_id: Annotated<CodeId>,
    pub code_file: Annotated<NativeImagePath>,
    pub debug_id: Annotated<DebugId>,
    pub debug_file: Annotated<NativeImagePath>,
    pub debug_checksum: Annotated<String>,
    pub arch: Annotated<String>,
    pub image_addr: Annotated<Addr>,
    pub image_size: Annotated<u64>,
    pub image_vmaddr: Annotated<Addr>,
    pub other: Object<Value>,
}

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

Fields

code_id: Annotated<CodeId>

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.

code_file: Annotated<NativeImagePath>

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.

debug_id: Annotated<DebugId>

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.

debug_file: Annotated<NativeImagePath>

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_checksum: Annotated<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

arch: Annotated<String>

CPU architecture target.

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

image_addr: Annotated<Addr>

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: Annotated<u64>

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: Annotated<Addr>

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.

other: Object<Value>

Additional arbitrary fields for forwards compatibility.

Trait Implementations

impl Clone for NativeDebugImage

fn clone(&self) -> NativeDebugImage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NativeDebugImage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NativeDebugImage

fn default() -> NativeDebugImage

Returns the “default value” for a type.

impl Empty for NativeDebugImage

fn is_empty(&self) -> bool

Returns whether this value is empty.

fn is_deep_empty(&self) -> bool

Returns whether this value is empty or all of its descendants are empty.

impl FromValue for NativeDebugImage

fn from_value(__value: Annotated<Value>) -> Annotated<Self>

Creates a meta structure from an annotated boxed value.

impl IntoValue for NativeDebugImage

fn into_value(self) -> Value

Boxes the meta structure back into a value.

fn serialize_payload<S>( &self, __serializer: S, __behavior: SkipSerialization, ) -> Result<S::Ok, S::Error>

where Self: Sized, S: Serializer,

Efficiently serializes the payload directly.

fn extract_child_meta(&self) -> MetaMap

where Self: Sized,

Extracts children meta map out of a value.

fn extract_meta_tree(value: &Annotated<Self>) -> MetaTree

where Self: Sized,

Extracts the meta tree out of annotated value.

impl PartialEq for NativeDebugImage

fn eq(&self, other: &NativeDebugImage) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ProcessValue for NativeDebugImage

fn value_type(&self) -> EnumSet<ValueType>

Returns the type of the value.

fn process_value<P>( &mut self, __meta: &mut Meta, __processor: &mut P, __state: &ProcessingState<'_>, ) -> ProcessingResult

where P: Processor,

Executes a processor on this value.

fn process_child_values<P>( &mut self, __processor: &mut P, __state: &ProcessingState<'_>, ) -> ProcessingResult

where P: Processor,

Recurses into children of this value.

impl StructuralPartialEq for NativeDebugImage