Cloudflare Computer可观测性实战：observe-recorder与Cloudflare集成三件套

Cloudflare Computer可观测性实战observe-recorder与Cloudflare集成三件套【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computerCloudflare Computer的可观测性Observability功能让你给 AI Agent 的迷你电脑装上仪表盘 。它由三个轻量组件组成WorkspaceObserver钩子、Cloudflare 运行时适配器和observe-recorder测试记录器——统称集成三件套。默认零开销打开后每次连接、文件读写、命令执行都会变成一条带属性的追踪 Span直接进入 Cloudflare 的ctx.tracing面板。本文带你用最短路径看懂这套机制并学会在测试中用记录器断言 Span 树。为什么 Agent 电脑需要可观测性Cloudflare Computer 给 Agent 提供了一块持久化的云硬盘 命令行文件存在 Durable Object 的 SQLite 里命令可以通过容器、Worker Shell 等多种后端执行。问题随之而来Agent 在云端动了哪些文件哪次同步慢了哪条命令失败了没有追踪信息这些全靠猜。上图展示了 Computer 的整体架构上层的 Container 通过 FUSE 挂载与下层 Durable Object 的 SQLite 存储同步见 docs/assets/arch.png。可观测性钩子就埋在这条链路的关键节点上——连接、同步、文件操作、命令执行每一步都会发出一个 Span。三件套总览各司其职组件文件职责①WorkspaceObserver钩子observe.ts定义统一的span(name, attributes, run)接口是全部埋点的插座② Cloudflare 适配器observe/cloudflare.ts把钩子接到 Cloudflare 运行时内置的ctx.tracing一行配置即可③observe-recorder记录器observe-recorder.ts在内存中录下完整的 Span 父子树专供测试断言使用这套设计的关键洞察是Cloudflare 运行时的 tracing 接口只支持回调包裹式 Spantracing.enterSpan(name, callback)无法先开始、后结束。所以钩子被设计成回调形态让三个组件都能无缝适配 Cloudflare 运行时、OpenTelemetry 和纯内存记录器。① WorkspaceObserver 钩子5 类内置 Span只需在创建Workspace时传入observer选项包内每个文档化操作都会自动发出一个 SpanSpan 名称触发时机workspace.connect每次连接后端携带后端 id 与类型属性workspace.sync.push每次推送本地变更带pushed计数workspace.sync.pull每次拉取远端变更带applied/skipped计数workspace.runtime.exec.spawn每次执行命令覆盖执行前推送、spawn、执行后拉取workspace.fs.op每个文件系统调用readFile、writeFile、stat、readdir、find、ls、grep、mkdir、rm三个细节值得注意Span 自动嵌套当命令执行并等待result()时workspace.runtime.exec会成为父节点workspace.sync.push和workspace.sync.pull自动成为它的子节点——无需手动维护调用链属性类型收窄只接受boolean | number | string三种标量与 CloudflareSpan.setAttribute签名完全对齐见 observe.ts默认零成本不传 observer 时走noopObserver直接返回回调的 Promise无额外await、无分配。② Cloudflare 适配器一行接入生产追踪这是三件套中最小的一个也是接入生产环境的那一个。从 npm 子路径cloudflare/computer/observe/cloudflare导入适配器把ctx.tracing交给它即可const observer createCloudflareObserver({ tracing: ctx.tracing });适配器只做两件事把种子属性转发到运行时 Span再把setAttribute转发给回调见 observe/cloudflare.ts。它的工程取舍很讲究参数注入而非依赖导入——Tracing实例通过参数传入而不是 importcloudflare:workers这样 Node 环境的单元测试也能直接跑且包不产生隐式运行时依赖优雅降级——部分环境没有 user-tracing 特性标志ctx.tracing会是undefined。此时适配器自动退化为纯透传同一份接线代码在两种环境下都能工作名称长度约束——运行时要求 Span 名称 ≤ 64 字节包内最长的workspace.runtime.exec.spawn只有 26 字节永远不会被截断。③ observe-recorder用录音机验证埋点observe-recorder.ts 里的makeRecorder()是一个测试专用观察者用一个简单的栈复现父子嵌套把每个 Span 的名称、属性、成功/失败结果和错误信息完整录进内存。它刻意放在非测试源文件中而不是*.test.ts这样集成测试可以直接共享下游用户也能在自己的测试里拿到同一个录音机。配套的一整套集成断言见 observe-integration.test.ts覆盖了典型场景连接成功 → 一个带workspace.backend.id属性的workspace.connectSpan连接失败 → Span 标记为error且不影响其他后端文件系统操作 → 每次调用一个workspace.fs.opSpanreaddir还带path和entries计数命令执行 →workspace.runtime.exec.spawn与sync.push/sync.pull的嵌套关系。对新手来说这是最好的学习材料想理解 Computer 内部流程先读这些测试。出错时发生什么记录、脱敏、再抛出Span 不只是计时器也是错误现场。当包裹的工作抛出异常时withSpan会先记录error.name和error.message然后原样抛出见 observe.ts。错误消息在落盘前经过三重清洗见 observe.ts控制字符替换为空格常见的凭据形态自动脱敏——tokenxxx、api_keyxxx、Bearer xxx一律替换为[REDACTED]截断到 512 字符以内。这意味着你可以放心地把 Span 导给任何追踪后端而不用担心日志里漏出密钥 。快速上手清单在Workspace构造参数中传入observer生产用 Cloudflare 适配器测试用makeRecorder()生产环境把ctx.tracing交给createCloudflareObserverSpan 即出现在 Cloudflare 的 user tracing 面板测试环境用makeRecorder()通过observer.spans断言名称、属性与嵌套不传 observer什么都不用做默认 no-op 保证零开销。更多背景见 packages/computer/README.md 的 Observability 章节以及包入口 index.ts 中导出的noopObserver与WorkspaceObserver类型。总结Cloudflare Computer 的可观测性三件套体现了典型的 Cloudflare 工程风格接口极小、默认免费、按需增强。钩子、适配器、记录器各管一段却共享同一个回调形态的 Span 契约——这让它既能直连ctx.tracing上生产也能在测试里当录音机用还能平移到 OpenTelemetry 生态。对于运行 Agent 工作负载的开发者来说这套机制让你用几行配置换来对整个云端文件系统的完整追踪视图。【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考