# 12.3 可观测性与调试

## 12.3.1 可观测性的三大支柱与上下文平面

**日志（Logs）** 记录系统运行的详细事件

**指标（Metrics）** 量化的系统状态数据

**追踪（Traces）** 请求在系统中的完整路径

在智能体工程中，这三大支柱需要与 **上下文平面（Context-Plane）** 紧密结合。上下文平面是 Agent Harness 的五个核心平面之一，负责管理：

* **会话状态**（Session State）：智能体执行的阶段和进度
* **记忆管理**（Memory）：长期和短期的信息存储
* **上下文压缩**（Compaction/Summarization）：历史信息的精简与整理
* **工件日志**（Artifact Logs）：可重放的执行记录与检查点

这四个维度共同构成了上下文管理的核心，使得“推理”能够被转化为可追踪、可审计的有类型的行动记录（Typed Actions as Replayable Artifacts）。

## 12.3.2 上下文相关的关键指标

| 指标          | 说明         | 告警阈值（示意）    |
| ----------- | ---------- | ----------- |
| 上下文 Token 数 | 每次请求的上下文大小 | 接近窗口上限      |
| 检索延迟        | 检索操作耗时     | 以 SLO 与基线为准 |
| 检索命中率       | 检索到相关结果的比例 | 以基线与业务验收为准  |
| 压缩率         | 压缩后/压缩前    | 异常波动        |
| 成本/请求       | 单次请求的成本    | 超出预算        |

## 12.3.3 日志设计

### 结构化日志

```json
{
  "timestamp": "2024-03-01T10:00:00Z",
  "request_id": "req_123",
  "stage": "context_build",
  "input_tokens": 500,
  "retrieved_chunks": 5,
  "context_tokens": 2000,
  "duration_ms": 150
}
```

### 日志级别

* **ERROR**：失败的操作
* **WARN**：接近限制、降级处理
* **INFO**：关键流程节点
* **DEBUG**：详细调试信息

## 12.3.4 请求追踪与分布式跟踪标准

完整追踪请求处理流程：

```
request_123
├── 接收请求 [0ms]
├── 查询处理 [10ms]
├── 知识检索 [120ms]
│   ├── 嵌入计算 [30ms]
│   └── 向量搜索 [90ms]
├── 重排序 [50ms]
├── 上下文构建 [20ms]
├── 模型调用 [800ms]
└── 响应返回 [1000ms]
```

### OpenTelemetry 与 W3C Trace Context

为了在分布式智能体系统中进行跨越多个工具边界的追踪，推荐使用 **OpenTelemetry** 标准与 **W3C Trace Context** 规范：

**OpenTelemetry 的核心要素**：

* **Spans**：表示某个操作的时间段和上下文信息，包括开始时间、结束时间、属性、事件和链接
* **Traces**：由多个相关的 Span 组成的完整执行链路，通过唯一的 Trace ID 关联
* **Context Propagation**：跨进程、跨服务传播 Trace ID 和 Span ID，使得分布式调用能被串联起来

**W3C Trace Context** 通过标准化的 HTTP 头（`traceparent` 和 `tracestate`）在服务间传播追踪信息，确保不同的工具和系统能够互操作。

### AI 特定语义约定（OpenInference）

OpenTelemetry 的通用约定需要针对 AI 系统进行扩展。**OpenInference** 项目定义了 AI 特定的语义约定：

* **检索 Spans**：记录向量检索、关键词检索等操作，包括查询、检索文档数、相关性得分
* **工具调用 Spans**：记录每次工具调用的输入参数、执行时间、返回结果
* **提示词与完成度 Spans**：默认记录脱敏后的摘要、哈希、工件引用和 Token 指标；只有在受控的调试/合规流程中才保存完整提示词或响应
* **Token 使用情况**：在 Span 属性中记录输入和输出的 Token 数，便于成本分析

这些语义约定使得观测数据能够被更深入地分析，例如：

* 计算单个请求的总 Token 成本
* 识别哪个检索步骤耗时最长或质量最差
* 关联工具调用失败与模型提示的关系

### 工件日志与可重放性

为了支持可审计性和调试，重要的中间结果应该以 **工件（Artifacts）** 的形式持久化，但默认只保存必要元数据、哈希和脱敏摘要。完整上下文快照应放在单独的加密存储中，并受访问审批、保留期限和删除策略约束。

* **结构化格式**：使用 JSON 或 Protocol Buffers 等机器可读的格式，而不仅仅是文本日志
* **校验和与版本**：记录工件的内容哈希值和版本号，确保可重放时的一致性
* **上下文快照**：在关键决策点保存上下文哈希、版本、脱敏摘要和工件引用；完整内容只在需要复现且合规允许时保存

这些工件可以被用于：

1. **离线调试**：从日志中重现问题场景
2. **AB测试**：使用相同的工件重新运行不同版本的模型或算法，对比结果
3. **合规审计**：证明决策过程的每一步都是可追踪和可验证的

## 12.3.5 上下文快照

保存关键请求的可审计快照。默认不要把原始上下文和模型响应直接写入常规日志：

```python
if should_snapshot(request):
    save_snapshot({
        "request_id": request.id,
        "context_hash": sha256_text(context),
        "response_hash": sha256_text(response),
        "retrieved_doc_ids": [doc["id"] for doc in docs],
        "redaction_status": "redacted",
        "secure_artifact_ref": maybe_store_encrypted_snapshot(context, response),
        "metadata": {...},
    })
```

用于：调试问题、效果分析、回放测试。`secure_artifact_ref` 应指向受控存储，不能把敏感原文复制到普通日志或监控标签中。

## 12.3.6 调试技巧

### 问题定位流程

```mermaid
graph TB
    A["发现问题"] --> B["检查日志"]
    B --> C["定位阶段"]
    C --> D{"问题类型"}
    D --> |"检索"| E["检查检索质量"]
    D --> |"生成"| F["检查上下文"]
    D --> |"性能"| G["检查耗时分布"]
```

图 12-4：问题定位流程

### 常见问题诊断

| 症状    | 可能原因  | 检查点        |
| ----- | ----- | ---------- |
| 答案不相关 | 检索问题  | 检索结果、嵌入质量  |
| 答案不完整 | 上下文不足 | 上下文内容、压缩程度 |
| 幻觉    | 缺乏依据  | 是否有相关知识    |
| 响应慢   | 瓶颈    | 各阶段耗时      |

## 12.3.7 监控仪表盘

建立可视化监控：

* 实时请求量和延迟
* Token 使用分布
* 错误率趋势
* 成本累计

## 12.3.8 告警设置

配置关键告警：

* 错误率超过阈值
* 延迟异常升高
* 成本超出预算
* Token 接近上限

## 12.3.9 常用可观测性工具（示例）

以下列举若干在业界较常见的工具/产品方向（以各工具最新能力与版本为准）：

**LangSmith (LangChain)**

* **特点**：全链路追踪，Prompt 编排，数据集评估。与 LangChain 生态集成度高。
* **适用**：LangChain 用户，需要完整 DevOps 流程的团队。

**LangFuse**

* **特点**：开源，支持自托管，详细的 Trace 和 Score 功能。
* **适用**：注重数据隐私，需要开源解决方案的团队。

**Arize Phoenix**

* **特点**：专注于 LLM Tracing 和 Evaluation，提供 Notebook 环境下的可视化。
* **适用**：数据科学家，需要深入分析 Trace 的场景。

**Weights & Biases (W\&B)**

* **特点**：传统的 ML 实验追踪工具，增加了 Prompts 和 LLM 监控功能。
* **适用**：已有 W\&B 工作流的 ML 团队。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/context_engineering_guide/di-si-bu-fen-gong-cheng-shi-zhan-yu-wei-lai-yan-jin/12_production/12.3_observability.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.