知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 可观测性设计 > 导读:本文从"线上 Agent 说了一句奇怪的结论,你既不知道它调了什么工具、也不知道它当时的思考是什么,只能靠猜"这个典型困境出发,把可观测性三支柱、Trace 数据模型与无侵入插桩、三层关键指标、结构化日志、Agent 专用 Dashboard、告警规则与调试工具逐项讲透,最后给出工程实践与踩坑。适合正在做 Agent 平台运维、或准备 Agent 系统设计面试的同学。 ## 一、先建立全局认知 ### Q:为什么 Agent 的可观测性比传统微服务更难? A:结论先行——因为 Agent 是**自主决策的黑盒**:它多步执行、调用外部工具、每一步都由概率模型生成,出了 Bug 既不报错也不留栈,找不到根因。 传统微服务的失败通常是"异常 + 堆栈",定位路径明确。Agent 的失败则往往是"**没报错,但答案不对**": - 它选了错误的工具,但工具本身返回成功; - 它带着一个过期的中间结果继续推理了 6 步; - 它某一步的工具返回了 5 万 token,导致后面每一步都在烧钱; - 它的思考里有幻觉,但最终输出看起来"很像那么回事"。 所以可观测性的核心目标是:**让 Agent 的每一次决策都留下痕迹,从 LLM 推理到工具调用到最终结果都有完整的链路可追踪**。 ### Q:可观测性三支柱在 Agent 场景下分别回答什么问题? A:结论先行——**日志回答"某个时刻发生了什么"、指标回答"系统整体的趋势和异常"、链路追踪回答"一次请求的完整路径"**,每一支柱在 Agent 场景下都有额外挑战。 | 支柱 | 回答的问题 | Agent 特有的挑战 | |---|---|---| | 日志 Logging | 某个时刻发生了什么 | 需要记录 LLM 的 Thought(思考过程),不只记录工具调用 | | 指标 Metrics | 系统整体的趋势和异常 | 传统 QPS/延迟不够,还需要 step 数、token 消耗、工具成功率 | | 链路追踪 Tracing | 一次请求的完整路径 | Agent Run 是树形结构——一个 Thought 分叉出多个 Tool Call | 关键点解读:请注意"**需要记录 Thought**"这一条——这是 Agent 可观测性与传统可观测性最本质的区别。传统系统里"状态"是明确的,Agent 里"**为什么做这个决定**"本身才是要观测的对象。  *图:可观测性三支柱* ### Q:为什么 Agent 的链路是"树"而不是"链"? A:结论先行——因为一次 Agent Run 会从"一个 Thought"分叉出"多个并发 Tool Call",形成树或 DAG,而不是微服务那种 A→B→C→D 的线性链。  *图:一次 Agent Run 的 Trace 树——思考、工具调用与并行分支* ```text Agent Run (Trace) ├── Step 1 │ ├── Thought: "需要先查财报数据" │ └── Tool Call: search("Q4财报") ← 串行 │ └── Observation: "{营收:1000, ...}" ├── Step 2 │ ├── Thought: "已拿到财务数据,还需要股价信息" │ └── Tool Call: search_stock_price("AAPL") ← 串行 │ └── Observation: "当前股价 $185" ├── Step 3 │ ├── Thought: "数据齐全了,开始分析" │ ├── Tool Call: calculate("毛利率") ← 并行 │ ├── Tool Call: calculate("净利率") ← 并行 │ │ └── Observation: "毛利率 45%" │ │ └── Observation: "净利率 22%" │ └── Final Answer: "分析结果显示..." └── [结束] ``` 这个结构差异带来两个直接后果:**一是 Trace 模型必须有 parent_span_id(否则并行分支无法还原);二是可视化必须支持"一个 step 下挂多个工具"的展示**,否则时间线上会看不到并发关系。  *图:Agent Trace 树形执行链路* ## 二、链路追踪(Tracing) ### Q:Trace 的数据模型怎么设计? A:结论先行——用 **Span(跨度)** 表达每个执行单元,按 `RUN / STEP / LLM_CALL / TOOL_CALL` 四类划分,并用 `parent_span_id` 还原树形结构;LLM 与 Tool 的专有字段都挂在同一个 Span 上。 ```python from dataclasses import dataclass, field from datetime import datetime from enum import Enum import uuid class SpanType(Enum): RUN = "agent_run" # 整个 Run STEP = "agent_step" # 一轮循环 LLM_CALL = "llm_call" # 一次模型调用 TOOL_CALL = "tool_call" # 一次工具调用 @dataclass class Span: span_id: str = field(default_factory=lambda: str(uuid.uuid4())) trace_id: str = "" parent_span_id: str = "" # 还原树形结构的关键 type: SpanType = SpanType.RUN name: str = "" # "search_financial_report" / "gpt-4-thought" start_time: datetime = field(default_factory=datetime.now) end_time: datetime = None duration_ms: int = 0 run_id: str = "" step: int = 0 agent_name: str = "" input_data: dict = field(default_factory=dict) output_data: dict = field(default_factory=dict) # LLM 特有 llm_model: str = "" llm_prompt_tokens: int = 0 llm_completion_tokens: int = 0 llm_total_tokens: int = 0 llm_temperature: float = 0 llm_thought: str = "" # LLM 的思考过程原文 # 工具特有 tool_name: str = "" tool_arguments: dict = field(default_factory=dict) tool_status: str = "" # success / error / timeout / fallback tool_error: str = "" tags: dict = field(default_factory=dict) # 用于聚合查询 def finish(self): self.end_time = datetime.now() self.duration_ms = int((self.end_time - self.start_time).total_seconds() * 1000) ``` 关键点解读: 1. **`trace_id` = `run_id`**,让"一次 Run 的全部 Span"天然聚合在一起; 2. **`tool_status` 有四态**(success / error / timeout / **fallback**)——`fallback`(降级)这一态很关键,因为降级成功在传统监控里会被算成"成功",但它其实是"**能力退化**"信号; 3. **`tags` 是聚合查询的抓手**,例如打上 `{"tenant":"a","task_type":"finance"}` 后就能按租户/任务类型算成功率。 ### Q:怎么采集数据才能"不侵入业务代码"? A:结论先行——用**装饰器插桩**:`trace_step` / `trace_llm_call` / `trace_tool_call` 各包一层,在 `finally` 里收尾并导出 Span。 ```python class AgentTracer: """Agent 链路追踪器,通过装饰器无侵入采集""" def __init__(self, exporter): self.exporter = exporter self._active_trace: dict = {} def start_run(self, run_id: str, task: str) -> Span: span = Span( trace_id=run_id, type=SpanType.RUN, name=f"Agent Run: {task[:50]}", run_id=run_id, input_data={"task": task}, ) self._active_trace[run_id] = span return span def trace_step(self, run_id: str, step: int): """装饰器:追踪一个 Agent step""" def decorator(func): async def wrapper(*args, **kwargs): span = Span( trace_id=run_id, parent_span_id=self._active_trace[run_id].span_id, # 挂到 Run 下 type=SpanType.STEP, name=f"Step {step}", run_id=run_id, step=step, ) try: result = await func(*args, **kwargs) span.output_data = {"result": str(result)[:500]} # 截断,防爆存储 return result except Exception as e: span.output_data = {"error": str(e)} raise finally: span.finish() self.exporter.export(span) # 无论如何都导出 return wrapper return decorator ``` 关键点解读:三个设计取舍值得注意: 1. **`finally` 里导出**——异常路径也必须留痕,否则"失败的那次调用"恰好是唯一没被记录的那次; 2. **`str(result)[:500]` 截断**——工具输出可能几万字符,全量写 Trace 会直接压垮存储;完整内容应该走"采样 + 对象存储"; 3. **装饰器而非手写插桩**——业务代码只加一行 `@tracer.trace_tool_call(...)`,可观测性成为横切能力,而不是侵入逻辑。 ## 三、关键指标(Metrics) ### Q:Agent 需要哪些指标?和传统指标的差别在哪? A:结论先行——分三层:**业务级(成功率、时长、人工介入率、满意度)、LLM 级(调用次数、token、延迟分位、错误率)、工具级(单工具成功率、延迟、调用量、降级率)**;差别在于"token"和"step"是传统监控里没有的核心成本与复杂度指标。 **业务级指标** | 指标 | 含义 | 告警阈值建议 | |---|---|---| | `agent.task.success_rate` | 任务完成成功率 | < 90% 告警 | | `agent.task.avg_duration_sec` | 平均任务完成时长 | 环比涨 > 50% 告警 | | `agent.task.human_escalation_rate` | 需要人工介入的比例 | > 20% 检查工具质量 | | `agent.user.satisfaction` | 用户满意度(拇指向上/向下) | < 80% 告警 | **LLM 级指标**:`calls_per_task`(每任务平均 LLM 调用次数)、`tokens_per_task`(每任务平均 token 消耗)、`latency_p50/p95/p99`(延迟分位数)、`error_rate`(API 限流、超时、内容过滤)。 **工具级指标**:`agent.tool.{name}.success_rate`、`agent.tool.{name}.latency_p50/p95`、`agent.tool.{name}.call_count`、`agent.tool.fallback_rate`。 关键点解读:`human_escalation_rate > 20%` 这条阈值的语义很特别——它**不指向 Agent 本身,而是指向工具质量**。人工介入率高,往往说明工具给的信息不足以让 Agent 自己决策,这是把"可观测性"用成"诊断工具"的典型例子。 ### Q:指标采集实现上要注意什么? A:结论先行——**用 Counter / Histogram / Gauge 三种类型分别表达"计数、分布、瞬时值",并且 bucket(分桶)必须按 Agent 的真实量级来设**。 ```python from prometheus_client import Counter, Histogram, Gauge class AgentMetrics: def __init__(self): # 业务指标 self.task_total = Counter('agent_task_total', 'Total agent tasks', ['status']) self.task_duration = Histogram( 'agent_task_duration_seconds', 'Task duration', buckets=[5, 15, 30, 60, 120, 300, 600]) # LLM 指标 self.llm_calls = Counter('agent_llm_calls_total', 'LLM call count', ['model']) self.llm_tokens = Counter('agent_llm_tokens_total', 'Token usage', ['model', 'type']) self.llm_latency = Histogram( 'agent_llm_latency_seconds', 'LLM call latency', ['model'], buckets=[0.5, 1, 2, 5, 10, 30, 60]) # 工具指标 self.tool_calls = Counter('agent_tool_calls_total', 'Tool call count', ['tool_name', 'status']) self.tool_latency = Histogram( 'agent_tool_latency_seconds', 'Tool call latency', ['tool_name'], buckets=[0.1, 0.5, 1, 2, 5, 10, 30]) # Agent 状态 self.active_runs = Gauge('agent_runs_active', 'Currently running agent tasks') self.current_step = Gauge('agent_current_step', 'Current step count', ['run_id']) ``` 关键点解读:三组分桶的差别体现了"**不同环节的时间尺度完全不同**"——工具延迟从 0.1s 起分桶,LLM 延迟从 0.5s 起,任务总时长从 5s 起。如果三组都用默认分桶,P95 会算得毫无意义。另外 **`current_step` 做成带 `run_id` 标签的 Gauge**,这是"检测 Run 卡死"的基础(见后文告警规则)。 ## 四、日志规范 ### Q:Agent 的日志为什么必须结构化? A:结论先行——因为排查时需要**按 run_id 过滤、按 step 排序、按 tool_name 聚合**,纯文本日志做不到。 ```python import structlog logger = structlog.get_logger() # ❌ 糟糕的日志:只有一行字符串,无法结构化检索 logger.info(f"Agent step {step}: calling tool {tool_name} with args {args}") # ✅ 结构化日志:字段化,可过滤、可聚合 logger.info("agent.step.tool_call", run_id=run_id, step=step, tool_name=tool_name, arguments=args, call_id=call_id, timestamp=datetime.now().isoformat(), ) ``` 关键点解读:`call_id` 这个字段常被漏掉,但它是**把日志与 Trace、与工具服务端日志串起来**的钥匙。有了它,"Agent 说我调了 search,但 search 服务说没收到"这类跨系统问题才能在几分钟内定位。 ### Q:日志级别怎么划分? A:结论先行——**INFO 记主干、WARNING 记退化、ERROR 记失败、DEBUG 记细节(Thought 全文与工具完整返回)**。 | 级别 | 场景 | |---|---| | INFO | Agent Run 开始/结束、每步开始、工具调用和结果 | | WARNING | 工具降级、重试、Token 使用超过 80% | | ERROR | 工具失败(已达最大重试)、LLM 返回格式解析失败 | | DEBUG | LLM 完整 Thought 文本、工具完整返回数据 | 关键点解读:**"Token 使用超过 80% 记 WARNING"** 是一个非常有价值的设计——它把"上下文即将耗尽的预警"做成日志事件。等到真正超限报错时才记录,已经太晚了。 ## 五、可视化:Agent 专用 Dashboard ### Q:为什么传统 Dashboard 不够用? A:结论先行——传统 Dashboard 关注 QPS 曲线、延迟热力图,而 Agent 需要看到**"一次 Run 内部的时间构成"与"token 随步数的变化"**,这是完全不同的可视化维度。 **Run 时间线视图**——按 step 展开,显示每步内部 LLM 思考与工具调用的耗时占比:  *图:一次 Run 的 Trace 结构:Step 与 Span 耗时明细* ```text ┌─────────────────────────────────────────────────────────────┐ │ Run: run_abc123 | 任务: 分析 Q4 财报 | 状态: 进行中 │ ├─────────────────────────────────────────────────────────────┤ │ Step 1 ████████████████ 3.2s │ │ LLM Think 1.5s │ │ Tool: search_financial 1.7s │ │ │ │ Step 2 ████████████ 2.1s │ │ LLM Think 1.2s │ │ Tool: calculate_gross_margin 0.9s │ │ │ │ Step 3 ████████████████████████ 4.5s │ │ LLM Think 2.1s │ │ Tool: search_news (并行) 1.1s │ │ Tool: get_stock_price (并行) 1.3s │ │ LLM Final Answer 临时 │ └─────────────────────────────────────────────────────────────┘ ``` **工具调用热力图**——按工具维度展示成功率、延迟、调用量的时间趋势,快速定位是哪个工具出了问题。 **Token 消耗曲线**——看每步 token 消耗趋势,用于发现"某步突然 token 暴涨"。这个视图的价值在于它直接指向一类高频事故:**某一步的工具返回了超大数据,导致后续每一步都带着这份巨大上下文,成本被放大 N 倍**。光看总量曲线看不出来,必须看"每步"曲线。  *图:Agent Run 时间线* ## 六、告警规则 ### Q:Agent 的告警该怎么设计? A:结论先行——覆盖五类:**成功率下降、工具异常率飙升、Token 消耗异常、任务堆积、Run 长时间无进展**;每条都要配 `for` 窗口避免抖动误报。 ```yaml groups: - name: agent_alerts rules: # 1. 任务成功率下降 - alert: AgentTaskSuccessRateLow expr: rate(agent_task_total{status="success"}[5m]) / rate(agent_task_total[5m]) < 0.85 for: 10m annotations: summary: "Agent 任务成功率低于 85%" # 2. 工具异常率飙升 - alert: AgentToolErrorRateHigh expr: | rate(agent_tool_calls_total{status="error"}[5m]) / rate(agent_tool_calls_total[5m]) > 0.05 for: 5m annotations: summary: "工具 {{ $labels.tool_name }} 错误率超过 5%" # 3. Token 消耗异常 - alert: AgentTokenSpike expr: rate(agent_llm_tokens_total[5m]) > rate(agent_llm_tokens_total[1h]) * 3 for: 5m annotations: summary: "Agent Token 消耗突然飙升 3 倍" # 4. 任务堆积 - alert: AgentTaskQueueBacklog expr: agent_runs_active > 50 for: 5m annotations: summary: "活跃 Agent Run 超过 50,可能存在堆积" # 5. Run 长时间无进展 - alert: AgentRunStuck expr: agent_current_step > 0 and rate(agent_current_step[10m]) == 0 for: 10m annotations: summary: "Run {{ $labels.run_id }} 在 10 分钟内无进展,可能卡死" ``` 关键点解读: 1. **"成功率 < 0.85 且持续 10m"而不是瞬时值**——Agent 请求量通常比 Web 请求低一到两个数量级,瞬间抖动很容易击穿瞬时阈值; 2. **Token 告警用"5 分钟速率 vs 1 小时速率"的比值**(> 3 倍)而不是绝对阈值——绝对阈值会被业务量增长自然触发,比值才能捕捉"异常放大"; 3. **`AgentRunStuck` 这条最特别**:它用"step 计数在 10 分钟内没有变化"来判断卡死。Agent 卡死往往表现为"进程活着、没有报错、也不推进",只有这类**基于进展速率的告警**才能发现。 ## 七、调试工具 ### Q:线上出问题后,最常用的排障手段是什么? A:结论先行——两个:**Run 回放(按 trace_id 拉出全部 Span 按时间顺序重演)和 Trace 搜索过滤(按 run_id / tool_name / step / status / 时间范围 / token 区间检索)**。 ```python class AgentRunReplayer: """根据 Trace 数据回放一次 Agent Run,用于调试""" def replay(self, trace_id: str): spans = self.trace_store.query(trace_id=trace_id, order_by="start_time") for span in spans: if span.type == SpanType.LLM_CALL: print(f"[Step {span.step}] Thought: {span.llm_thought}") print(f" Tokens: {span.llm_total_tokens} " f"(in={span.llm_prompt_tokens}, out={span.llm_completion_tokens})") elif span.type == SpanType.TOOL_CALL: status_icon = "✅" if span.tool_status == "success" else "❌" print(f" {status_icon} Tool: {span.tool_name}({span.tool_arguments}) " f"→ {span.tool_status} ({span.duration_ms}ms)") if span.tool_error: print(f" Error: {span.tool_error}") elif span.type == SpanType.STEP: print(f"\n{'='*60}") print(f"Step {span.step} — {span.duration_ms}ms") ``` 关键点解读:回放的关键是**把 LLM 的 Thought 和工具的实际参数/结果放在一起按时间顺序展示**。因为 Agent 出错的典型形态是"**Thought 说得对,但工具参数传错了**"或者"**工具结果对,但 Thought 误读了**"——必须两者对照才能定位。 搜索与过滤则是最常用的入口:按 run_id(精确定位)、tool_name(某工具全体异常)、status(失败集合)、时间范围(事故窗口)、token_range(异常放大的 Run)多维组合检索。  *图:Agent Run 回放* ## 八、技术选型 ### Q:这一套用什么技术栈落地? A:结论先行——**Trace 用 OpenTelemetry SDK + Jaeger/SigNoz,指标用 Prometheus + Grafana,日志用 structlog + Loki/ELK,LLM 专用视图可考虑 LangSmith / Weights & Biases**。 | 层面 | 推荐方案 | 备注 | |---|---|---| | Trace 采集 | OpenTelemetry SDK | 标准协议,兼容 Jaeger/Zipkin | | Trace 存储 | Jaeger / SigNoz | Jaeger 成熟,SigNoz 作为开源替代 | | 指标 | Prometheus + Grafana | 标准组合,社区庞大 | | 日志 | structlog(Python)→ Loki / ELK | 结构化日志最佳实践 | | LLM 专用 | LangSmith / Weights & Biases | 自动采集 LLM prompt/completion,有 Agent 专用视图 | 关键点解读:**优先选 OpenTelemetry 这类标准协议**,而不是框架自带的私有时序格式。原因很实际:Agent 系统通常和业务系统共用一套观测基础设施,私有时序格式会导致"Agent 的 Trace 和业务 Trace 断成两截",跨系统排障时最痛。 ## 九、采集成本、采样与数据治理 ### Q:全量采集 Trace 的成本会不会失控? A:结论先行——会。一次 Agent Run 可能产生几十个 Span 和成千上万条 token 级事件,**全量留存等于用业务成本换排障能力**,必须做分层:结构留全、内容采样。  *图:结构层、内容层、结论层的保留策略差异* ```text 三层数据的分工: 结构层(谁调谁、耗时、状态、token 计数) → 体量小、价值高 → 100% 保留 内容层(prompt / completion / 工具完整返回) → 体量大(可能单条几万字符)→ 按采样率保留 + 超长截断 结论层(最终输出、用户反馈、错误码) → 体量小、价值高 → 100% 保留 ``` 关键点解读:这个分层回答了一个常见争论——"Trace 要不要存全量 prompt"。答案是:**不要,但要存全量"结构"**。因为排查问题时,90% 的情况只需要知道"第 3 步调了 search、参数里 company=AAPL、返回成功、耗时 1.2s";只有剩下的 10%(怀疑模型理解错、怀疑注入、怀疑幻觉)才需要看完整内容,而这些场景恰恰可以用"按需提升采样率"来兜。 ### Q:采样怎么设计才不会漏掉关键故障? A:结论先行——用**非对称采样**:失败全采、成功按比例采,并且额外把"慢 Run"和"被用户负反馈的 Run"也全采。  *图:五条采样规则:失败、差评、慢、拦截全量* ```text 采样规则(按优先级): 1. Run 最终失败(error / timeout / max_steps_exceeded)→ 100% 采样 2. Run 被用户点"踩"或触发人工介入 → 100% 采样 3. Run 耗时超过 P95 基线 → 100% 采样 4. Run 触发安全拦截(含越狱、注入、PII) → 100% 采样 5. 其余成功 Run → 按 1%~10% 比例采样 ``` 关键点解读:**采样的决策时机比采样比例更重要**。不能在"请求入口"就随机决定采不采——因为入口处根本不知道这个 Run 会不会失败、会不会慢、用户会不会给差评。正确的做法是:**先全量把结构事件写进内存缓冲,在 Run 结束时按最终状态决定"是否把内容层落盘"**。 这是一个很实用的取舍:结构层本来就要 100% 落盘,内容层延迟到 Run 结束再决定,代价只是"需要在内存里多留一份内容到 Run 结束"(对单次 Run 而言体量可控),收益是"关键故障 100% 有完整证据"。 ### Q:数据保留期怎么定? A:结论先行——按价值衰减分层保留:**热数据(可全文检索)7 天左右、温数据(结构 + 摘要)30~90 天、冷数据(结构 + 聚合指标)1 年以上**。 ```text 热数据(7 天):完整 Trace(含采样内容),支持全文检索与 Run 回放 温数据(30~90 天):Span 结构 + 摘要字段,支持按 Run 检索与聚合 冷数据(1 年+):聚合指标 + 失败 Run 的结构骨架,仅用于趋势分析与审计 ``` 关键点解读:保留期设计的依据是"**问题从发现到排查的时间差**"。绝大多数线上问题在 7 天内被排查完,所以热数据 7 天足够;而"某类失败是不是在近三个月逐渐增多"这种趋势问题,需要的只是聚合指标,不需要完整内容。至于审计需求("半年前那次决策是怎么做的"),往往有独立的合规留存要求,需要结合所在行业的法规确认保留期限。 ### Q:可观测性的价值怎么形成闭环? A:结论先行——要有明确链路:**指标发现异常 → Trace 定位到具体 Run → 回放定位到具体 step → 归因 → 优化 → 离线评测验证 → 回到指标**。  *图:指标→Trace→Span 逐层下钻定位慢查询* ```text 指标层:任务成功率从 92% 掉到 85% │(哪个维度掉得多?)→ tool_name="search_financial" 错误率 5% → 18% ▼ Trace 层:筛出该工具失败的 Run 集合 │(失败长什么样?)→ 全部是 timeout,耗时都 > 30s ▼ Span 层:看 Run 回放 → 第 3 步 search 耗时 32s,重试后仍超时 ▼ 归因:工具服务侧限流 or 数据量增长导致慢查询 ▼ 优化:加缓存 / 调超时 / 补降级链 ▼ 离线评测:回归验证成功率与工具准确率未退化 ▼ 回到指标:观察成功率是否回升 ``` 关键点解读:这个闭环里最容易断的一环是"**指标 → Run 集合**"。如果 Dashboard 只显示"成功率 85%"却点不进去看具体是哪些 Run,那诊断就断在这里。所以可观测性设计从一开始就要保证**每个指标都能下钻到原始 Trace**——这也是为什么 `tags` 字段(租户、任务类型、工具名)必须和指标维度保持一致:**指标的分组维度和 Trace 的标签维度对不上,就永远下钻不下去**。 ### Q:多 Agent / 多租户场景有什么额外要求? A:结论先行——两条:**Trace 要能跨服务串联(trace_id 透传)**,以及 **tags 必须带租户与任务类型维度**。 - **跨服务串联**:多 Agent 系统里"一个 Run 跨多个 Worker/服务",如果每个服务各自生成 trace_id,排查时就只能看到一堆孤立的片段。做法是把根 Span 的 `trace_id`(即 run_id)通过消息信封一路透传(这也解释了消息协议里为什么必须有 `correlation_id`)。 - **维度标签**:多租户场景下"整体成功率 90%"这个数字毫无意义——A 租户 99%、B 租户 60% 也会平均成 90%。必须用 `tenant` 标签分组,才能发现"某个租户的工具配置有问题"。 ## 十、工程实践与踩坑 ### Q:落地 Agent 可观测性最容易踩哪些坑? A:结论先行——六个高频坑:**只记录工具调用不记录 Thought、全量写 Trace 压垮存储、不做 token 采样与截断、Span 层级挂错、告警阈值照搬 Web 指标、以及把 Thought 明文落盘带来的隐私风险**。 1. **只记录工具调用、不记录 Thought。** 结果是"知道它做了什么,但不知道为什么",排障效率损失一半以上。Thought 可以在 DEBUG 级别或按采样率记录,但必须存在。 2. **全量写 Trace 压垮存储。** 工具返回可能几万字符,`input_data`/`output_data` 必须截断;大体量内容走对象存储 + 引用 id。 3. **不做采样。** 高流量下必须按比例采样(错误 Run 全采样 + 成功 Run 按比例采样),否则可观测性成本会超过业务成本。 4. **Span 的 parent 挂错。** 并行工具调用如果都挂到 Run 而不是当前 Step 下,时间线就还原不出"一个 Step 并发两个 Tool"的结构。 5. **告警阈值照搬 Web 指标。** Agent 请求量低、单次耗时长(分钟级),用 Web 的"QPS + P99 延迟"阈值会疯狂误报。 6. **Thought 明文落盘带来隐私与合规风险。** Thought 里可能包含用户原始输入、检索到的敏感数据。日志与 Trace 存储必须做脱敏,并明确访问权限(合规要求需结合所在地区法规确认)。 ### Q:可观测性和成本的边界怎么划? A:结论先行——**用"分层记录 + 分级采样"控制成本**:Trace 记结构(谁调谁、耗时、状态),大体量内容记引用;错误 Run 全采样,成功 Run 采样;DEBUG 级日志默认关闭、排障时按 run_id 临时开启。 这套策略的本质是承认一个现实:**可观测性的边际价值递减很快**。100% 的 Trace 覆盖率对定位问题帮助巨大,但从 10% 提到 100% 成功 Run 的采样率,收益远小于成本。相反,"**所有失败 Run 必须 100% 留痕**"这条约束的价值极高,因为它直接对应"下一次同类故障能不能 5 分钟定位"。 ### Q:告警太多会怎样?怎么避免? A:结论先行——会导致"告警疲劳",最后所有人都无视告警。Agent 系统尤其容易踩这个坑,因为它的指标天然抖动大(同一个任务,模型每次的步数、耗时都可能不同,成功率也容易出现小幅波动)。 对策有四条: 1. **只对"可行动"的指标告警**。如果一个告警响了之后没人知道该做什么,它就不该存在——它只是在消耗注意力。 2. **按维度收敛**。工具错误率要按 `tool_name` 分组,只报"异常的那个工具",而不是笼统报"整体错误率高";否则值班同学每次都要自己去猜是哪个工具。 3. **分级通知**。先 Warning(进看板 / 群消息),再 Critical(呼叫值班)。不要所有告警都直接呼叫,否则一线会很快学会"忽略"。 4. **定期复盘**。统计"过去一个月有多少告警真的被处理过",把长期无人处理的告警降级或删掉。**没人处理的告警不是"安全垫",是"噪声源"。** ### Q:Trace 里的隐私边界怎么把握? A:结论先行——Trace 是"给内部人看的、长期留存的、还可能同步到第三方观测平台的数据",所以它的隐私要求不比业务日志低,甚至更高。 三条具体要求: 1. **内容层默认脱敏**:prompt / completion / 工具返回里的手机号、身份证、邮箱、银行卡必须在落盘前打码; 2. **敏感字段黑名单硬拦**:`password` / `token` / `secret` / `api_key` 这类 key 直接不落盘,不依赖"检测器识别"; 3. **访问权限受控**:Trace 查询界面的访问权限必须与它能暴露的敏感数据级别匹配——不是所有研发都应该能看到全量 prompt。 这里有一个现实矛盾:**排障需要看原文,合规要求脱敏**。常见的折中是"存脱敏版 + 保留原文的加密引用":需要时按审批解密查看单条,并把"谁在什么时候解密看了哪条"记入审计。这样既保住了排障能力,又留下了可追溯的访问痕迹。 ### Q:怎么衡量"做可观测性"这件事本身的 ROI? A:结论先行——用两个可测指标:**MTTR(平均故障恢复时间)** 和 **同类故障复发率**。 - **MTTR**:有了完整 Trace 后,"从发现异常到定位根因"的时间是否显著下降。这是可观测性最直接的收益; - **复发率**:同一个根因的故障是否还会出现第二次。如果会,说明可观测性只做到了"发现"、没做到"闭环修复"。 一句话概括:可观测性不该被当成"监控成本",而应被当成"**排障效率投资**"来衡量。如果做了半年、MTTR 没降、复发率也没降,那大概率是"采集了很多数据,但没有形成从指标到 Trace 到修复的闭环"。 ### Q:能不能直接复用业务系统的 SLO / 告警体系? A:结论先行——可以复用**基础设施**(Prometheus / Grafana / Jaeger 这套采集与展示栈),但不能复用**指标语义与阈值**。 原因在于两类系统的"健康定义"完全不同: - 业务系统的健康是"请求成功且快"——所以 QPS、错误率、P99 延迟就是全部; - Agent 系统的健康是"**任务真的完成了,且过程是合理的**"——一个 Run 可以 HTTP 200、延迟正常,但工具选错、步数暴涨、结论错误。 所以复用基础设施能省一大笔工程投入,但必须为 Agent 补充自己的指标维度(step、token、tool 维度、fallback)与自己的阈值经验(低 QPS、高单次耗时、指标抖动大)。**"共用管道、各管语义"是这里最划算的取舍。** ### Q:可观测性和离线评测体系怎么配合? A:结论先行——两者是同一个闭环的两端:**可观测性负责在真实流量里"发现问题",评测负责在可控环境里"验证修复"**。 - 可观测性的产出物:失败的 Run、被用户点负反馈的 Run、异常慢的 Run、触发安全拦截的 Run——这些都是**真实分布下的 badcase**; - 这些 badcase 恰好是评测数据集最优质的候选来源(比人工凭空构造更贴近真实); - 修复后用离线评测确认"该 badcase 已修好,且没有引入别的回归"; - 再上线观察指标是否回升。 一句话:**没有可观测性,评测集只能靠人工拍脑袋构造;没有评测,可观测性只能告诉你"变差了",却无法证明"已经修好了"。** ## 小结 - Agent 的可观测性难在"**黑盒自主决策**",目标是从 LLM 推理到工具调用到最终结果全程留痕; - 三支柱各司其职:日志(时刻)、指标(趋势)、Tracing(链路),且都需为 Agent 扩展字段(Thought、step、token、fallback); - Trace 是**树不是链**,靠 `parent_span_id` 还原;Span 分 RUN / STEP / LLM_CALL / TOOL_CALL 四类,`tool_status` 必须包含 `fallback`; - 采集靠装饰器无侵入插桩,`finally` 里导出、输出截断; - 指标分业务/LLM/工具三层,分桶要按各自时间尺度设置;`token` 与 `step` 是 Agent 特有的核心指标; - 日志必须结构化,`call_id` 是打通跨系统链路的钥匙;WARNING 里要有"token 使用超 80%"这类提前预警; - Dashboard 要看"Run 时间线"和"每步 token 曲线",后者能定位"某步工具返回过大导致后续成本放大"; - 告警要有 5 类(成功率、工具错误率、token 飙升、堆积、卡死),配 `for` 窗口; - 排障入口是 Run 回放 + 多维 Trace 搜索;技术选型优先 OpenTelemetry 标准协议; - 成本靠**分层留存(结构全留、内容采样)与非对称采样(失败/慢/负反馈全采)**控制;数据按热/温/冷分层保留; - 可观测性必须能闭环:**指标能下钻到 Trace,Trace 能回放到 step**,否则只能看到"变差了"而看不到"为什么差"。 ## 思考题 1. `AgentRunStuck` 告警基于"step 计数 10 分钟无变化",但如果某个工具本身就要跑 15 分钟(例如大规模数据导出),这条告警会持续误报。你会怎么改进这个规则? 2. 记录 LLM 的 Thought 对排障价值极高,但它可能包含用户敏感数据。请设计一个既能排障又能合规的方案,并说明你在哪些环节做了取舍。 3. 如果采样率设为 10%,恰好那次出故障的 Run 没被采样怎么办?你会用什么策略保证"失败 Run 必然留痕"? 4. 工具级指标里的 `fallback_rate`(降级触发率)上升,但 `success_rate` 没变。这说明什么?你会怎么把这两条信息结合起来判断影响? 5. 假设公司要求"Agent 的每一次线上决策都可被审计复现",这对你的可观测性架构(存储、采样、数据保留期、Thought 记录)会提出哪些新约束?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入