Upload WebAssembly Symbols
Overview
WebAssembly (WASM) runs as part of a browser application. It is not a separate Datadog application type. The Datadog Browser SDK collects WASM errors with the surrounding browser context, and Datadog Error Tracking can symbolicate their WASM stack frames with uploaded DWARF debug information.
A single error can contain both JavaScript and WASM frames. Upload JavaScript source maps for the JavaScript frames and WASM symbols for the WASM frames.
WebAssembly symbolication is in beta. The Browser SDK plugin and the datadog-ci wasm-symbols upload command are experimental and may change.
Prerequisites
Before uploading symbols, make sure you have:
- A browser application configured to collect WASM module metadata with RUM, Browser Logs, or both.
- A
.wasm symbol file with embedded DWARF debug sections and a build_id custom section. @datadog/datadog-ci version 5.23.0 or later.
Generate debug symbols
Configure your WASM toolchain to generate:
- Embedded DWARF sections such as
.debug_info and .debug_line. - A
build_id custom section. The build ID in the uploaded symbol file must match the build ID in the module loaded by the browser.
For example, with Emscripten:
emcc -g -Wl,--build-id <SOURCES> -o <OUTPUT>.js
This command produces <OUTPUT>.js, the JavaScript loader, and <OUTPUT>.wasm, the WebAssembly binary containing the embedded DWARF information and build_id custom section.
You can inspect the generated module with wasm-objdump:
wasm-objdump -h <OUTPUT>.wasm
wasm-objdump -j build_id -x <OUTPUT>.wasm
Keep the symbol file as a build artifact so you can upload it from your CI pipeline.
Upload your symbols
Install the Datadog CLI and configure your Datadog API key and site:
npm install --save-dev @datadog/datadog-ci
export DATADOG_API_KEY=<DATADOG_API_KEY>
export DATADOG_SITE=
Enable beta commands and upload either one .wasm file or a directory. When given a directory, the CLI searches it recursively for .wasm files:
DD_BETA_COMMANDS_ENABLED=1 datadog-ci wasm-symbols upload /path/to/build
The command skips files that do not contain both embedded DWARF information and a build_id custom section. Use --dry-run to validate symbol files without uploading them:
DD_BETA_COMMANDS_ENABLED=1 datadog-ci wasm-symbols upload /path/to/build --dry-run
By default, Datadog keeps the first symbol file uploaded for a build ID. Use --replace-existing when you intentionally need to replace it.
The uploader does not resolve an external_debug_info reference. A runtime module that contains only this reference is skipped. Upload a symbol file that contains embedded DWARF sections and the same build_id as the runtime module.
How symbols are matched
Datadog uses the module URL metadata to associate each WASM stack frame with a module, then matches the module to its uploaded symbols by build_id. Unlike JavaScript source maps, service and version are not part of the WASM symbol lookup.
You can view uploaded files on the RUM Debug Symbols page.
Further reading
Additional helpful documentation, links, and articles:
