系列AI Agent 工程实践上一篇第 26 篇《Prompt Management》下一篇第 28 篇《可观测性Observability》一、开场一个只能盲猜的线上 bug一个 Agent 偶尔返回奇怪答案频率很低复现不了。团队排查了一周最后发现系统里没有任何日志只能靠读代码盲猜。加了结构化日志后半小时定位到——某个工具的返回被截断导致模型拿到残缺上下文。问题AI 系统最大的调试障碍不是代码难是运行时发生了什么看不见。上篇26讲提示词收口这篇讲最底层的底座——日志系统 Logging。二、问题背景print 调试 vs 结构化日志print 版print(calling llm, messages) print(got, resp)结构化版logger.info(agent_run, extra{ session: sid, model: deepseek-chat, input_tokens: 1200, output_tokens: 300, latency_ms: 850, cost_usd: 0.002, tool: get_weather, })差别print 只给人临时看结构化日志能被系统采集、检索、聚合是可观测的原料。三、错误尝试三种日志翻车错误 1只用 print如上。无法检索、无级别、无字段出问题只能人肉翻控制台。错误 2日志不结构化logger.info(fuser {u} asked {q} got {a}) # 纯文本无法按字段过滤想统计哪个工具最慢得正则解析文本——不可行。错误 3不打关键字段只打调用成功不打印 prompt / completion / token / cost。真出问题时缺的恰恰是最关键的那些。四、关键观察AI 工程的日志要打满 8 类字段AI 系统调试需要的远多于普通后端。最少要记录Prompt本次输入含 system/user/tool。Completion模型输出含 text / tool_calls。Tokeninput / output 用量。Latency各阶段耗时。Cost本次花费钱。Memory读写的内容摘要。Tool调用了哪个工具、参数、结果。Error异常类型与上下文。没有这 8 类你既调不了 bug也优化不了成本更追不了责。日志是 AI 工程最重要的底座没有之一——它喂养了下篇28的可观测性。五、最终方案结构化日志长什么样日志事件示例JSON{ event: agent_run, session: s_8821, model: deepseek-chat, input_tokens: 1200, output_tokens: 300, latency_ms: 850, cost_usd: 0.0021, tools_called: [get_weather], error: null, ts: 2026-07-26T10:00:00Z }字段速查表字段用途event区分阶段agent_run / tool_call / memory_readsession串联同一次会话model成本/质量归因input/output_tokens成本计算 超长预警latency_ms性能瓶颈定位cost_usd成本监控对应 29 篇tools_called行为审计error失败归因请求流中日志的角色Mermaid六、代码对比print vs 结构化print问题print(llm done, resp.choices[0].message.content)结构化生产logger.info(agent_run, extra{ session: sid, model: provider.name, input_tokens: usage.prompt_tokens, output_tokens: usage.completion_tokens, latency_ms: elapsed, cost_usd: estimate_cost(usage, provider.name), })关键差异结构化字段可被采集系统直接聚合cost_usd字段直接喂给成本监控29 篇。七、设计权衡打什么不打什么决策建议理由全 8 类字段生产必打调 bug/成本/审计都靠它敏感信息PII/密钥脱敏后再打合规 安全极高流量采样 关键路径全量控日志成本原型基础字段即可不必一步到位反过度工程不要为日志再引一套复杂 pipeline 拖慢开发。先打 JSON 结构化日志 文件/简单采集规模上来再接专业系统。八、总结✅ 无日志 线上 bug 只能盲猜一个截断 bug 查了一周。✅ 三种翻车只用 print、日志不结构化、不打关键字段。✅ AI 日志要打满 8 类Prompt / Completion / Token / Latency / Cost / Memory / Tool / Error。✅ 结构化 JSON 字段才能被采集、检索、聚合是下篇可观测性的原料。✅ 反过度工程先结构化文件再接专业系统敏感信息务必脱敏。下一篇在日志之上建看得见每一步的能力——可观测性 Observability。28参考资料带用途说明本系列26Prompt Management本文是26之后最该先补的底座——提示词改了没日志就不知影响。本系列28可观测性Observability日志是28Trace/Span 的原料本文是28的前置。本系列29成本控制本文cost_usd字段直接喂给29的成本监控。OpenTelemetry Logs 文档opentelemetry.io结构化日志与语义约定的标准来源。Python logging 文档docs.python.org本文结构化日志extra用法的实现参考。本文是 AI Agent 工程实践系列的第 27 篇第四阶段第七篇。系列导航上一篇第 26 篇《Prompt Management》下一篇第 28 篇《可观测性Observability》 
长河君 · 2026/8/14 15:17:01 · 阅读 1.2k AI Agent 工程实践（27）：日志系统（Logging）
系列AI Agent 工程实践上一篇第 26 篇《Prompt Management》下一篇第 28 篇《可观测性Observability》一、开场一个只能盲猜的线上 bug一个 Agent 偶尔返回奇怪答案频率很低复现不了。团队排查了一周最后发现系统里没有任何日志只能靠读代码盲猜。加了结构化日志后半小时定位到——某个工具的返回被截断导致模型拿到残缺上下文。问题AI 系统最大的调试障碍不是代码难是运行时发生了什么看不见。上篇26讲提示词收口这篇讲最底层的底座——日志系统 Logging。二、问题背景print 调试 vs 结构化日志print 版print(calling llm, messages) print(got, resp)结构化版logger.info(agent_run, extra{ session: sid, model: deepseek-chat, input_tokens: 1200, output_tokens: 300, latency_ms: 850, cost_usd: 0.002, tool: get_weather, })差别print 只给人临时看结构化日志能被系统采集、检索、聚合是可观测的原料。三、错误尝试三种日志翻车错误 1只用 print如上。无法检索、无级别、无字段出问题只能人肉翻控制台。错误 2日志不结构化logger.info(fuser {u} asked {q} got {a}) # 纯文本无法按字段过滤想统计哪个工具最慢得正则解析文本——不可行。错误 3不打关键字段只打调用成功不打印 prompt / completion / token / cost。真出问题时缺的恰恰是最关键的那些。四、关键观察AI 工程的日志要打满 8 类字段AI 系统调试需要的远多于普通后端。最少要记录Prompt本次输入含 system/user/tool。Completion模型输出含 text / tool_calls。Tokeninput / output 用量。Latency各阶段耗时。Cost本次花费钱。Memory读写的内容摘要。Tool调用了哪个工具、参数、结果。Error异常类型与上下文。没有这 8 类你既调不了 bug也优化不了成本更追不了责。日志是 AI 工程最重要的底座没有之一——它喂养了下篇28的可观测性。五、最终方案结构化日志长什么样日志事件示例JSON{ event: agent_run, session: s_8821, model: deepseek-chat, input_tokens: 1200, output_tokens: 300, latency_ms: 850, cost_usd: 0.0021, tools_called: [get_weather], error: null, ts: 2026-07-26T10:00:00Z }字段速查表字段用途event区分阶段agent_run / tool_call / memory_readsession串联同一次会话model成本/质量归因input/output_tokens成本计算 超长预警latency_ms性能瓶颈定位cost_usd成本监控对应 29 篇tools_called行为审计error失败归因请求流中日志的角色Mermaid六、代码对比print vs 结构化print问题print(llm done, resp.choices[0].message.content)结构化生产logger.info(agent_run, extra{ session: sid, model: provider.name, input_tokens: usage.prompt_tokens, output_tokens: usage.completion_tokens, latency_ms: elapsed, cost_usd: estimate_cost(usage, provider.name), })关键差异结构化字段可被采集系统直接聚合cost_usd字段直接喂给成本监控29 篇。七、设计权衡打什么不打什么决策建议理由全 8 类字段生产必打调 bug/成本/审计都靠它敏感信息PII/密钥脱敏后再打合规 安全极高流量采样 关键路径全量控日志成本原型基础字段即可不必一步到位反过度工程不要为日志再引一套复杂 pipeline 拖慢开发。先打 JSON 结构化日志 文件/简单采集规模上来再接专业系统。八、总结✅ 无日志 线上 bug 只能盲猜一个截断 bug 查了一周。✅ 三种翻车只用 print、日志不结构化、不打关键字段。✅ AI 日志要打满 8 类Prompt / Completion / Token / Latency / Cost / Memory / Tool / Error。✅ 结构化 JSON 字段才能被采集、检索、聚合是下篇可观测性的原料。✅ 反过度工程先结构化文件再接专业系统敏感信息务必脱敏。下一篇在日志之上建看得见每一步的能力——可观测性 Observability。28参考资料带用途说明本系列26Prompt Management本文是26之后最该先补的底座——提示词改了没日志就不知影响。本系列28可观测性Observability日志是28Trace/Span 的原料本文是28的前置。本系列29成本控制本文cost_usd字段直接喂给29的成本监控。OpenTelemetry Logs 文档opentelemetry.io结构化日志与语义约定的标准来源。Python logging 文档docs.python.org本文结构化日志extra用法的实现参考。本文是 AI Agent 工程实践系列的第 27 篇第四阶段第七篇。系列导航上一篇第 26 篇《Prompt Management》下一篇第 28 篇《可观测性Observability》