§07 可观测性：内置追踪、指标、日志

07.1 先给结论

Cloudflare Agents 内置了一套事件系统。RPC 调用、状态变更、调度执行、工作流流转、MCP 连接——全有结构化的事件。没人听的时候零开销。

07.2 事件长什么样

{
  type: "rpc",            // 发生了什么
  agent: "MyAgent",       // 哪个类
  name: "user-123",       // 哪个实例（DO name）
  payload: { method: "getWeather" },
  timestamp: 1758005142787
}

07.3 本地订阅看事件

import { subscribe } from "agents/observability";

const unsub = subscribe("rpc", (event) => {
  if (event.type === "rpc") console.log(`RPC call: ${event.payload.method}`);
  if (event.type === "rpc:error") console.error(`RPC failed: ${event.payload.error}`);
});

07.4 生产用 Tail Worker

生产环境不用在 Agent 里写订阅。挂一个 Tail Worker，自动收到所有诊断事件。

export default {
  async tail(events) {
    for (const event of events) {
      for (const msg of event.diagnosticsChannelEvents) {
        // msg.channel 是 "agents:rpc"、"agents:workflow" ...
        console.log(msg.timestamp, msg.channel, msg.message);
      }
    }
  },
};

维度	本地 subscribe	生产 Tail Worker	标叔的结论
接入成本	改代码	挂一个 Worker	生产用 Tail
热路径开销	零（没人听就静默）	零（平台转发）	都不拖慢
适用	调试	监控告警	两个都配

核心建议

开发期用 subscribe 抓 bug，上线用 Tail Worker 接日志系统。别把调试代码留生产。

可观测这块讲完。下一 Part 进进阶实战，先拆一个真实聊天 Agent。