接口返回 200 OK，只说明请求完成了，不能证明任务做对了
AI 应用会同时改变提示词、模型、检索证据、工具状态和外部世界。真正的可观测性不是保存更多正文，而是用同一 Trace 串起版本、输入边界、执行步骤、业务终态和评测证据；再把失败变成可回放样本，把结果未知变成可对账状态。
一次请求要能沿 Prompt、Context、Model、Tool 走到真实结果
Trace（分布式追踪）是一棵调用树，Span（工作片段）是树上的节点。应用通过 SDK（Software Development Kit，软件开发工具包）创建 Span；根 Span 表示一次用户回合或工作流，子 Span 表示检索、重排、LLM（Large Language Model，大语言模型）、工具、护栏和评测。网页、网关、应用、模型代理与工具服务之间传播同一个 W3C（World Wide Web Consortium，万维网联盟）Trace Context，才能把“回答错了”拆成可定位步骤。
传播层：W3C Trace Context 只负责“这是同一条链”
traceparent 携带 Trace ID、Parent ID 和采样标志，tracestate 携带厂商状态。它们不应包含个人可识别信息，也不是身份凭证或授权结果；穿越不可信边界时可以重新起 Trace，并用受控关联字段连接。
信号层：OpenTelemetry 统一 Trace、Metric 与 Log 的传输模型
OpenTelemetry（OTel，开放遥测）提供 SDK、OTLP（OpenTelemetry Protocol，开放遥测协议）和 Collector。它解决跨语言采集与传输，不自动替你定义“任务成功”“引用正确”或“退款已发生”。Tail Sampling 只处理 Trace，不是 Metric 与 Log 的共同漏斗。
语义层：OpenInference 与 OTel GenAI 不是同一份稳定词典
OpenInference 是建立在 OTel 之上的 AI 语义层，定义 Agent、LLM、Tool、Retriever、Reranker、Guardrail、Evaluator 等 Span Kind。OTel GenAI 独立仓库则定义 gen_ai.* 等字段。截至 2026-07-16，后者仍标为 Development、无正式 release，仓库的 Schema URL 还是 TODO，并依赖 core semantic conventions v1.43.0；生产系统应 pin commit/版本、保存字段映射，不能静默混用命名空间。
业务层：为真实终态补稳定字段
平台通用字段之外，至少需要 prompt_version、index_snapshot、tool_schema_version、release_id、operation_id 与 outcome_status。自定义字段要有 owner、类型、保留期、敏感级别和迁移规则。
Prompt / Model Span：模板、请求与实际响应分开
记录模板 ID/version、内容哈希、请求模型、实际响应模型、采样参数、输入/输出/推理 Token、Provider request ID、完成原因和 streaming 标志。正文属于 opt-in 敏感字段；不要为了调试把整段对话默认复制到观测平台。
Context Span：记录证据身份，不只记录“检索成功”
保存 query hash、Embedding 与 Reranker 版本、index snapshot、过滤策略、top-k、document/chunk IDs、分数与拒绝原因。这样才能区分没召回、召回旧文档、重排错误和模型忽略证据。
Tool Span：用收据证明动作，而不是用模型文字证明
记录 Tool 名称/版本、tool_call_id、参数 schema、脱敏摘要、timeout、retry、HTTP（Hypertext Transfer Protocol，超文本传输协议）/业务状态、稳定 operation_id、intent_hash 和 Provider receipt。API（Application Programming Interface，应用程序接口）返回前进程崩溃时，模型文字不能替代远端收据。
Evaluator Span：分数也必须可复现
保存 evaluator 类型、rubric version、Judge 模型/提示词、校准集版本、阈值、原始维度分和人工复核结果。只有“0.83”而没有裁判版本，历史曲线没有可比性。
先沿证据链分诊，不要直接把问题叫“幻觉”
Retriever 未召回政策，是查询或索引问题；召回旧版本，是 snapshot/过滤问题；正确文档排第一但回答仍编造，是 Prompt、模型或引用约束问题；Tool 已执行而回答声称失败，则要查收据与业务终态。四种问题需要四种修复。
Metric 看分布，Trace 看因果，Log/Eval 看受限细节
AI 应用的核心口径是“每个合格任务花多少钱、多久、为什么失败”。Metric label 只放模型族、发布版本、route、任务类型和 status class 等有界维度；tenant ID、prompt hash、document ID、tool_call_id 等高基数字段留在 Trace/Log。Exemplar（样例点）可携带 Trace/Span ID，但只有目标 Trace 实际被保留且后端可查询时，聚合指标才能成功反查具体调用。
OpenTelemetry Metrics SDK 把每组唯一属性组合视为一条时间序列。当匹配的 View 未设置 aggregation_cardinality_limit，且 MetricReader 未设置默认 cardinality limit 时，规范建议的默认上限是每个 instrument、每个 collection cycle 输出 2,000 个数据点；溢出会汇入 otel.metric.overflow=true。把用户 ID 或 Prompt ID 塞进 label，不是“更细”，而是在制造无界时间序列和费用风险。
质量
任务成功率、正确性、Groundedness（有据性）、引用支持、安全、格式、用户纠正、人工升级；每项写清可验证终态和分母。
延迟
E2E（End-to-End，端到端）、TTFT（Time to First Token，首 Token 时间）、TPOT（Time per Output Token，每输出 Token 时间）、排队、检索和 Tool duration。Provider 只暴露首 chunk 时要明确不是严格首 Token。
成本
输入、输出、推理 Token，Embedding、Rerank、Tool、重试、缓存写入和人工复核；最终归到合格成功任务，而不是只算单次模型调用。
缓存
Provider Prompt Cache 与 vLLM 的 KV（Key-Value，键值）block cache 都按精确 Token 前缀复用计算，但字段、分母和淘汰范围要分开。OpenAI 的 cached_tokens 对全部请求可见，cache_write_tokens 当前仅由 GPT-5.6 及以后模型族报告；命中仍会生成新输出。
语义响应缓存
按相似度复用完整答案或 Tool 结果，分母是 eligible queries；除命中率外必须看阈值、陈旧答案率、错误复用率和权限隔离，不能与 KV Cache 合并成一个命中率。
错误与恢复
Provider error、timeout、rate limit、schema mismatch、业务失败、guardrail block、parse failure，以及 retry、resume、unknown 对账、重复副作用拦截和最终恢复耗时。
“缓存命中率 70%”要写清是请求、完整块还是命中 Token；“成功率 99%”要写清空答案、超时后迟到、业务 Tool 失败和用户取消是否进入分母；P95（第 95 百分位）/ P99（第 99 百分位）还要固定窗口、时区、任务类型和是否只统计成功请求。
便宜模型重试三次，可能比贵模型一次成功更贵
先定义合格任务和成功终态，再把同一 Trace 的模型、检索、工具、缓存写入、重试与人工成本求和。只比较单次 LLM 调用费用，会奖励失败、短路和不完整答案。
先用真实结果和确定性规则，再让模型裁判模糊维度
Online Evaluation（在线评测）不是给每条答案塞一个万能分，而是把任务结果、可执行检查、领域 Rubric（评分规约）、用户行为和专家抽检对齐到同一 Trace。客服关注政策正确与解决率，代码 Agent 关注测试和仓库终态，搜索摘要关注主张与引用支持。
第一层：业务终态与确定性 Grader
订单是否真的更新、单元测试是否通过、SQL 是否返回预期行、JSON Schema 是否满足、引用是否存在、权限检查是否放行。能用执行器或数据库判断，就不要先让 LLM 猜。
第二层：领域 Rubric 与 LLM-as-a-Judge
LLM-as-a-Judge（用大模型作裁判）适合风格、完整性、解释质量等模糊维度，但要逐维评分、给正反例、允许“不确定/送人工”，并保存 Judge 模型、提示词与输出解析版本。
第三层：用户行为与专家校准
追问、改写、放弃、复制、人工升级、退款、显式反馈都有混杂因素。按任务类型抽样，让领域专家给盲标，并比较 Judge 的一致率、误报/漏报、分桶差异和升级前后漂移。
失败聚类：用来发现候选模式，不是自动根因分析
先对脱敏后的失败 Trace 组合结构字段与 Embedding（向量表示）聚类，再由专家合并、拆分并命名“未召回”“Tool schema 变化”“长上下文漏条件”等标签。聚类结果是待验证假设，不能直接当因果结论。
这项 Position Bias 论文于 2024 年首次提交；2025 年 v9 / AACL-IJCNLP 版本覆盖 15 个 Judge（12 个闭源、3 个开源）、22 类任务、约 40 个候选模型和超过 150,000 次评判，确认顺序偏差会随 Judge 与任务变化。上线做法是交换 A/B 顺序、对不一致样本复评或升级人工、用固定校准集做 Shadow 对照，而不是假设某个更强模型天然无偏。
同样叫“退款失败”，修复对象可能完全不同
假设一周收集 500 条合规采样的失败 Trace，可以先按“旧政策召回、缺订单号、Tool schema 冲突、支付 timeout、超期限”形成候选簇；随后核对各簇样本量、抽样概率和真实终态，再决定改索引、交互、代码还是重试策略。不能先编一个“60% 来自某字段”的数字再倒推故事。
可复现的不是一句 Prompt，而是输入、版本、环境与判定合同
Replay Harness（回放测试台）要保存脱敏输入、Prompt/模型/索引/工具版本、权限、时间点快照、预算和允许行为集合。它回答“候选版本在相同证据条件下是否更好”，而不是要求随机生成逐字相同。
冻结输入与 manifest，不假装冻结世界
保存输入（脱敏后）、Prompt ID、requested/returned model、参数、document IDs/index snapshot、Tool schema、地区/权限、最大步数和停止原因。外部 API 要用录制响应、沙箱或时间点快照，并明确哪些依赖仍会变化。
保存可接受行为集合，不只保存唯一文本
开放任务定义必须引用的事实、禁止动作、Tool 参数约束、业务终态和可接受答案集合。temperature=0 也不保证跨版本、硬件或 Provider 调度逐字一致；逐字匹配会把合理改写误判为回退。
同样本配对 baseline 与 candidate
在同一 Harness 上比较质量、E2E/TTFT/P95、成本和失败类型，保留总体与关键分桶。尾延迟仍要在真实到达过程和并发下压测，离线串行回放不能代表生产排队。
安全零容忍是政策硬门，不是“真风险等于零”的统计证明
危险副作用、越权和敏感数据泄露可设“样本中一例即阻断并人工审查”；若测试中零命中，只能说明这批样本未观察到，仍需报告样本量、覆盖面和不确定性。总体平均提升也不能掩盖高风险分桶回退。
LangGraph 的官方 time travel 语义明确：从旧 checkpoint replay 会跳过此前节点，但会重新执行此后的 LLM call、API request 和 interrupt。回归环境不得直接重复生产退款、发信或写库；恢复环境也必须依靠服务端幂等、查询或对账。这是 LangGraph 的具体 replay 合同，不应外推为所有工作流引擎的统一语义。
可观测性记录状态、操作身份、收据与未知结果
Checkpoint 保存流程状态，但不证明外部副作用只发生一次。本页关注“恢复证据怎样进入 Trace”；完整状态机、租约、隔离令牌、补偿与故障注入请继续阅读 Agent 可靠执行：状态、收据与恢复协议。
Checkpoint Span：记录恢复位置与兼容版本
保存 thread/run ID、checkpoint ID、graph version、已完成节点、下一节点、结果引用、pending writes、暂停原因和 resume count。节点边界的快照不等于函数任意一行都可恢复。
操作身份：稳定 operation_id + intent_hash
operation_id 在首次意图持久化时生成，并跨进程、跨重试复用；intent_hash 绑定金额、对象、动作类型和关键参数。run-step 之类易随重放改变的序号不能独自充当幂等键；同键异意图必须返回冲突，而不是复用旧结果。
操作账本：状态必须能表达结果未知
至少区分 not_sent、pending、succeeded、failed_final 与 unknown。timeout 只说明调用方没拿到结果，不说明远端没执行；unknown 要先用 Provider request/resource ID 查询或业务对账。
Outbox 的边界：原子化本地写入，不魔法覆盖远程系统
Transactional Outbox（事务 Outbox）能在一个本地 ACID（原子、一致、隔离、持久）事务中提交业务变更和待发事件；消息仍可能至少一次投递，消费者要幂等。任意支付、邮件或第三方 API 仍需服务端 idempotency key、查询接口、收据或补偿。
Trace 要能复原“为什么重试或没有重试”
记录 ledger transition、attempt、backoff、decision reason、receipt、reconcile result、人工审批和最终业务终态。恢复成功率应以“恢复到正确且无重复副作用的终态”为分子，而不是仅统计工作流进程重新启动。
最危险的窗口是“远端成功，本地尚未记账”
恢复时旧 checkpoint 仍显示 Tool 未完成。若退款服务接受同一个 operation_id 并返回第一次的语义等价结果，Agent 可以安全补写收据；若远端没有幂等能力，就先按订单与 Provider request ID 对账。盲目重试和盲目跳过都可能错。
先决定哪些数据能离开应用，再决定哪些 Trace 值得留下
Prompt、检索文档和 Tool 参数很有调试价值，也可能包含 PII（Personally Identifiable Information，个人可识别信息）、凭证和商业秘密。正确顺序是：在应用侧派生必要的低风险标签，尽早 allowlist/脱敏，再路由和采样；不能先把完整正文集中起来，再希望后端帮你擦干净。
最小化
默认保存版本、长度、哈希、类别与 Token 数；正文和 Tool 参数按租户/场景显式 opt-in，设用途、短保留期和删除验证。
保护
入口 allowlist、PII/secret 删除或 tokenization、传输/静态加密、RBAC（Role-Based Access Control，基于角色的访问控制）、租户与地域隔离。
审计
记录谁改了采样/脱敏规则、谁查过原文、导出到哪里、何时删除；敏感 Trace 的查看与下载本身也要成为审计事件。
Tail Sampling：先收齐 Trace，再按结果决策
OpenTelemetry Tail Sampling Processor 截至核查日仍是 Beta。所有 Span 必须按 Trace ID 到同一 Tail 实例；扩容时通常由上一层 Collector 的 load-balancing exporter 做一致路由。可在同一个 tail_sampling processor 的 policies 列表中配置错误/慢请求等优先 cohort 与 random_baseline，但它们的并集不能直接估计总体：总体指标只用可识别随机 cohort，或按真实已知 inclusion_probability 加权。OTel 自动写读概率与策略归因目前依赖默认关闭的 Alpha feature gates，不能假定字段天然存在。
Head Sampling：入口早决策，但后面救不回已丢 Span
Head Sampling 在请求开始时决定是否记录，开销低，却不知道最终会不会失败。若 SDK 已按低比例 head-drop，后置 Tail Collector 无法恢复那些 Span；要么把相关 Span 全送到 Tail，要么另建独立、可解释的随机遥测路径。
“错误优先”不是“错误保证 100% 留存”
Collector 的 num_traces、decision wait、晚到 Span、内存与导出失败都会影响留存；容量超限会出现 sampling_trace_。因此要记录目标策略、policy_version、selection reason、cohort 与容量上限；随机 cohort 另存其已知纳入概率，并监控容量早退和导出丢弃。
采样标志与 Trace Context 不能作为安全信号
外部请求可以伪造 sampled flag 来增加系统负载；traceparent、tracestate 与 OpenTelemetry Baggage 都会跨边界传播，不应放凭证或 PII。跨安全域要验证、清理或重建上下文，不要让“同一 Trace”被误解为“同一授权主体”。
手机号、邮箱和短用户 ID 的输入空间可枚举，普通无盐哈希很容易反查。若只需稳定关联，可使用受控 HMAC（Hash-based Message Authentication Code，基于哈希的消息认证码）、域内 surrogate ID 或聚合分桶；即使使用 HMAC，也要管理密钥、轮换、访问边界和关联风险。
字段为什么收、在哪里变形、谁能看、何时删
对每个 Prompt/Context/Tool/Eval 字段写 data owner、用途、敏感级别、采集点、脱敏方式、保留期和删除验证；再用含 PII、密钥、异常堆栈和超长内容的测试 Trace 验证 Collector、导出器、Exemplar 与告警通知都没有旁路泄漏。
一手来源与证据边界
优先使用论文、官方文档、官方模型卡和代码仓库。页面中的数字只代表来源所述设置，不自动外推到其他模型与数据。
traceparent / tracestate 的跨服务传播、隐私风险与信任边界；它们是关联上下文，不是身份或授权。
GenAI span、metric、event 的独立仓库与当前生命周期；截至核查日无 release，Schema URL 仍为 TODO。
模型请求/响应、Token、缓存、Prompt 版本、首块延迟和 opt-in 内容字段；仓库当前依赖 core semconv v1.43.0。
建立在 OpenTelemetry 之上的 AI 语义层，包含 LLM、Agent、Tool、Retriever、Reranker、Guardrail 与 Evaluator span kind。
同一 Trace 的全部 Span 必须到同一 Tail 实例；随机基线与优先留存 cohort 可写入同一 tail_sampling processor 的 policies 列表，但策略并集不能直接估计总体。
当匹配 View 未设置 aggregation_cardinality_limit，且 MetricReader 未设置默认 cardinality limit 时，SDK 建议以每个 instrument、每个 collection cycle 输出 2,000 个数据点为默认上限；规范也定义 overflow 聚合与 Exemplar。
不要把 user ID、邮箱等无界高基数字段放进 Metric label。
复用相同 Token 前缀的 KV Cache block、命中粒度、淘汰与多租户 cache salt 边界。
精确前缀匹配与输出仍重新生成的语义；cached_tokens 适用于全部请求，cache_write_tokens 当前只由 GPT-5.6 及以后模型族报告。
每个 super-step 的 checkpoint、pending writes、线程状态与持久化边界。
稳定客户端请求 ID、同键语义等价、同键异意图冲突，以及服务端原子记录幂等状态。
本地数据库变更与待发事件的原子提交、至少一次投递和消费者幂等；不把 Outbox 外推成任意远程 API 的 exactly-once。
数据最小化、allowlist、过滤、哈希、Redaction Processor 与可预测标识符不能靠普通哈希匿名化。
15 个 Judge（12 个闭源、3 个开源）、22 类任务、约 40 个候选模型和超过 150,000 次评判揭示 Position Bias 与任务差异。
按语义相似度复用完整 LLM 响应或 Tool 结果，区别于精确 Token 前缀的 KV / Prompt Cache。
从历史 checkpoint replay 时，checkpoint 之前的步骤被复用，之后的 LLM、API 与 interrupt 会重新执行。
Baggage 会跨服务传播，可能到达不受信任的第三方；不得放入凭证、PII 或其他敏感信息。