Agent日志体系
1. 定义与边界
Agent 日志体系是对 Agent 输入、决策、工具调用、状态变更、安全策略和用户反馈的结构化记录。它不是把 prompt 和回答全文塞进日志，而是按事件记录可查询、可聚合、可审计的信息。
2. 为什么重要
没有日志，生产问题只能靠复述和猜测。Agent 失败经常跨越模型、工具、检索、权限和业务系统，结构化日志是定位和审计的基础。
3. 核心机制
日志事件建议分层：
| 层级 | 事件示例 |
|---|---|
| 会话 | task_started、task_finished、task_failed |
| 模型 | model_call_started、model_call_finished |
| 工具 | tool_call_requested、tool_call_finished、tool_call_denied |
| 安全 | guardrail_triggered、policy_check_failed |
| 用户 | feedback_submitted、handoff_requested |
4. 工程实现
统一日志结构：
{
"timestamp": "2026-05-09T10:00:00Z",
"level": "INFO",
"trace_id": "tr_001",
"span_id": "sp_003",
"event": "tool_call_finished",
"agent_version": "support_agent_3.1",
"user_hash": "u_hash",
"task_type": "refund",
"tool_name": "refund_payment",
"tool_risk": "payment",
"status": "denied",
"reason": "missing_user_confirmation"
}
字段原则：
- 标识字段：trace_id、span_id、request_id、user_hash、tenant_id。
- 版本字段：agent_version、prompt_version、tool_schema_version、policy_version。
- 分类字段：task_type、risk_level、channel、environment。
- 结果字段：status、error_code、failure_reason、latency_ms、cost。
5. 生产实践
- 日志先脱敏再落盘，密钥、完整身份证号、银行卡、访问 token 不应进入日志。
- 原始 prompt 和工具返回只在必要场景受控保存，并设置保留期。
- 高风险事件使用审计日志，避免被普通日志清理策略删除。
- 日志格式要稳定版本化，方便长期查询和告警。
6. 常见反模式
- 只打自然语言日志，后续无法聚合。
- 只记录失败，不记录成功基线，导致无法计算比例。
- 把完整用户隐私写入 debug 日志。
- 没有 trace_id，多个系统日志无法关联。
7. 评测方法
日志体系本身也要验收：
| 检查项 | 标准 |
|---|---|
| Trace 覆盖率 | 生产任务中带 trace_id 的比例 |
| 关键事件覆盖率 | 模型、工具、护栏、结果是否都有事件 |
| 脱敏通过率 | 抽检日志中无明文敏感信息 |
| 查询可用性 | 能按用户反馈定位到完整 trace |
8. 安全与治理
日志是敏感资产。需要访问控制、保留周期、加密、审计、脱敏和数据最小化。对安全事件，日志要能证明 Agent 为什么执行或拒绝某个动作。
9. 权威资料
- OpenTelemetry logs: https://opentelemetry.io/docs/concepts/signals/logs/ （核对日期：2026-05-09）
- OpenTelemetry semantic conventions for generative AI: https://opentelemetry.io/docs/specs/semconv/gen-ai/ （核对日期：2026-05-09）
- OWASP Top 10 for LLM Applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/ （核对日期：2026-05-09）
- NIST AI RMF: https://www.nist.gov/itl/ai-risk-management-framework （核对日期：2026-05-09）
10. 二次精修：结构化日志 schema
Agent 日志必须能回答：谁、在什么版本、基于什么输入、调用了什么工具、为什么失败、是否触发安全策略。
{
"timestamp": "2026-05-09T10:20:30Z",
"level": "INFO",
"event_name": "agent.tool_call.completed",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"run_id": "run_123",
"tenant_id": "t_123",
"agent_id": "refund_agent",
"agent_version": "1.8.2",
"prompt_version": "refund.system@2026-05-09.3",
"model": "gpt-5",
"tool_name": "search_order",
"tool_status": "ok",
"duration_ms": 320,
"input_tokens": 2100,
"output_tokens": 120,
"cost_usd": 0.04,
"policy_decision": "allow",
"error_code": null
}
| 字段 | 用途 | 脱敏要求 |
|---|---|---|
trace_id/span_id | 关联 trace | 不含业务数据 |
tenant_id/user_id | 分租户分析 | 低权限视图可 hash |
prompt_version | 回放和回滚 | 不记录 prompt 全文 |
tool_name/tool_status | 工具质量分析 | 参数用 hash 或摘要 |
policy_decision | 安全审计 | 保留策略版本 |
cost_usd | 成本监控 | 不含敏感输入 |
11. 日志事件分类
| 事件名 | 必须字段 | 告警用途 |
|---|---|---|
agent.run.started | run_id、agent_version、budget | 量级异常 |
agent.model.completed | model、tokens、latency | 成本延迟 |
agent.tool_call.completed | tool、status、duration | 工具错误 |
agent.policy.checked | policy、decision | 安全审计 |
agent.run.completed | outcome、cost、latency | SLO |
agent.security_event | severity、rule、action | 安全告警 |
12. 日志治理与评测
- 日志采样不能丢关键安全事件；普通成功事件可采样，高危和失败事件全量保留。
- 日志字段要有 schema 测试，发布时校验关键字段不缺失。
- PII、密钥、完整 prompt、完整工具参数默认不进普通日志。
- 日志保留周期按数据分级设置，安全审计日志通常比调试日志保留更久。
- 评测指标：Log Completeness、PII Leakage Count、Schema Violation Rate、Event Drop Rate、Correlation Success Rate。
13. Runbook 检查
- 没有
trace_id的错误日志优先修复。 - 看到
agent.security_event的 critical 事件，先确认是否有真实副作用。 - 成本日志突增时按
prompt_version、tool_name、tenant_id分片。 - 工具错误突增时同时检查下游状态、重试放大和 DLQ。
- 日志平台故障时主链路不能阻塞，应本地缓冲或降级。
14. 补充权威资料
- OpenTelemetry logs: https://opentelemetry.io/docs/concepts/signals/logs/ （核对日期：2026-05-09）
- OpenTelemetry GenAI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/ （核对日期：2026-05-09）
15. 主控验收清单
- 是否所有错误日志都有
trace_id、run_id、agent_version。 - 是否所有模型调用都有 token、model、prompt_version。
- 是否所有工具调用都有 tool_name、status、duration。
- 是否安全事件全量记录且不被采样丢弃。
- 是否日志 schema 有 CI 校验。
- 是否明确定义哪些字段禁止写入日志。
- 是否能按租户、版本、工具、风险等级检索。
- 是否配置日志保留周期和访问审计。
- 是否有日志导出失败告警。
- 是否能从日志跳转到 trace。
- 是否对自由文本做 PII 扫描。
- 是否把日志字段变更纳入发布审查。
- 是否有事故时的日志查询模板。
- 是否记录采样率，避免误解统计结果。
- 是否定期抽检日志脱敏效果。