WASM 调试与性能剖析：源码映射、断点调试与火焰图分析

WASM 二进制只有指令，没有源码行号/变量名：
  - 报错只给「函数索引 + 偏移」
  - 无法设源码断点、看变量
解决：把调试信息（DWARF）打进产物，把指令映射回源码

Rust/C++ 产物 → DWARF（Rust 原生支持）
AssemblyScript/生成代码 → SourceMap（前端栈还原）
浏览器 DevTools 两者都读

调试信息让 wasm 体积增长（数倍）：
  - 开发：保留调试信息（-g）
  - 发布：剥离（wasm-opt --strip-debug / wasm-strip）
  - 中间态：debug 版 + release 版双产物

1. 产物带调试信息编译（Rust: cargo build -g / 保留 debug）
2. DevTools Sources 面板打开 wasm 文件
3. 勾选「Enable DWARF support」/ 自动加载
4. 断点/单步/变量/调用栈全部可用

Sources 面板对 wasm：
  - 文件列表显示 .wasm（可点击查看指令）
  - 断点可设在「源码行」（有 DWARF 时）
  - 单步进入/跳过/退出
  - 变量面板读 Rust 变量（类型、字段）
  - 调用栈还原源码帧

1. 断点不生效 → 确认带 -g 且未 strip 调试信息
2. 变量显示 raw → 缺少类型信息（DWARF 未完整嵌入）
3. 混淆偏移 → 检查 sourcemap 是否加载
4. 性能影响 → 调试时 JIT 关闭（较慢但更可断）

# Cargo.toml 开发 profile
[profile.dev]
debug = 2                # 完整 DWARF
opt-level = 1            # 适度优化（保留可断点）

# release 也可带部分调试
[profile.release]
debug = 1                # 行号（体积小）

# 编译 wasm + 调试信息
cargo build --target wasm32-unknown-unknown
# wasm-pack 默认 dev 带 debug
wasm-pack build --dev

wasm 里 panic：
  - 默认只给「无法展开的栈」
  - 配 RUST_BACKTRACE=1 + panic=unwind 可展开
  - 带 DWARF 时 DevTools 显示 Rust 源码栈

浏览器场景：console 里 error 对象含 wasm 栈，
启用 sourcemap/DWARF 后还原为源码位置

debug_assert!(x >= 0, "负数输入: {x}");
unreachable!("不应走到这里");   // 比静默继续好

# Emscripten 调试构建
emcc main.cpp \
  -g4 \
  -s WASM=1 \
  -s ASSERTIONS=1 \
  -s DEMANGLE_SUPPORT=1 \
  -s SAFE_HEAP=1 \
  -o game.js

SAFE_HEAP：把每个内存访问转成带界检查的调用
  - 立即定位越界读写（OOB 在第一次出错处炸）
  - 代价：明显变慢 → 仅调试构建开

搭配：-s STACK_OVERFLOW_CHECK=1 检测栈溢出

# 调试版（慢，信息全）
emcc main.cpp -g4 -s SAFE_HEAP=1 -o debug/game.js
# 发布版（快，无调试）
emcc main.cpp -O3 -s ALLOW_MEMORY_GROWTH=1 -o dist/game.js

把日志从 wasm 送出去（宿主可看/可采）：
  - Rust：经 wasm-bindgen 调 console/log 导出函数
  - 或经 WASI fd_write 到 stdout/stderr（服务端）
  - Emscripten：printf → JS console（默认已接）

关键：日志通道与宿主 API 解耦，便于采集

// Rust → JS console
#[wasm_bindgen]
extern "C" {
    fn console_log(s: &str);
}
macro_rules! log { ($($t:tt)*) => { console_log(&format!($($t)*)) } }

// wasmtime 侧钩子：跟踪调用/导入/分配
let engine = Engine::default();
let mut store = Store::new(&engine, ());
store.add_fuel(u64::MAX)?;                    // 燃料计量（执行步数）
// fuel 耗尽可触发回调 → 定位死循环

1. 业务关键路径打点（进入/退出模块、状态变化）
2. 带 requestId/实例标识（多实例可区分）
3. 采样率控制：全量 vs 抽样（生产慎开）
4. 归一到日志平台（与 JS/后端日志统一查询）

# 结构校验（发现问题字节码）
wasm-tools validate module.wasm

# 转 WAT 文本（读指令）
wasm-tools print module.wasm > module.wat

# 查看段信息
wasm-tools dump module.wasm | head -50

# 分离调试信息
wasm-tools strip -d module.wasm -o stripped.wasm

# 用 wasmtime 直接跑模块 + 详细栈
wasmtime --dir=. --env KEY=val module.wasm arg1

# 计时执行
time wasmtime module.wasm

# 打开 debug（更多信息）
RUST_LOG=wasmtime::wasm=debug wasmtime module.wasm

崩溃信息「at 0x… in func 7, at offset 0x…」：
  1. wasm-tools print 查看 func 7 指令
  2. 按偏移定位具体指令
  3. 结合源码/行号（DWARF）还原位置

CPU 剖析两条路：
  1. 浏览器 Performance 面板（采样 wasm 函数）
  2. 服务端 profiling（wasmtime 的 perf / samply）

输出：火焰图（调用深度 + 耗时占比）

Performance 面板：
  - 录制交互 → 查看 Call Tree / Flame Chart
  - 带 DWARF 的 wasm 显示源码函数名（而非地址）
  - 定位：哪些 wasm 函数占主导

注意：采样的是 JIT 后代码，符号来自调试信息

# samply：macOS 采样 CPU，输出火焰图
samply record -- wasmtime module.wasm

# perf（Linux）：采到 wasm 符号需 DWARF 支持
perf record -F 1000 -- wasmtime module.wasm
perf report

wasm 线性内存是主要内存面：
  - 增长：memory.grow 触发（频繁 grow 是分配问题信号）
  - 峰值：DevTools Memory 面板 / 运行时统计
  - 泄漏：重复实例不释放 → 宿主层回收检查

1. Rust（dlmalloc/dlmalloc 或 wee_alloc 时）：
   - 自定义分配器可加计数（alloc/free 次数）
2. 宿主统计：Wasmtime 每实例内存上限 + 已用
3. 对象池：热路径预分配，避免每帧 alloc

1. 记录 memory.grow 时机 → 关联操作
2. 峰值跟踪：模拟长会话看是否持续增长
3. 实例泄漏：多实例创建/销毁后 RSS 是否回落
4. 缓冲复用：JS↔wasm 缓冲是否反复新建

线程产物注意：
  1. 需 COOP/COEP 头（浏览器跨源隔离）
  2. 调试看 worker 独立栈（DevTools Threads 面板）
  3. 竞态定位：Atomics 等待 + 共享内存读写点
  4. 死锁：查看各 worker 栈 + Atomics.wait 位置

Cloudflare Workers / Fastly + WASM：
  - 本地：wrangler dev / fastly compute serve（本地跑）
  - 日志：console 进工作台日志流
  - 远程：绑定日志/链路追踪（requestId 贯穿）
  - 冷启动：首请求慢排查初始化路径

推荐组合：
  - 本地复现：本地运行时（wasmtime/浏览器 dev 服务器）
  - 单元级别：Rust cargo test（逻辑正确性）
  - 集成级别：本地边缘模拟器 + 日志
  - 生产：结构化日志 + 采样剖析（先于问题）