用途：在每次变更中实现并验证 JoelClaw 可观测性，防止故障静默发生。可观测性被视为完成标准的一部分，而非可选打磨。
主要能力与规则：只使用规范事件契约，核心文件包括 packages/system-bus/src/observability/otel-event.ts、emit.ts、store.ts。Worker/Inngest 代码通过 emitOtelEvent 或 emitMeasuredOtelEvent 发射事件；网关代码通过 emitGatewayOtel 发射；内部摄取统一走 POST /observability/emit（packages/system-bus/src/serve.ts），不做临时写入。不得把 console.log 当作主要可观测性手段，结构化事件才是事实来源。高基数取值放入 metadata，而非 source、component、level、success 等 facet 字段。失败必须设置 success: false 并给出有意义的 error。需验证事件送达当前遥测配置要求的 sink，先检查镜像是否启用。在 Inngest 持久函数中，任何“只发射一次”的遥测必须放在 step.run(...) 内，避免恢复后重放重复。
事件约定：source 表示子系统（worker、gateway、webhook、memory、verification 等）；component 为稳定模块/服务名；action 为稳定点分动作；metadata 放请求 ID、部署 ID、函数 ID、会话 ID、载荷标识等；计时操作包含 duration_ms。采用 event-per-hop（宽事件）风格，每个主要边界/操作发一个上下文丰富的事件。
使用方式：先识别被变更的边界（Inngest 函数、网关通道、Webhook 路由、API 路由、后台任务、同步步骤），添加成功与失败信封；长任务用开始+完成，短任务用单个完成事件；在 metadata 中带上运营与业务上下文；保持严重级别有意义。完成前运行验证门禁，完整清单见 references/implementation-checklist.md。CLI 发射使用 --metadata 传 JSON 上下文，没有 --attributes 标志，例如 joelclaw otel emit "task.completed" --source system --component skills --success true --metadata '{"session":"NimbleBadger","task":"install wzrrd-publish skill"}'。
完成定义：变更路径已添加结构化 OTEL 事件；没有直接向 Typesense/Convex 写可观测性数据；scripts/otel-smoke.sh 冒烟探测通过；joelclaw otel list 与 joelclaw otel stats 显示预期行为；新失败模式可按 source、component、action 查询。
Inngest 重放与挂起排查：当步骤代码看似运行但运行保持 RUNNING/CANCELLED 并出现 Finalization 错误时，先查看运行轨迹 joelclaw run <run-id>，查找 errors.Finalization.stack 中的 Unable to reach SDK URL；用 joelclaw inngest status、joelclaw logs worker --lines 200、joelclaw logs errors --lines 200 确认是真实网络可达性问题还是 worker 侧阻塞。检查 OTEL 重放噪声，若本应只发射一次的动作在单个运行窗口出现数百次，应将其移入独立 step.run，可用 joelclaw otel search "manifest.archive.prereqs-passed" --hours 1 查询。Unable to reach SDK URL 是模糊症状，可能表示入口问题，也可能因函数处理器长时间阻塞本地 IO/依赖导致无法完成 finalization。
辅助脚本：./skills/o11y-logging/scripts/otel-smoke.sh verification o11y-skill probe.emit 可做快速端到端探测。关键文件还包括 packages/gateway/src/observability.ts、packages/system-bus/src/inngest/functions/check-system-health.ts、packages/cli/src/commands/otel.ts、apps/web/app/api/otel/route.ts。
限制：资料未提供收费、价格、平台支持范围等信息。