Observability

可观测性：日志、追踪与审计

🛠️ 工程化 · 🏠 首页 › Observability

---

📑 本页目录

• 1. 五条观测通道
• 2. 结构化日志（core:logging）
• 3. 工具追踪（ToolTraceRecorder）
• 4. 任务层观测（T76）
• 5. 终端事件
• 6. 诊断建议：出问题先看哪里
• 7. 相关页面

一个能自主执行 25 轮 ReAct、调用上百次工具的系统，没有可观测性就无从排错。 本页汇总项目里所有"能事后复盘"的通道。

1. 五条观测通道

通道	位置	粒度	用途
AppLogger（结构化日志）	core:logging	LogCategory / LogLevel / LogRecord	全项目日志，运行日志屏消费
ToolTraceRecorder	core:tool-registry	每次尝试一个 ToolTraceSpan	"具体哪次调用、什么参数、第几轮重试"
ToolUsageTracker	core:tool-registry	每工具聚合计数	"多常调用、多快、成功率"
TaskRuntimeEvent + journal	core:agent-engine/task/	任务生命周期边界	"任务第几步、中断在哪"
TerminalEventLog / TerminalEventBus	platform/terminal	每 session 有界 500 事件	终端会话复盘

外加浏览器侧 BrowserTracer（内存环形缓冲 100 条：工具 / 参数 / 结果 / 耗时 / URL / 状态）。

2. 结构化日志（core:logging）

AppLogger.<level>(category, message, ...)
LogCategory：按领域分类（引擎 / 工具 / 终端 / 记忆 / 网络 / UI …）
LogLevel：  DEBUG / INFO / WARN / ERROR

运行日志屏（ui/screen/log/LogViewerScreen.kt）可浏览与导出。

Warning

提交日志给 Issue 前务必打码 API Key、PAT、手机号、Cookie —— 导出内容包含完整上下文。

3. 工具追踪（ToolTraceRecorder）

ToolTraceSpan(callId, toolId, durationMs, outcome, attempt, argsDigest, errorSlug)

设计	原因
args 摘要而非原文（长度 / 可打印字符计数）	诊断导出不含用户粘贴的机密
环形有界缓冲（默认 200，app 配 300）	内存有界
监听器分发 + JSON 导出 + 直方图报告	可接入不同消费方
幂等完成（同一 handle 二次 complete 不产生幻影 span）	避免重试导致统计失真

与 ToolUsageTracker 并存：tracker 答"多常/多快"，tracer 答"哪一次"。

4. 任务层观测（T76）

• LlmRequestContext.taskId / stepId：execute 入口设 taskId、StepStart 设 stepId、finalize 清空；引擎全部 7 个构造点经 tagged() 包裹；
• TaskRuntimeEvent（低频通道）：StatusChanged / CheckpointSaved / Finished / RetryExhausted / RecoverableDiscovered；
• journal 脱敏：参数摘要截断 512 字符、输出摘要截断 256 字符，不落 prompt 全文；journal 滚动保留最近 200 条。

5. 终端事件

对象	约束
TerminalEventLog	append-only，按 sessionId 分片；每 session 上限 10_000 条（超限批量裁剪最旧 1_000 条）
TerminalEventBus	SharedFlow extraBufferCapacity = 1024，每订阅者独立游标（互不推进）
RingBuffer	默认 256KB，游标越界返回 overrun = true + 空字节 —— 从不静默丢弃

6. 诊断建议：出问题先看哪里

现象	先看
工具失败但不知原因	ToolTraceSpan.errorSlug + 运行日志（工具分类）
工具被拒（限流/熔断/环境）	追踪里的 outcome + outcome 附带的模型可读修复指引
任务中断/不知做到哪一步	任务横幅 + journal（SUCCEEDED/FAILED/UNKNOWN）
终端命令"像是没执行"	TerminalEventLog + 语义状态（WAITING_INPUT / RUNNING）
记忆"该记的没记住"	cs-mem 分类日志 + 免疫系统判定
浏览器卡住	browser_debug_dump（BrowserTracer 环形缓冲）
长任务变慢	RunSummaryCard（迭代数 / 工具调用数 / 总耗时）+ 压缩事件计数

7. 相关页面

• 工具系统（追踪与熔断）· 任务运行时
• 终端性能 · 混沌工程 · 故障排查

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}