调试与可观测性：CopilotKit 的调试模式和遥测系统

调试与可观测性：CopilotKit 的调试模式和遥测系统

学习目标

理解 CopilotKit 的调试和可观测性工具：

• DebugConfig 的三级开关
• DebugEventBus 事件收集和回放
• Pino 结构化日志
• Telemetry 遥测客户端
• Web Inspector 调试控制台

前置知识

无特定前置知识。

项目实践

DebugConfig 三级开关

前端和后端都支持细粒度的调试配置：

DebugConfig 结构（源码验证，@copilotkit/shared）：
{
  events: boolean,      // 是否记录每个事件（默认 true）
  lifecycle: boolean,   // 是否记录请求/运行生命周期（默认 true）
  verbose: boolean      // 是否记录完整 payload vs 摘要（默认 false）
}

前端启用：

<CopilotKit debug={true}>      // 全部开启
<CopilotKit debug={{ events: true, verbose: false }}>  // 细粒度

后端启用：

const runtime = new CopilotSseRuntime({
  debug: true
});

normalize 逻辑（源码验证 resolveDebugConfig()）：

• debug: true → { events: true, lifecycle: true, verbose: true }
• debug: false → { events: false, lifecycle: false, verbose: false }
• debug: { ... } → 合并默认值

DebugEventBus

开发环境的事件总线，收集和回放 AG-UI 事件：

仅在 NODE_ENV !== "production" 时创建（源码验证）：
if (process.env.NODE_ENV !== "production") {
  this.debugEventBus = new DebugEventBus();
}

用途：

• 开发时收集所有 AG-UI 事件
• Web Inspector 调试控制台读取事件并展示
• 生产环境自动禁用（零性能开销）

Pino 结构化日志

Runtime 端的调试日志使用 Pino：

日志器创建（源码验证）：
this.debugLogger = createLogger({
  level: "debug",
  component: "copilotkit-debug"
});

记录的事件（源码验证）：

• Agent run started
• SSE stream opened/completed/errored
• 每个 AG-UI 事件发射
• 中间件执行

Telemetry 遥测

@copilotkit/license-verifier 集成的遥测客户端：

遥测设置（源码验证）：
const licenseToken = options.licenseToken ?? process.env.COPILOTKIT_LICENSE_TOKEN;
if (licenseToken) {
  telemetry.setLicenseToken(licenseToken);
}
logRuntimeTelemetryDisclosure();  // 非生产环境记录遥测披露

遥测披露文件：packages/runtime/src/lib/telemetry-disclosure.ts

Web Inspector

@copilotkit/web-inspector 包提供调试控制台：

• 基于 Lit 构建的 Web Components
• 在开发模式下加载
• 实时显示 Agent 间通信的事件流
• 可视化调试 Agent 运行状态

客户端调试

CopilotKit 前端的 debug 配置传递给 AG-UI 传输层（transformChunks）：

前端 debug 传递链（源码验证）：
<CopilotKit debug={true}>
  → CopilotKitCore config.debug
    → ProxiedCopilotRuntimeAgent config.debug
      → AG-UI transport transformChunks debug

注意：CopilotKit 自身不发射客户端 console.debug 调用——debug 配置只用于配置底层 AG-UI 事件管道的传输级调试输出。

问题与规避

问题	规避策略
verbose 模式导致日志量过大	生产环境关闭 verbose；仅在排查问题时开启
DebugEventBus 内存泄漏	仅在开发环境创建；生产环境为 undefined
遥测数据包含敏感信息	遥测披露文件明确记录收集内容；可选择不设置 license token

设计取舍

开发环境 vs 生产环境

开发环境：

• DebugEventBus 启用
• Pino debug 级别日志
• Web Inspector 加载
• verbose 模式可选

生产环境：

• DebugEventBus 不创建
• Pino 仅 warning 及以上
• Web Inspector 不加载
• 遥测仅发送聚合数据

参考来源

• packages/shared/src/debug.ts（DebugConfig、resolveDebugConfig）
• packages/runtime/src/v2/runtime/core/debug-event-bus.ts
• packages/runtime/src/lib/telemetry-disclosure.ts
• packages/runtime/src/lib/logger.ts
• packages/web-inspector/