WASM 可观测性：指标、追踪、日志与运行时监控

常规服务：stdout 直接可读、eBPF 抓 syscall、/proc 看内存、进程级堆栈
WASM：无 stdout（需宿主注入 log）、无 syscall 可抓、只能看宿主进程、
      trap 堆栈需开 backtrace 才有符号、实例崩溃需显式上报

指标（Metrics）：宿主采集调用次数、延迟、燃料、内存水位、trap 次数；
                模块通过导入的 emit_metric 上报业务计数器
追踪（Traces）：宿主生成 span（调用边界、能力调用边界）；
                模块通过导入函数读写 trace context
日志（Logs）：模块调用导入的 log(level, ptr, len)；
              宿主负责加时间戳、插件 ID、trace ID 后写出

// Wasmtime：调用前后采集，得到延迟与结果分布
let t0 = Instant::now();
let result = instance.get_typed_func::<(i32, i32), i32>(&mut store, "handle")?
    .call(&mut store, (a, b));
let dt = t0.elapsed();

metrics.histogram("wasm_call_duration_seconds", dt, &[("plugin", pid)]);
metrics.counter("wasm_call_total", 1, &[("plugin", pid),
    ("status", if result.is_ok() { "ok" } else { "trap" })]);

// 每次调用后读取剩余燃料，差值就是本次消耗
let before = store.get_fuel()?;
let _ = call(&mut store);
let used = before - store.get_fuel()?;
metrics.histogram("wasm_fuel_used", used as f64, &[("plugin", pid)]);

// 线性内存当前页数 → 字节数
let mem = instance.get_memory(&mut store, "memory").unwrap();
let bytes = mem.data_size(&store) as u64;
metrics.gauge("wasm_memory_bytes", bytes as f64, &[("plugin", pid)]);

必备指标清单（按插件实例维度）：wasm_call_total（按 status 分）、
wasm_call_duration_seconds（延迟直方图）、wasm_fuel_used（燃料直方图）、
wasm_memory_bytes（内存占用）、wasm_trap_total（按原因分）、
wasm_instantiate_seconds（实例化耗时）。

// 模块侧：通过导入的 emit_metric 上报业务计数
#[link(wasm_import_module = "host")]
extern "C" { fn emit_metric(name_ptr: *const u8, name_len: usize, value: f64); }

pub fn count_cache_hit() {
    let name = b"cache_hit_total";
    unsafe { emit_metric(name.as_ptr(), name.len(), 1.0) };
}

// 宿主侧实现：校验指标名白名单，避免插件刷爆指标系统
fn emit_metric(name: &[u8], value: f64) {
    let name = std::str::from_utf8(name).unwrap_or("");
    if !ALLOWED_METRICS.contains(name) { return; }   // 白名单
    registry.counter(name).inc_by(value);
}

自动插桩两条路线：编译期插桩（wasm-opt 的 --instrument-locals /
--instrument-memory，在函数入口出口插计数）与宿主侧 wrapping（把每个导出
函数包一层计时计数，零侵入、不依赖插件配合，是生产首选）。

# 检查插桩后的体积与指令增长
wasm-opt --instrument-memory --instrument-locals in.wasm -o out.wasm
wasm-tools dump out.wasm | head -20

WASM 追踪的核心问题：模块内没有网络栈，无法自动传播 traceparent。
解决方案：宿主在调用前把 context 注入模块，模块透传即可 ——
宿主从上游请求头取 traceparent → 调用前用 set_trace_context(ptr, len) 注入
→ 模块发起下游能力调用时宿主自动附加 context → 模块可选地创建子 span。

// 宿主：为每次插件调用创建一个 span
let span = tracer.start_span_with_parent("wasm.handle", &incoming_ctx);
span.set_attribute("plugin.id", plugin_id);
let _guard = span.enter();
let r = call_plugin(&mut store, &bytes);
span.record_result(&r);

建议的 span 边界：一次插件调用 → wasm.handle；一次宿主能力调用（http）→
wasm.cap.http 子 span；插件内部业务阶段由插件显式创建（可选）。
禁忌：不要为每次内存读写创建 span（量级爆炸），不要在 span 属性里放插件
传入的任意字符串（基数爆炸）。

// 模块侧：调用导入的 log(level, ptr, len)
#[link(wasm_import_module = "host")]
extern "C" { fn log(level: u32, ptr: *const u8, len: usize); }

pub fn warn(msg: &str) {
    unsafe { log(2, msg.as_ptr(), msg.len()) };
}

// 宿主侧：补齐上下文字段后写出结构化日志
fn host_log(store: &mut Store<HostState>, level: u32, msg: &[u8]) {
    let st = store.data();
    tracing::event!(target: "wasm", Level::INFO,
        plugin_id = %st.plugin_id, trace_id = %st.trace_id,
        level = level, message = %String::from_utf8_lossy(msg));
}

宿主必须补齐：ts（宿主时钟，模块时钟不可信）、plugin_id、plugin_version、
instance_id（热加载后变化）、trace_id/span_id、level；
模块自己只提供 message（纯文本或 JSON 字符串）。

# 方案一：把 wasm 转成原生可剖析的形式（wasmtime 的 profiling）
wasmtime run --profile=perf app.wasm

# 方案二：用 wasm-tools 保留 name 段 + 采样栈
wasm-opt --keep-section=name app.wasm -o app.prof.wasm

// 方案三：宿主侧粗粒度剖析（记录每个导出函数的调用耗时分布）
profiler.record("handle", dt);
profiler.record("transform", dt2);

生成火焰图三步：采样（perf record / wasmtime profiling 收集栈样本）→
符号化（用 name 段或 DWARF 把地址映射回函数名）→ 渲染（flamegraph.pl）。
关键前提：必须有 name 段或 DWARF，否则火焰图全是 func[1234]。

典型发现：某字符串处理函数占 40% CPU → 改用批量 API；某跨边界调用被调用
200 万次 → 合并为一次批量调用；某分配路径触发大量内存增长 → 预分配 + 对象池。

// 宿主侧周期采样，超过阈值告警
let bytes = mem.data_size(&store);
let peak = state.peak_memory.max(bytes);
if bytes > state.limit * 8 / 10 {
    tracing::warn!(plugin_id = %pid, used = bytes, "wasm memory above 80%");
}

内存监控三个关键值：current（当前线性内存字节数）、peak（历史峰值）、
limit（配置的 MAXIMUM_MEMORY）。current / limit 持续大于 0.8 → 上调限额或修插件。

内存单调上涨不回落 → 泄漏（分配未释放）；内存锯齿状剧烈波动 → 频繁增长收缩，
应预分配；燃料消耗突然翻倍 → 输入规模变化或算法退化；实例化耗时突增 →
模块变大或 AOT 缓存未命中。

推荐的四条基础告警：插件错误率 > 1% 持续 5 分钟、P99 延迟 > 基线 3 倍持续
10 分钟、trap 次数 5 分钟内 > 10 次、内存水位 > 80% 持续 5 分钟。
每条告警都要带 plugin_id 与 plugin_version，便于快速定位到具体版本。

// 开启详细 backtrace，让 trap 堆栈可读
config.wasm_backtrace_details(WasmBacktraceDetails::Enable);

// trap 分类统计，区分「插件 bug」与「配额耗尽」
match err.downcast_ref::<Trap>() {
    Some(Trap::OutOfFuel)      => metrics.inc("trap_fuel", ...),
    Some(Trap::MemoryOutOfBounds) => metrics.inc("trap_oob", ...),
    Some(Trap::UnreachableCodeReached) => metrics.inc("trap_unreachable", ...),
    _ => metrics.inc("trap_other", ...),
}

trap 原因与责任归属：OutOfFuel → 配额问题，调额度或优化插件；
MemoryOutOfBounds → 插件越界 bug，插件侧修；UnreachableCode → 通常是
panic/abort，看插件堆栈；调用超时 → 可能是死循环，需熔断。

多租户观测的三个要求：
  1. 租户只能看到自己的数据（查询侧隔离）
  2. 一个租户的指标基数不能拖垮全局（写入侧限流）
  3. 成本可归因（按租户统计采集量）

实现手段：
  所有指标/日志/span 都带 tenant_id 标签
  每租户设置指标基数上限与日志速率上限
  超出上限时降采样而不是丢弃全部

控制指标基数的手段：
  禁止把请求参数放进标签（只允许枚举型标签）
  高基数维度（user_id、request_id）只进日志与追踪，不进指标
  日志按租户限速，超限后只保留 warn 以上级别
  追踪按比例采样（1% ~ 10%），错误全采

WASM 宿主 → (指标聚合) → Prometheus / OTLP
          → (日志)     → stdout JSON → 采集器 → 日志后端
          → (追踪)     → OTLP exporter → 追踪后端

管线上的三个关键点：
  1. 导出必须是异步的（批量 + 后台线程），不能阻塞调用路径
  2. 背压时降采样，绝不反压到业务调用
  3. 每个插件实例的观测开销单独计量，纳入插件配额

[ ] 六项基础指标按 plugin_id 维度采集
[ ] 燃料与内存水位每次调用后采样
[ ] 日志由宿主补齐 ts/plugin_id/version/trace_id
[ ] span 边界划在调用与能力调用两级，属性低基数
[ ] 保留 name 段，trap 堆栈可符号化
[ ] 四条基础告警就绪，trap 按原因分类
[ ] 多租户标签齐全，写入侧有基数与速率上限
[ ] 导出异步化，观测开销纳入插件配额