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

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

【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer

Cloudflare 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 接口只支持"回调包裹"式 Span（tracing.enterSpan(name, callback)），无法"先开始、后结束"。所以钩子被设计成回调形态，让三个组件都能无缝适配 Cloudflare 运行时、OpenTelemetry 和纯内存记录器。

① WorkspaceObserver 钩子：5 类内置 Span

只需在创建Workspace时传入observer选项，包内每个"文档化操作"都会自动发出一个 Span：

Span 名称	触发时机
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）。

它的工程取舍很讲究：

1. 参数注入而非依赖导入——Tracing实例通过参数传入，而不是 importcloudflare:workers，这样 Node 环境的单元测试也能直接跑，且包不产生隐式运行时依赖；
2. 优雅降级——部分环境没有 user-tracing 特性标志，ctx.tracing会是undefined。此时适配器自动退化为纯透传，同一份接线代码在两种环境下都能工作；
3. 名称长度约束——运行时要求 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.<op>Span，readdir还带path和entries计数；
• 命令执行 →workspace.runtime.exec.spawn与sync.push/sync.pull的嵌套关系。

对新手来说，这是最好的学习材料：想理解 Computer 内部流程，先读这些测试。

出错时发生什么：记录、脱敏、再抛出

Span 不只是计时器，也是错误现场。当包裹的工作抛出异常时，withSpan会先记录error.name和error.message，然后原样抛出（见 observe.ts）。

错误消息在落盘前经过三重清洗（见 observe.ts）：

1. 控制字符替换为空格；
2. 常见的凭据形态自动脱敏——token=xxx、api_key=xxx、Bearer xxx一律替换为[REDACTED]；
3. 截断到 512 字符以内。

这意味着你可以放心地把 Span 导给任何追踪后端，而不用担心日志里漏出密钥 🔒。

快速上手清单

1. 在Workspace构造参数中传入observer（生产用 Cloudflare 适配器，测试用makeRecorder()）；
2. 生产环境把ctx.tracing交给createCloudflareObserver，Span 即出现在 Cloudflare 的 user tracing 面板；
3. 测试环境用makeRecorder()，通过observer.spans断言名称、属性与嵌套；
4. 不传 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