观测、Trace 和日志

{
  "traceId": "abc-123-def",
  "spans": [
    {
      "spanId": "span-1",
      "name": "receive_request",
      "startTime": "2026-06-12T10:00:00Z",
      "endTime": "2026-06-12T10:00:01Z",
      "status": "ok"
    },
    {
      "spanId": "span-2",
      "parentId": "span-1",
      "name": "call_llm",
      "startTime": "2026-06-12T10:00:01Z",
      "endTime": "2026-06-12T10:00:05Z",
      "status": "ok",
      "input": {"prompt": "..."},
      "output": {"text": "..."}
    },
    {
      "spanId": "span-3",
      "parentId": "span-1",
      "name": "query_database",
      "startTime": "2026-06-12T10:00:05Z",
      "endTime": "2026-06-12T10:00:06Z",
      "status": "error",
      "error": "connection timeout"
    }
  ]
}

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

@tracer.start_as_current_span("call_llm")
def call_llm(prompt: str) -> str:
    span = trace.get_current_span()
    span.set_attribute("prompt.length", len(prompt))

    # 调用 LLM
    result = llm_client.complete(prompt)

    span.set_attribute("result.length", len(result))
    span.set_attribute("model", "gpt-4")
    return result

# 错误复盘报告

## 问题现象
用户在查询订单状态时，Agent 返回了错误的订单信息。

## Trace 分析
- Trace ID: abc-123-def
- 问题 Span: query_order (span-3)
- 错误类型: 查询参数错误

## 根因
Agent 在提取订单号时，把用户输入的"订单 12345"解析成了"1234"，漏掉了最后一位。
原因是 prompt 里对订单号格式的描述不够明确。

## 修复措施
1. 更新 prompt，明确订单号是 5 位数字
2. 增加参数校验，不符合格式的要追问用户
3. 把这类错误加入测试集，防止复发

## 跟进
- 负责人: @张三
- 完成时间: 2026-06-15

我把 Agent 的可观测性设计成四层：

第一层是追踪层，用 Trace 记录每次请求的完整执行流程，从入口到出口，每个步骤都是一个 Span，记录输入输出和状态。

第二层是日志层，在 Span 里记录详细的业务日志、调试日志、错误日志和审计日志。所有日志都带上 Trace ID 和 Span ID，方便关联查询。

第三层是复盘层，出了问题，通过 Trace 快速定位到出问题的 Span，看它的输入输出，分析根因。写复盘报告，把失败案例加入测试集，更新规则和护栏。

第四层是审计层，记录所有敏感操作和关键决策，不可篡改，长期保留，满足合规要求。

这样做的目的是让 Agent 系统可调试、可审计、可改进。出了问题能复盘根因，能沉淀经验，能持续优化，而不是每次都靠猜。