日志与可观测性

这一节解决什么问题

Agent 系统的执行链路长、涉及模块多——用户请求进来后可能经过模型调用、工具执行、状态更新、多轮推理等多个环节。没有可观测性，出了问题不知道原因，优化没有数据支撑，系统就像一个黑盒。

可观测性不是"出问题再看日志"，而是从设计阶段就纳入的工程能力。它让你能回答：这次执行为什么失败？哪个环节最慢？成本花在哪里？用户满意度如何？

本节会系统讲解 AI 应用可观测性的三大支柱（日志、Trace、指标）、Agent 系统特有的观测需求和工程化实践。

核心概念

可观测性是什么

可观测性（Observability）是指通过系统的外部输出来理解系统内部状态的能力。它由三个支柱组成：

• 日志（Logs）：记录系统中发生的事件
• 链路追踪（Traces）：记录一次请求的完整执行路径
• 指标（Metrics）：用于监控系统健康状态的量化数据

三者的关系：日志告诉你"发生了什么"，Trace 告诉你"怎么发生的"，Metrics 告诉你"整体表现如何"。

日志（Logs）

日志是系统事件的结构化记录。AI 应用需要记录的关键事件：

• 用户请求（输入内容、请求来源、时间戳）
• 模型调用（模型名称、输入摘要、输出摘要、耗时、token 消耗）
• 工具调用（工具名称、参数、返回结果、耗时、是否成功）
• 错误信息（错误类型、错误消息、上下文）
• 业务事件（任务状态变化、用户操作）

日志应该是结构化的（JSON 格式），而不是自由文本。结构化日志方便后续的搜索、过滤和分析。

{
  "timestamp": "2026-05-20T10:00:00Z",
  "level": "info",
  "event": "tool_call",
  "request_id": "req-abc123",
  "tool": "query_database",
  "duration_ms": 150,
  "success": true
}

链路追踪（Traces）

Trace 记录一次请求的完整执行路径。在 Agent 系统中，一次请求可能经过多个环节：用户输入 → 意图识别 → 工具调用 → 结果处理 → 模型生成 → 输出。

Trace 的每个节点记录：

• 开始时间和结束时间
• 输入和输出摘要
• 父节点 ID（建立调用链关系）
• 是否成功
• 关键决策摘要

Trace 的核心价值是"可回溯"——任何一次执行都可以被完整重现和分析。

指标（Metrics）

指标用于监控系统的整体健康状态。AI 应用的关键指标：

• 请求量：每秒请求数、并发数
• 响应时间：P50、P95、P99 延迟
• 模型调用耗时：平均耗时、超时率
• 工具调用成功率：成功/失败比例
• 错误率：各类错误的占比
• Token 消耗量：每次请求的 token 使用
• 成本统计：模型调用成本

指标应该关注趋势，不只是当前值。如果响应时间在逐渐变慢，即使当前还能接受，也需要提前排查。

模型调用日志

模型调用是 AI 应用的核心操作，需要详细记录：

• 模型名称和版本
• 输入 token 数和输出 token 数
• 调用耗时
• 是否成功
• 失败原因（超时、限流、参数错误）
• 输出摘要（不需要记录完整输出，记录关键信息即可）

模型调用日志是成本分析和性能优化的基础。

工具调用日志

工具调用记录应该包含：

• 工具名称
• 调用参数
• 返回结果摘要
• 执行耗时
• 是否成功
• 错误信息

工具调用日志是调试 Agent 行为的关键——当 Agent 给出错误答案时，通过工具调用日志可以定位是工具选择错误还是工具执行失败。

请求链路追踪

为每个请求生成唯一的 request_id，贯穿整个处理链路。request_id 应该出现在：日志中（方便搜索同一请求的所有日志）、响应中（方便用户反馈问题时提供）、Trace 中（串联整个执行过程）。

错误日志

错误日志应该包含足够的上下文：请求内容、执行到哪一步、什么错误、相关配置。只记录"出错了"没有意义，需要足够的信息来定位原因。

延迟统计

延迟统计应该细化到每个环节：模型调用延迟、工具调用延迟、数据库查询延迟、网络延迟。总延迟高但不知道是哪个环节慢，优化就无从下手。

成本统计

AI 应用的成本主要在模型调用。需要统计：每次请求的 token 消耗、每天/每月的总 token 消耗、按模型分类的成本、按用户分类的成本。成本统计是资源优化和商业决策的基础。

用户反馈

用户反馈是 Evaluation 的重要数据来源。可以收集：用户是否满意回答、用户是否标记错误、用户是否重新提问。用户反馈数据用于持续优化 Agent 质量。

失败样本收集

每次执行失败都应该被记录和分析。失败样本是优化的宝贵资源——分析失败原因、归类失败模式、针对性优化。没有失败样本收集，优化就是盲目的。

为什么重要

可观测性在 AI 应用工程中的价值体现在多个方面。

首先，问题定位。Agent 系统的执行链路长，出了问题需要快速定位是哪个环节。没有 Trace，只能猜测；有了 Trace，可以精确定位。

其次，性能优化。延迟统计和 token 统计告诉你哪里慢、哪里贵。优化应该基于数据，不是直觉。

再次，成本控制。AI 应用的模型调用有成本。没有成本统计，可能不知不觉花了很多钱。成本统计让你能做资源优化和预算规划。

最后，持续改进。用户反馈、失败样本、评测指标是持续改进的数据基础。没有这些数据，优化就是"拍脑袋"。

工程化理解

从工程角度看，可观测性不是"事后补救"，而是应该在系统设计阶段就纳入。

从第一天就加日志。不要等到出问题再补日志。日志应该在开发阶段就加入，而不是上线后才想起来。

统一日志格式。所有服务、所有模块用统一的日志格式（JSON 结构化日志），方便后续的搜索和分析。

Trace 覆盖完整链路。Trace 应该覆盖从用户输入到最终输出的每个环节。如果某个环节没有 Trace，出了问题就无法定位。

Metrics 关注趋势。指标应该持续采集和可视化。关注趋势比关注当前值更重要——逐渐变慢比突然变慢更隐蔽。

日志级别合理使用。DEBUG 用于开发调试、INFO 用于正常事件、WARNING 用于异常但不影响功能、ERROR 用于错误。不要把所有信息都用 INFO 级别。

日志不能影响性能。日志采集应该是异步的，不能阻塞主流程。日志量要控制，不要记录过多无用信息。

敏感信息脱敏。日志中不能包含用户密码、API Key 等敏感信息。如果必须记录，需要脱敏处理。

常见误区

误区一：出了问题再加日志

日志应该从开发阶段就加入。出了问题再补日志，意味着你需要先复现问题、再加日志、再等复现，浪费大量时间。

误区二：日志只记成功不记失败

成功和失败的日志都需要记录。只有失败日志，无法分析正常流程的性能和行为；只有成功日志，出了问题无法定位。

误区三：Trace 只记部分环节

Trace 应该覆盖完整链路。如果某个环节没有 Trace，出了问题就无法定位是哪个环节出错。

误区四：不需要成本统计

AI 应用的模型调用有成本。没有成本统计，可能不知不觉花了很多钱，或者某个异常请求消耗了大量 token。

误区五：敏感信息不脱敏

日志中包含 API Key、用户密码等敏感信息是安全隐患。日志可能被泄露、被未授权人员查看。所有敏感信息都需要脱敏。

和项目的关系

后续在项目实践中会用到可观测性能力，但当前阶段只做工程化知识准备，不展开具体项目实现。

理解日志、Trace、指标三大支柱的设计原则和工程化实践，是构建可维护 AI 应用的基础。

面试表达

可以这样表达：

> Agent 系统的可观测性是我重点关注的方向。我会为每次执行生成完整的 Trace，记录从用户输入到最终输出的每个步骤，包括关键决策摘要和工具调用记录。用结构化日志记录关键事件，通过 request_id 串联整个链路。用 Metrics 监控延迟、错误率和 token 消耗的趋势。另外，我会收集失败样本和用户反馈，作为持续优化的数据基础。没有可观测性的 Agent 系统就像黑盒——出了问题不知道原因，优化没有数据支撑。