Native

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/instrumentation-native"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/5ca020f7-aae4-436e-8497-c6dc3e639042/social-card.svg?v=3e7ae33eec8b" alt="Native" width="600" height="315"></a>

<!-- status: ga language: native -->

Native (ELF, Mach-O, PE) error symbolication

Watchtower symbolicates native frames from debug files: upload them (POST /v1/projects/{prj}/artifacts, kind elf, macho or pdb) or let the worker fetch them from a symbol server (/v1/projects/{prj}/symbol-sources).

Frame contract

  • debug_id: the image's id (ELF build-id, Mach-O UUID, PDB GUID), as a UUID or 32 hex digits.

  • instruction_addr: preferably module-relative (the load base already subtracted).

  • If the SDK can only send absolute addresses, list the loaded images in contexts.debug_meta.images as {debug_id, image_addr, image_vmaddr}. The symbolicator rewrites each frame to addr - image_addr + image_vmaddr. Frames below their image base are left unchanged.

  • module: the image file name (app.dll). The Microsoft symbol server layout needs it to build the <name>.pdb path.

  • contexts.device.arch (arm64, x86_64) or a numeric cpu_type picks the slice of a universal (fat) Mach-O.

Symbol servers

Kinds: microsoft (<url>/<name>.pdb/<GUID><age>/<name>.pdb, uncompressed PDB only; CAB .pd_ is refused), debuginfod (<url>/buildid/<hex>/debuginfo) and custom (a mirror using the debuginfod layout). URLs must be https and public. Downloads are limited to 20 MB and 10 s, stored as artifacts named symsrv/<id>, and a miss is not retried for 7 days.

Limits: the PDB age is assumed to be 1, and debuginfod ids are the 16 bytes Watchtower keeps (a 20-byte GNU build-id is cut, so such files must be uploaded).

Compressed DWARF

.zdebug_* sections and ELF SHF_COMPRESSED sections (zlib) are read. zstd-compressed sections are rejected.

In-app frames of an event carry source_url (repository file at the release's newest commit, needs a repo link) and, when PUT /v1/projects/{prj}/editor-settings sets editor_path_prefix, editor_url (vscode://file/...) and editor_url_jetbrains.

Updated