Kilo Agent Observability 指南从 API 指标到 Agent 行为与结果分析的可观测性路线图【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode本文基于 Kilo 仓库中packages/kilo-docs/pages/contributing/features/agent-observability.md的架构事实与路线图结合packages/core、packages/kilo-telemetry、packages/kilo-gateway的源码实现与文档证据系统讲解 Agent 编码系统当前已具备的可观测能力、待建设的运维指标Operational Metrics、Agent 行为分析Agent Behavior与结果分析Outcome路线以及 burn-rate 告警策略设计。读者可据此了解 Kilo 如何监控会话是否卡死、模型是否反复出错、任务是否真正完成这类传统请求指标覆盖不到的信号。为什么 Agent 系统需要独立的可观测性Agentic coding 系统Agent 编码系统的每次运行由模型请求、工具执行、文件修改和外部 API 调用共同组成。传统的请求级指标Request Metrics能捕获硬性失败hard failures例如请求超时、HTTP 5xx、token 配额耗尽但大量真正影响体验的问题并不表现为请求失败而是Agent 陷入重复动作循环反复调用同一工具、反复提交同一失败请求会话退化degraded session——看起来在运行实际上没有产生有效进展任务以不理想的方式结束——被放弃、超时或被错误结果伪完成。Kilo 的 Agent Observability 文档因此将可观测性划分为三个层次已落地的指标与告警基础设施、行为信号分析识别循环与停滞、结果分析判断任务是否真正成功并明确标注了每一项能力的当前状态Current / Planned / Partial。文档开头的 Status 提示如下Partial - API metrics, session ingestion, storage, and burn-rate alert infrastructure exist. Higher-order agent behavior and outcome analysis remain roadmap work.即API 指标、会话摄取、存储和 burn-rate 告警基础设施已经存在高阶的 Agent 行为分析和结果分析仍属于路线图工作。这正是理解本文的基调——本文描述的是现状 计划双轨文档阅读时需区分已验证的当前能力与规划中的目标。当前实现已经落地的基础设施能力现状总览原文档以表格形式给出了当前实现的能力清单完整继承如下能力Capability状态说明API metrics ingestionCurrent已存在可运营的请求指标摄取Session metrics ingestionCurrent已存在会话级指标摄取Burn-rate alert evaluationCurrent告警评估基于已存储指标运行Alert config storageCurrent已存在告警配置存储Analytics Engine storageCurrent已存在 API 与会话指标数据集Export pipelinesCurrent infrastructure已存在面向下游分析的指标导出基础设施Per-message feedbackCurrent已存在显式用户反馈信号云端 o11y 基础设施对应 Cloud Platform 文档Cloud Platform observability 章节 给出了services/o11y/作为当前指标与告警基础设施的静态源码事实注意该章节路径相对Kilo-Org/cloud仓库属于托管平台层表面Surface静态源码行为Alert evaluationWorker cron 每分钟运行一次API metricsAnalytics Engine dataset Pipeline streamSession metricsAnalytics Engine dataset Pipeline streamExportPipelines 双写 R2 Parquet 数据供 Snowflake 导出基础设施使用Alert deduplicationKV namespace 存储基于 TTL 的冷却cooldown状态Alert configurationAlertConfigDO存储强一致配置Session connectionsession-ingest绑定o11y并发出会话指标从该表可以梳理出完整的指标生命周期链路客户端/网关产生指标 → Analytics Engine dataset 落库 → Pipeline stream 导出 R2 Parquet → Snowflake 下游分析告警侧则是AlertConfigDO 存配置 → 每分钟 cron 评估 → KV TTL 去重。这也是原文档burn-rate alert evaluation当前已存在的底层支撑。客户端侧的可观测性实现证据在开源仓库内客户端侧可观测性有两条可直接阅读的源码路径1. OTLP 日志与追踪核心层packages/core/src/observability/otlp.ts 展示了基于 Effect 与 OpenTelemetry 的导出实现通过Flag.OTEL_EXPORTER_OTLP_ENDPOINT决定是否启用导出未设置端点时返回空 Layer实现零成本关闭OTEL_EXPORTER_OTLP_HEADERS以keyvalue,keyvalue形式解析为 HTTP 请求头resource()将OTEL_RESOURCE_ATTRIBUTES环境变量解析为资源属性并附加deployment.environment.name安装渠道、opencode.clientKilo 客户端标识、opencode.run/service.instance.id来自shared.ts的 runID等属性日志通过OtlpLogger发往${endpoint}/v1/logs追踪通过BatchSpanProcessor OTLPTraceExporter发往${endpoint}/v1/traces并注册AsyncLocalStorageContextManager以便 AI SDK 正确挂接 span 父子关系。这从源码层面印证了原文档API metrics ingestion 已存在的客户端基础模型请求的 provider、model、latency、成功/失败、token 等维度正是由这类遥测管线承载。2. 客户端遥测事件kilo-telemetrypackages/kilo-telemetry/src/telemetry.ts 定义了与会话指标和显式反馈直接对应的事件跟踪函数会话生命周期trackSessionStart/trackSessionEnd携带messageCount、inputTokens、outputTokens、duration模型调用trackLlmCompletion携带apiProvider、modelId、token 明细、cost、duration行为信号trackToolUsed、trackAgentUsed显式用户反馈trackFeedbackFeedbackProperties含providerID、modelID、rating: up | down | cleared、sessionID、messageID、parentMessageID——这正是能力表中 Per-message feedback 的实现入口索引与错误trackIndexingStarted/Completed/Error、trackError等。遥测开关遵循KILO_TELEMETRY_LEVEL环境变量all启用与enabled选项的联合判断且初始化后通过Client.setEnabled控制。相应测试位于 packages/kilo-telemetry/src/tests/telemetry.test.ts。使用前提与限制需要强调的是以上内容中services/o11y/、Analytics Engine dataset、Pipeline、Snowflake 导出、AlertConfigDO等属于云端平台层Cloud 仓库的静态源码表面不代表生产环境的实际启用量、回滚比例或保留配置。文档明确要求在把任一字段当作生产分析可用之前必须先验证指标覆盖metric coverage。这是本文所有当前能力结论的适用前提。运维指标路线图用现有摄取与告警基建支撑 SLO原文档指出应复用已有的摄取与告警基础设施作为仪表盘和服务级目标SLO的底座。核心原则是任何指标字段在未经验证前不得视为生产分析中可用。API 指标候选维度面向模型请求model requests的候选维度Provider模型提供商Model模型Tool工具Latency延迟Success or failure成功或失败Error type错误类型Token countsToken 计数Client source客户端来源其中 Provider/Model/Token 维度在 packages/kilo-telemetry/src/telemetry.ts 的trackLlmCompletion属性中均有对应字段说明客户端在事件源头就已具备这些标签而 Kilo Gateway 侧的用量展示如配额窗口的hour/day/week/month周期、used/remaining/limit状态可见于 packages/kilo-gateway/src/provider-usage.ts是Client source / 用量归属落地的另一处参考实现。会话指标候选聚合面向会话session的候选聚合项Session duration会话时长Time to first model response首次模型响应耗时Turns and tool calls轮数与工具调用数Errors by type按类型分组的错误Tokens consumed消耗的 TokenContext compaction frequency上下文压缩频率Termination reason终止原因会话级指标在客户端已有基础trackSessionEnd携带messageCount、inputTokens、outputTokens、duration可视为会话时长/Token 消耗的最小可行集Termination reason与下文会话终止分类路线直接相关属于待建设项。告警策略burn-rate 分级路由Burn-rate 评估基础设施已存在每分钟 cron 评估 KV TTL 去重。原文档给出的建议告警路由策略为仅对使用 Kilo Gateway 的推荐模型recommended models进行 page呼叫值班其他条件下的告警可创建 ticket 或保持禁用。建议的窗口/阈值如下窗口Burn rate建议动作5 分钟14.4xPage——重大故障major outage30 分钟6xPage——事件incident6 小时1x创建 ticket——行为变化behavior changeBurn rate 的语义是在窗口内错误消耗 SLO 预算的速度倍数14.4x 意味着 5 分钟内以 14.4 倍于预算速率燃烧必须立即处理1x 持续 6 小时则代表预算被匀速耗尽属于值得追踪的行为漂移而非紧急故障。这一分级与短窗口高倍数 page、长窗口低倍数建 ticket的通用 SLO 实践一致但具体阈值是本文档的提议值落地前应结合真实 SLO 预算验证。Agent 行为路线图从请求是否成功到Agent 是否在进步传统指标回答这次调用成功没有行为分析要回答Agent 是否在产生有效进展。原文档建议初始行为分析聚焦重复操作与进展信号信号清单如下信号目的Identical tool calls相同工具调用检测使用相同工具和参数的重复动作Identical failing calls相同失败调用检测重复相同失败的 retryOscillation patterns振荡模式检测无进展的交替状态Unique files touched唯一文件数估算会话变更广度Unique tools used唯一工具数将进展与重复操作对比Repeated-to-unique ratio重复/唯一比识别可能卡住的会话这组信号的设计逻辑很清晰重复动作本身不一定是问题合法的重试、格式化、多文件编辑都可能是重复的因此需要唯一文件数唯一工具数作为进展基准用重复/唯一比把高重复 低唯一的会话标记为疑似卡死stuck。从仓库证据看trackToolUsed/trackAgentUsedpackages/kilo-telemetry/src/telemetry.ts已经为工具调用计数提供了原始事件基础而振荡检测唯一文件/工具统计的聚合与判定逻辑仍在路线图阶段Oscillation detection 状态为 Planned or partial。结果路线图从硬错误到任务是否真正有用原文档明确指出一个关键局限硬错误与行为指标都不能证明用户成功。一个会话可能没有任何错误、也没有卡死但产出的结果毫无价值。因此结果分析Outcome roadmap规划了三个方向的组合显式逐条反馈explicit per-message feedback——当前已存在trackFeedback的rating: up/down/cleared见 packages/kilo-telemetry/src/telemetry.ts会话终止分析session termination analysis——区分完成 / 放弃 / 超时 / 错误四类终止对应路线图中的 Session termination classification其他结果信号——将反馈与终止分析组合评估有用性usefulness与任务成功task success这类高阶结果。此外原文档明确把离线模型与 Agent 对比划归 Benchmarking 主题Benchmarking 页面强调Benchmarking 与生产可观测性分离——可观测性监控真实会话Benchmarking 运行受控评估任务。二者互补可观测性回答线上表现如何基准回答在受控任务集上谁更好。路线图状态速查表综合原文档的 Roadmap 部分完整状态清单如下能力状态目标Oscillation detection振荡检测Planned or partial检测重复或交替的 Agent 动作Unique-file progress metrics唯一文件进展指标Planned or partial追踪会话期间接触的文件Unique-tool progress metrics唯一工具进展指标Planned or partial追踪工具多样性与重复操作Session termination classification会话终止分类Planned区分完成、放弃、超时与错误Higher-order outcome analysis高阶结果分析Planned超越硬错误评估有用性与任务成功结论如何阅读与使用本文档Kilo 的 Agent Observability 现状可以概括为一句话摄取与告警的地基已铺好行为与结果的判断仍在路上。实际使用中请注意三条纪律区分事实与计划能力表中标 Current 的项API/会话指标摄取、burn-rate 评估、告警配置存储、Analytics Engine 数据集、导出管道、逐条反馈有文档与源码支撑标 Planned / Partial 的项振荡检测、唯一文件/工具指标、终止分类、高阶结果分析是路线图目标不应视为现成能力。先验证再使用云端o11y相关结论来自静态源码表面生产启用、保留与供应商配置需另行验证任何指标字段在验证 metric coverage 前不得直接用于生产分析。观察真实会话基准评估受控任务需要横向对比模型或 Agent 时应转向 Benchmarking 的受控评估设计而非依赖线上可观测数据。仓库内可继续深入阅读的证据入口核心层 OTLP 实现 packages/core/src/observability/otlp.ts 与 packages/core/src/observability/shared.ts、客户端遥测事件定义 packages/kilo-telemetry/src/telemetry.ts、云端平台观测章节 packages/kilo-docs/pages/contributing/architecture/cloud-platform.md以及相邻的 Benchmarking 主题页。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
