Skip to content

martin1847/evolab / skills/observability-standard

observability-standard

Verified

适用于编写或评审任何后端服务,包括普通服务与 agent/RAG 系统。覆盖日志、tracing、OpenTelemetry、上下文传播、日志级别、trace/log/DB 关联、边界类型及 LLM/工具/检索调用观测。用户说“加点日志”“接一下 trace / instrument this”“set up observability”“这个错误怎么查不到”“这个请求怎么追踪”也触发。

references/standard.md

View on GitHub
# 服务可观测性与工程规范(语言无关)

> 总纲:**用一条关联主线贯穿定位**。`trace_id` 串起 trace + log;业务库这一环靠**业务 id 同时挂成 span 属性(`order.id` / `run.id`)**关联,**不在业务行存 `trace_id`**(见 §2.1)。
> 定位问题永远是 `拿到 trace 或业务 id → 查 trace 看哪步 → 查 log 看为什么 → 按业务 id 查 db 看数据对不对`,绝不靠时间戳猜。
>
> 适用范围:**所有后端服务** —— 普通微服务(auth / 网关 / 业务服务)、以及 agent(单 agent、orchestrator/worker、流水线)、RAG/知识库;Python / Go / Java / Rust 通用。
> 读法:**普适核心(所有服务遵守):§1、§2 普适原则 + §2.1、§3、§4、§5.0、§7、§9**;**§2 / §6 / 附录 C 各取你的语言附录**(Python / Go / Java / Rust);**§5.1(agent)/ §5.2(RAG)按项目类型选增量**。
> 维护契约:本文 §1–§9 在 `SKILL.md` 有压缩镜像;改任一条规则必须**同步两处**,不留分叉。

---

## §1 五条普适铁律(语言/项目无关)

1. **一次对外请求 = 一棵 trace**。入站请求 handler 是 root span;所有下游(DB / 缓存 / 跨进程调用 —— agent 场景下还有子 agent / LLM 调用 / 工具调用 / 检索)都是子 span。agent 编排场景额外给整棵 trace 一个 `run.id`(span 属性键用点号,与 `tenant.id` 一致;业务库列名仍是 `run_id`)。
2. **宽事件优先**:每个处理步骤输出一条富字段结构化事件,而非散文文本。事件名是稳定标识符(可聚合),变量进字段。指标从字段派生,不从 grep 派生。
3. **三信号可关联**:trace 串 span;每条 log 带 `trace_id`+`span_id`(随 trace 同采样 / 保留);**业务 id 挂成 span 属性(`order.id` / `run.id`)**以按业务 id 反查 trace。**不往业务行加 `trace_id` 列**——trace 被采样、保留期短,持久业务行存它多半成死指针(详见 §2.1)。
4. **跨进程必传播 context**:任何跨进程边界(HTTP / gRPC / 消息队列 / agent-to-agent 协议)必须传播 W3C `traceparent`,入站 extract、出站 inject。**不传播 = trace 断成多棵互不相连的树 = 跨服务定位失效**。这是头号正确性要求,优先级高于功能。
5. **标准在边界 + 后端无关**:跨进程、对外响应遵守 OTel 语义约定 + 类型校验;LLM 边界额外遵守 GenAI 语义约定;内部实现自由。**只依赖 OTel API/SDK + OTLP exporter,应用代码不 import 厂商 SDK(Langfuse / Datadog 等);标准组件优先用官方 auto-instrumentation(自动 / 零代码,包见附录 C)埋点,手写 span 只补领域环节;厂商差异只在 Collector / exporter 配置层 —— 换后端(SigNoz / ClickStack / Langfuse,均支持 OTLP)不改一行埋点。**

---

## §2 类型纪律

**普适原则(四语言都成立):**
- 在**边界**锁死数据结构、运行期校验;内部拿到的是可信类型。
- **ID 不用裸字符串**,用语言各自的"专名类型",防止参数传反。
- **状态/角色/事件名用枚举式类型**,不用裸字符串。
- **跨进程的失败建模成数据,不靠异常穿透**——一旦序列化,栈帧就没了,失败必须是返回值/结果类型的一部分。
- 边界数据模型尽量**不可变**,防下游误改后写错指标。
- **持久化只存自己拥有的 id**:业务 id / `correlation_id` 才落库;`trace_id` 是 ephemeral 链接,不当业务行外键(详见 §2.1)。

### §2.1 id 持久化与关联(普适,所有服务)

**不要在业务写入里塞 `trace_id` 列。** 问题不在字节(一列 16–32 字节,存储上微不足道),在**生命周期错配 + 耦合**:

- **生命周期错配(致命)**:trace 被采样、短保留(典型:1% 平采样 + 偏向错误 / 高延迟的尾采样,代表性 trace 留 ~30 天;头 / 尾采样意味大量 trace 根本不留)。业务行持久(存数年)。存进业务行的 `trace_id` 绝大多数指向一条已被采样丢弃或已过期的 trace = 死指针。
- **schema 耦合**:把持久业务表绑到一个由可观测后端拥有、生命周期完全不同的字段。
- **索引代价**:真要按它查就得建索引 → 热表写放大 + 索引体积;不建索引,这列查不动,等于摆设。

**业界标准做法(都不是"往业务表塞 trace_id"):**

1. **区分持久 `correlation_id` 与 ephemeral `trace_id`**。`trace_id` 不透明、每请求变、无业务含义(on-call 调试能用,但没法按"订单 #12345"查)。要持久存,存你自己拥有、带业务含义的 `correlation_id` / `run_id` / `order_id`,不是裸 OTel `trace_id`。
2. **反转查找方向**:把业务 id 作为 **span 属性**,反过来按业务 id 查可观测库(`WHERE attributes->>'order.id' = '...'`)。业务 id 本就是业务主键、已在库里,只要它也是 span 属性,**零新增列**即可从业务 id 反查到 trace。
3. **传播用 baggage,高基数 id 别进 metric label**。入口设业务 correlation id,用 baggage 传播,使其出现在 spans / logs / metric exemplars;Collector 的 baggage processor 自动注入;高基数 id 进 metric 标签会基数爆炸,指标到 trace 的链接靠 **exemplar**。

**真要 `trace_id` ↔ `request_id` 映射时**:维护一个轻量 correlation 索引(Redis / 专用表)存 `requestId ↔ traceId ↔ 时间戳`,带 ~24h TTL —— 独立索引,不污染业务热表。常见实战:每请求生成 / 传播一个 UUID `correlation_id` 存进语言原生 ambient context,注入日志、并作为 `request_id` 写进 trace 元数据;**持久 id 是 `correlation_id`,trace 关联走日志**。

**唯一该持久落库的场景:审计 / 溯源,且进专用 store**(AI 决策、报价 / 金额、对客最终输出、合规):
- 审计事件在**发布到日志管道之前先落进持久存储**(下游日志系统挂了,审计仍正确);
- 保留期对齐最严监管(如 SOX 6 年、PCI 滚动 12 个月),不可变 / 校验和防篡改;
- 用**业务上下文**丰富(用户、记录类型、改了哪些字段),别只存一堆 id;
- 这张专用审计表里放 `correlation_id`(+ 尽力而为的 `trace_id` 链接),而**不是**给每张业务表加列。

### 附录 A·Python
- `pyright`/`mypy` **strict** 进 CI 门禁;公共函数(agent/tool/handler)全标注。
- **数据两档**:只有跨进程数据(JSON / HTTP 载荷、manifest、配置)用 **Pydantic v2** `BaseModel`,`model_config = ConfigDict(extra="forbid", frozen=True)`(抓 typo + 边界对象不可变),边界 `model_validate` 一次;进入内部即转 `@dataclass(frozen=True, slots=True)`,内部 DTO(事件 / 信封 / 结果)不带 Pydantic 依赖与校验开销。混用模块在模块级注释写明边界在哪一行。
- `NewType` 区分 ID:`RunId = NewType("RunId", str)`。
- `Literal` 表状态/角色/事件名。
- 结果用判别联合(内部 → frozen dataclass):`Ok` / `Err` 各一个 `@dataclass(frozen=True, slots=True)`,以 `status: Literal["ok"]` 判别,`Result = Ok | Err`,调用方 `match`。
- 接口用 `typing.Protocol`(结构化子类型)不用 ABC;默认实现体放独立 mixin 类(只结构化符合、不显式继承协议的类拿不到 Protocol 里的默认实现)。

### 附录 A·Go
- `go vet` + `staticcheck` + `golangci-lint` 进门禁。
- 专名 ID 用 defined type:`type RunID string`(编译期不与普通 string 混用)。
- 边界结构体用 `go-playground/validator` 等做标签校验。
- **`context.Context` 一路下传**(它同时携带 trace 上下文、取消、deadline);函数签名第一参数即 `ctx`。
- 错误是值:`return zero, fmt.Errorf("...: %w", err)` 包装;用 sentinel/typed error(`errors.Is/As`)替代异常穿透;**不要 `panic` 跨边界**。
- 状态用 `type State string` + 常量集合;DTO 尽量值传递保持不可变意图。

### 附录 A·Java
- 编译器 `-Werror` + Error Prone / NullAway 进门禁。
- DTO 用 `record`(天然不可变);边界用 Jakarta Bean Validation(`@NotNull`/`@Valid`)。
- 专名 ID 用 wrapper `record RunId(String value){}`,不用裸 `String`。
- 判别联合用 **sealed interface + record**:`sealed interface Result permits Ok, Err {}`,配合 `switch` 模式匹配穷尽。
- 状态用 `enum`;避免 `null`,用 `Optional` / `@Nullable` 标注。

### 附录 A·Rust
- `cargo clippy -- -D warnings` 进门禁;库内 `#![forbid(unsafe_code)]`(无 FFI 时);公共 API 显式标注类型。
- 专名 ID 用 newtype:`struct RunId(String);` + `#[derive(Clone, Debug, PartialEq, Eq, Hash)]`(编译期不与普通 `String` / 别的 ID 混用)。
- 边界数据用 `serde` + `#[serde(deny_unknown_fields)]` 反序列化即校验;复杂约束用 `garde` / `validator`。
- 失败是值:返回 `Result<T, E>`,错误类型用 `thiserror` 定义(库层),`anyhow` 仅应用顶层;**跨进程失败序列化成结果类型,不靠 `panic` 穿透边界**(panic 跨 `await` / 线程 / FFI 不可靠)。
- 状态/角色/事件名用 `enum`,`match` 穷尽;边界 DTO 默认不可变(绑定默认 immutable,不暴露 `&mut`,共享只读用 `Arc`)。

---

## §3 日志铁律(语言无关)

1. **结构化优先,永不字符串拼接**。`message` = 短事件名(snake_case),变量全进字段。**宽事件 ≠ JSON**:要求的是"事件名稳定 + 变量进字段 + 行式可解析",不是 JSON 序列化——JSON 有实打实的每行计算开销,默认行式字段格式即可;日志管道需要机器解析时再升 JSON,且升级只应动导出层配置、不动打点代码。
   - ✅ `info("tool_call_failed", tool="search", code="timeout", attempt=2)`
   - ❌ `info("Failed to call search because timeout on attempt 2")`
2. **日志即数据,不即叙事**。事件名是可查询/聚合的标识符,不是给人读的句子。
3. **trace 绑定是默认**:日志在活跃 span 内打出,`trace_id`/`span_id` 由桥/处理器自动注入。**没有 `trace_id` 的 ERROR 视为 bug**。
4. **上下文绑一次贯穿全程**:进入一次 run 时绑 `run_id`/`tenant_id`/`agent_role`(语言原生 ambient context 机制,见 §6 附录 B),之后每条日志自动带,不手传。
5. **不要 log-and-throw**:要么处理并记录,要么向上抛由处理者记录,别既记录又抛。
6. **永不记录**:密钥/token/凭证、完整 PII、客户机密原文。在日志边界脱敏。
7. **明文 model I/O = 数据披露闸,非日志级别**:记明文 prompt/completion MUST 同时满足 **显式 flag + 非 prod 环境 + best-effort 脱敏**(不是"调成 DEBUG 就行");audit / 持久溯源 **MUST 仅存哈希**,不留明文。这三条件由 `references/conformance-profile-v3.json` 机械执行,oracle 只按 `schema_version` 闭集分派(v2 带 content 段 / v3 缺子键 / 未知版本 = profile invalid,红):**环境走白名单**(`allowed_environment_pattern`,值先 strip、大小写不敏感;不命中即红,故 `live` / `prd` / `"prod "` 等别名不再是"非 prod")、`audit_records` 子树的**每个字符串叶值**必须 fullmatch 哈希模式或命中 `metadata_key_allowlist` 且不超 `metadata_max_length`(别名字段装明文即红)。V2 profile 保持无条件 fail-closed,放开只能换显式 profile 版本、不能由运行时开关绕过。
   - **snapshot 形态契约(下游机械可产出)**:`redaction_probe.canaries` = **object list**,每项 `{class, value}` 两个非空字符串;`redaction_probe.redacted` = **string list**;两者 **1:1 等长、按索引对齐**(长度不等即 `content.redaction_output_arity`,聚合成单串的产出形态不被接受);每个 `class` 必须在 `forbidden_output_patterns` 有对应形状,且该 class 的 `value` 必须命中该形状(不像 API key 的 `api_key` canary 即红);产出每项 strip 后 ≥ `min_output_chars`。probe 与 capture 面机械绑定:任何 canary 字面量若出现在**被 capture 的 content key 值**里即红——该断言只在 canary 真被送进 capture 管道时才有杀伤力。**oracle 判的是 snapshot 级证据自洽**,它结构上不能证明「canary 穿过了真实 redactor 路径」或「产品仓真的调用了 redactor」——把 canary 灌进真实管道并断言其结局,由产品仓自己的 conformance 测试(§9.1 负例探针)负责,gate 不冒充那一层。
8. **必记点(均 ≥ INFO)**:路由/决策点及其依据、状态转移、每次 LLM/工具/检索/跨进程调用的边界与结果状态、重试/回退/降级/补偿、每步 token 与成本(也作 metric)。
9. **统一 logger 树 + 级别由配置控**:用语言原生 named logger(如 `getLogger(__name__)`)落统一树,**MUST NOT 自造 logger 名**;级别由 env/config 统一控,**MUST NOT 用 `os.getenv(...DEBUG...)` 之类门控单条日志**(级别是配置事,不是代码里逐条判)。

---

## §4 日志级别(INFO vs DEBUG 判据)

> 判据:**这条日志在"正常生产运行"里读它有意义吗?** 有 → `INFO`;只有"出问题深挖时"才看 → `DEBUG`。
> 一句话:**INFO 重建"发生了什么"的骨架,DEBUG 重建"为什么"的全部细节。**

| 级别 | 何时用 | 生产默认 | 告警 |
|---|---|---|---|
| `ERROR` | 失败且影响本次请求结果(调用最终失败、不可恢复的工具错误、非法状态转移、跨进程调用彻底失败无法补偿)。**必带 trace + 操作 + 输入标识符 + 异常栈**。 | 开 | 是 |
| `WARNING` | 降级但请求继续(重试、回退备用 prompt/模型、超时用缓存、输出未过校验已重试、部分失败已补偿)。 | 开 | 视情况 |
| `INFO` | 业务里程碑与状态转移。**粒度 = 每个 step / 每次调用 / 每次状态转移一条**;目标:只读 INFO 即可重建一次 run 的骨架。**不刷高频内循环**。 | 开 | 否 |
| `DEBUG` | 深挖细节:完整 prompt、模型中间推理、原始工具响应、检索命中的 chunk、跨进程报文全文。体积大、含敏感数据、仅 deep-dive 看。 | 关(可按 trace 动态开) | 否 |

补充:OTel 无标准 TRACE 级,最细用 `DEBUG`;生产默认 INFO,DEBUG 按环境变量或按特定 `trace_id` 动态开(采样式重放);**排障时若"光看 INFO 不知走到哪步",是 INFO 漏了状态转移点——补 INFO,而不是常开 DEBUG**。

**span 导出日志与环境分级(多语言通用)**:
- **span 复述进日志流 = 噪音**:console/logging 型 span exporter 把每个 span 复述成一条日志——每请求一条、exporter 线程在请求上下文之外 → `trace_id` 关联字段为空,连"日志必带 trace_id"都不过。此类 exporter 各语言 OTel SDK 都有(Java `LoggingSpanExporter` / Python `ConsoleSpanExporter` / Go `stdouttrace` / Rust stdout exporter),**定位都是 dev 期验证埋点,不是部署环境的 trace sink**。trace 信号的正解是 OTLP 后端;部署环境把该 exporter 的 logger 类别阈值默认压到 `WARN`(保留 SDK 自身告警),dev 覆盖回可见。
- **环境三档矩阵(默认形状)**:

  | 环境 | 全局级别 | span 导出行 | 来源 |
  |---|---|---|---|
  | dev | DEBUG | 可见 | 代码内 dev 默认(开发就近调试) |
  | staging | DEBUG | 可见 | 部署层运行时配置开 |
  | prod | INFO(骨架) | 隐藏 | 默认即安静侧,零配置 |

- **配置分工(所有权切分)**:语义级别(哪条日志算 INFO/DEBUG)归**代码**,且默认取安静侧;级别阈值按环境开归**部署层运行时配置**。rationale:"一份构建物服务多环境"时 stage/prod 跑同一构建物/同一 profile,构建期配置分不开环境,环境详细度必须是运行时可覆盖项——由此得所有权切分:代码管语义,部署层(manifests/env)管环境。**注意 logger 类别阈值通常优先于全局级别**:全局开 DEBUG 不会带出被类别阈值压住的行,要看见须显式开该类别。各语言的运行时级别覆盖机制:Java(JUL/JBoss LogManager/Logback)类别级别属运行时配置(Quarkus 形如 `QUARKUS_LOG_CATEGORY__<CAT>__LEVEL`,注意 native 受构建期 min-level 下限约束);Python `logging` 按 logger 名 setLevel,入口从 env/配置读;Go `slog.LevelVar` / zap `AtomicLevel` 运行时可调;Rust `tracing` `EnvFilter`(`RUST_LOG=target=level`)。
- **静音前查 sink**:若部署环境此前以日志流当 trace 落地(无 collector),静音 span 导出 = trace 信号整体消失;先补 OTLP collector(exporter 选择在部分栈是构建期属性——如 Quarkus native——切换须重构建,排期考虑)或有意识接受盲区再静音。

---

## §5 OTel Span 拓扑

### §5.0 服务基线拓扑(所有服务)
任何服务的最小 span 拓扑:**入站 server span = root**(带 `trace_id` / `run.id`)→ 每次**出站 client span**(HTTP / gRPC / MQ;**先开 client span 再 inject `traceparent`**——使注入的 header 带真实 parent span)→ DB / 缓存 / 外部 API 子 span。trace 是请求在系统里的因果树;§5.1 / §5.2 是 agent / RAG 在此基线上的**增量**。

**Resource 部署身份(MUST)**:每个服务的 OTel Resource 必须带 `service.name` + `service.version`。`service.version` 钉当前实际部署的 release / image tag,例 `20260709-1020-c28e8f2`;部署层用 `OTEL_RESOURCE_ATTRIBUTES=service.version=20260709-1020-c28e8f2` 注入。该值 MUST 非空、非 placeholder(`unknown` / `latest` / `dev` 等),且与 Docker / GitOps 实际部署 tag 一致。release tag 只识别 deployed artifact,不是动态配置版本,不能代替 durable workflow 的 immutable effective-config snapshot。

**Resource ownership 与冲突优先级**:
- `service.namespace`:稳定逻辑系统/产品分组,由应用或部署合同声明;不是 Kubernetes namespace。
- `deployment.environment.name`:部署环境,由部署配置声明;优先标准值 `development|test|staging|production`,不参与 service identity 唯一性。
- `k8s.cluster.name` / `k8s.cluster.uid`:由平台/IaC或可靠 detector 提供;name 便于查询,uid 才是 cluster identity。
- `k8s.namespace.name`:由 Collector `k8sattributes` 等运行时富化;应用不得伪造。Collector MAY 补缺失的运行时属性,**MUST NOT 覆盖**应用/部署合同已声明的 `service.name` / `service.namespace` / `service.version`。

共享 OTLP/SigNoZ 只表示共用存储/查询面,**不构成安全 tenant 隔离**。`tenant.id` 不属于 OTel 标准,是 custom request/span/log 属性;仅在确有并已验证真实业务 tenant 时写,不得写入 Resource,不得填产品名、环境、`service.namespace` 或 `k8s.namespace.name`,也不得作为 metric label。无真实 tenant 时必须缺失。

**这三类基线 span 优先用官方 auto-instrumentation(自动 / 零代码)产出**,而非手写;手写 span 只补自动埋点拿不到的领域环节(§5.1 / §5.2)。各语言 auto-instrumentation 包见**附录 C**。

### §5.1 Agent 增量(在 §5.0 基线上)

> 基线:OpenTelemetry GenAI conventions 当前状态为 **Development**。字段以仓库 pinned oracle 为准;仅当具体 instrumentation 仍依赖旧版迁移机制时设置 `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`,不得把 `latest` 当稳定契约。
> 事实基线(2026-07 亲验):`gen_ai.*` **零属性 Stable**(SEO 站"已稳定"说法与 spec 原文矛盾,勿信);约定 2026-06-12 整体迁仓至 `open-telemetry/semantic-conventions-genai`(旧 semconv 固定链接/codegen 失效);`gen_ai.system` 已废、现名 `gen_ai.provider.name`(主流平台仍读写旧名,接入逐属性核对);**Java 上游 GenAI instrumentation 覆盖窄**(官方 supported-libraries 矩阵仅 OpenAI Java SDK 与 AWS SDK 两族发 GenAI spans/metrics)——矩阵外 provider 的 `gen_ai.*` 需自建(pin revision + 内部抽象层,字面量不散落业务代码),接入前先查 pinned 矩阵。
>
> **接入 LLM 可观测平台(Langfuse / Phoenix 等)优先走 OTLP ingestion** —— 当作一个 OTLP 后端接,不在应用代码引其 SDK(Langfuse 已支持 OTLP)。

| 概念 | OTel span / 操作 | 关键属性 |
|---|---|---|
| 编排 | invoke workflow span | `gen_ai.operation.name=invoke_workflow`,真实可得时 `gen_ai.workflow.name` |
| 调用子 agent | invoke agent span | `gen_ai.operation.name=invoke_agent`,`gen_ai.agent.name`,真实可得时 id/version/conversation |
| 每次 LLM 调用 | inference span | `gen_ai.operation.name=chat|generate_content|text_completion`,`gen_ai.provider.name`,`gen_ai.request.model`,`gen_ai.usage.input_tokens/output_tokens`,`gen_ai.response.finish_reasons` |
| 每次工具调用 | execute tool span | `gen_ai.operation.name=execute_tool`,`gen_ai.tool.name`,`gen_ai.tool.call.id`;组织 envelope 另含 status/error/duration/resource(见下) |
| prompt 版本 | 挂在 inference span 上 | `gen_ai.prompt.name`,`gen_ai.prompt.version`;变量属于 opt-in content |

`inference` 是 span 概念,不是 operation value。`gen_ai.conversation.id` 仅在真实 conversation/session/thread id readily available 时写,不得生成新 UUID、trace id 或内容 hash 顶替。模型与 prompt 版本沿用 `gen_ai.request.model` / `gen_ai.prompt.version`,不另造平行字段。组织级 custom 字段必须由 profile extension 声明:低基数字段钉 allowlist + 长度,跨 span 关联 id 钉同 trace 一致性且不得进 metric label;公共 profile 不内置任何公司/项目 namespace。`tenant.id`、组织字段、`tool_status` 等 custom 字段不得宣称为 OTel 标准。

**工具调用 envelope 纪律(MUST)**:每个工具调用落一条结构化记录(execute_tool span / 持久 envelope),字段 ≥ `tool_call_id` / `tool_name` / `tool_status` / `error_type` / `duration_ms` / `trace_id` / `span_id` / `resource_identifier`。两条硬约束:
- **稳定显式 id**:`tool_call_id` MUST 显式生成且稳定;**MUST NOT 复用底层框架的 run_id 当持久 id**——否则 parent→child→provider 跨跳无法 join。
- **键名分层**:`tool_call_id` 是**持久 envelope 的列名**;span/telemetry 属性一律用标准键 `gen_ai.tool.call.id`(同一个值)——`tool_call_id` 直接进 span 属性会被 conformance oracle 判 legacy key(profile `forbidden_keys`)。
- **完整生命周期**:start **与** finalize 都要写,`tool_status` 必终结到 `success`/`failed`/`timeout`/`cancelled`/`blocked`;**只写 start 会让记录永停 `running`**(常见实漏)。

拓扑铁律:子 agent 之间若不直连、只经编排者中转,则所有 agent span 都挂在编排 span 下,trace 天然呈**树**(= 编排拓扑的镜像),而非网,便于定位。

**持久化执行(durable execution,如 Temporal / DBOS / Restate / 自建)专项**:工作流跨重启/恢复时默认会**丢失原 trace context**,恢复后那段会脱离原 trace。必须把 `traceparent` 一并持久化进工作流状态、恢复时重建。当成显式设计项,不要假设自动。

**LiteLLM OTel V2 profile**:Proxy 新接入显式启用 V2并关闭 legacy compatibility;V1/V2 二选一。generic OTLP、vendor preset、custom OTel callback 只能形成一个语义 span 生产路径;fan-out 只在 exporter 层做,并以 collector 端 `(trace_id,span_id)` 计数证明无重复。LiteLLM 的“standards-based”不等于逐字段 conformance,每次升级仍按 pinned oracle 验证。

- generation/inference span 必须是当前 domain/invocation span 的 child;instrumentation 每进程 bootstrap 一次,不能只在 API handler 注册。
- async callback、worker、poller、streaming 在脱离点捕获并恢复 OTel context;callback 晚到也恢复原 parent。
- streaming 覆盖正常耗尽、provider error、client cancel/disconnect、consumer early-close;只有正常完整消费才 success,其余必须终结为对应 error/cancelled,不得泄漏未结束 span。
- 当前 V2 conformance profile 对明文 `gen_ai.system_instructions` / input/output messages、prompt variables、tool arguments/results 无条件 fail-closed:即使 dev runtime flag 为 true也拒绝;放开须发布新的显式 profile 版本,不能由运行时开关绕过。sentinel 必须证明 spans/events/legacy mapper 均无内容泄漏。

### §5.2 RAG / 知识库 增量
在 §5.1 基础上**加开检索链路的 span**(GenAI 约定含 embeddings、retrieval span)。理由:RAG 的两类失败——**检索没召回**(知识在库里但没取到)与 **生成幻觉**(取到了但模型瞎编)——只有靠 retrieval span 才能区分;没有它,你看到错误答案根本不知道该修检索还是修 prompt。

| 概念 | span | 必记字段 |
|---|---|---|
| 向量化 query | embedding span | 嵌入模型、维度、耗时 |
| 检索 | retrieval span | 原始 query、top-k、命中 doc/chunk 的 **id + score**、检索耗时 |
| 重排(若有) | rerank span | 重排模型、重排前后顺序变化 |
| 组装上下文 | (挂检索/生成 span) | **最终进入上下文的 chunk id 列表**(provenance) |
| 生成 | inference span | 同 §5.1,外加引用了哪些 chunk |
| 接地校验(若有) | eval/score | grounding/faithfulness 分、是否有未被来源支持的断言 |

知识库专属铁律:**答案要可溯源到 chunk**。把"最终进上下文的 chunk id"挂到 span,排障时一眼看出"模型是依据哪几段编的"。需持久审计时(ToB / 合规),把答案 + chunk id + 自己拥有的 `correlation_id`(+ 尽力而为的 `trace_id` 链接)落进**专用审计 / outbox store**(按 §2.1),而非给每张业务表加 `trace_id` 列;`trace_id` 受采样 / 保留约束,仅作尽力而为链接。

---

## §6 日志接入(选你的语言)

目标:一处配置,全项目自动产出 `trace_id`-绑定的结构化日志,经 OTLP 进后端。**两层别混**:关联层(把 trace context 注入每条日志)+ 导出层(把日志作为一等遥测发出)。

### 附录 B·Python
- 库:`structlog`(结构化)+ OTel 日志桥 `LoggingHandler`(导出)。
- 关联:自定义 processor 从 `trace.get_current_span()` 取 id 注入;或 contrib 的 `LoggingInstrumentor` / 环境变量 `OTEL_PYTHON_LOG_CORRELATION=true`。
- 导出:`LoggerProvider` + `BatchLogRecordProcessor(OTLPLogExporter())` + `LoggingHandler` 挂到 root logger。
- **坑**:必须在任何库调用 `logging.basicConfig` 之前初始化,否则 trace 注入失效。

### 附录 B·Go
- 库:标准库 `slog` + 桥 `go.opentelemetry.io/contrib/bridges/otelslog`。
- 一行接通:`slog.SetDefault(otelslog.NewLogger("your-service"))`,之后 slog 调用自动带 OTel trace context。
- **坑**:必须用带 Context 的方法 `logger.InfoContext(ctx, ...)`(传当前 ctx),活跃 span 才能关联。
- 高吞吐替代:slog 直接写 JSON 到 stdout,由 OTel Collector 摄入时转 OTel 日志记录(转换成本移出进程),但要自己把 trace 字段注入 JSON(用包装 handler)。

### 附录 B·Java
- 库:Log4j2 或 Logback,经 OTel **MDC** 集成(pattern 里 `%X{trace_id}` / `%mdc{trace_id}`)。
- 关联(两选一):挂 java agent `-javaagent:opentelemetry-javaagent.jar`,自动填 MDC;或用 SDK + `OpenTelemetryAppender`(logback)/ `opentelemetry-log4j-context-data`(log4j2)。
- 导出(两选一):OTLP appender 直发 Collector(简单,有导出开销);或写 stdout/文件 + Collector filelog receiver 采集(复用已有日志基础设施)。
- pattern 示例:`... trace_id=%X{trace_id} span_id=%X{span_id} - %msg%n`。

### 附录 B·Rust
- 库:`tracing`(结构化 span + event,日志与 trace 同一套 API)+ `tracing-subscriber`(订阅/格式化)+ `tracing-opentelemetry`(桥到 OTel)+ `opentelemetry-otlp`(导出)。
- 关联:`OpenTelemetryLayer` 把 `tracing` span 映射成 OTel span,event 自动带当前 `trace_id`/`span_id`;`Registry().with(otel_layer).with(fmt_layer).init()`。
- 埋点:`#[tracing::instrument]` 给函数开 span;结构化字段 `info!(tool = "search", code = "timeout", attempt = 2, "tool_call_failed")`(message 是短事件名,变量进字段)。
- 传播:`global::set_text_map_propagator(TraceContextPropagator::new())`;出站 `inject_context` 进 header,入站 `extract` 后 `span.set_parent(cx)`。
- **坑**:async 里开 span 必须用 `#[instrument]` 或 `fut.instrument(span)`,**不要让 `span.enter()` 的 guard 跨 `.await`**(会把别的 task 时间算进来 / 上下文错乱)。

---

## §7 三查工作流(最快定位)

对外响应回带 `trace_id`(调试入口,受保留期约束)与业务 id(如 `order_id`),客户报问题即拿到入口。

1. **查 trace**:看 span 树 → 哪个子 agent / 哪次 inference / 哪个工具 / 哪次检索 span 红了或慢了。→ "**哪一步**"。
2. **查 log**(同 `trace_id`):跳到该 span 的 INFO/ERROR → 决策、状态转移、错误详情;不够细按此 `trace_id` 动态开 DEBUG 重放看完整 prompt/检索 chunk。→ "**为什么**"。
3. **查 db**(**按业务 id**,如 `order_id` / `run_id` —— 它本就是 span 属性):业务表按业务 id 捞当时落库的数据(抽取结果 / 检索 chunk id / 中间值),与 LLM 输出对账。→ "**数据对不对**"。

三者靠**同一 trace(`trace_id`)+ 业务 id**串联,不在三个系统里靠时间戳猜对应:log / trace 同 `trace_id`,db 这环按业务 id(它是 span 属性)关联,**不依赖业务行存 `trace_id`**。

---

## §8 落地检查清单

- [ ] OTel Resource 同时有 `service.name` + `service.version`;`service.version` 非空、非 placeholder,且精确匹配当前部署 release / image tag(通过 `OTEL_RESOURCE_ATTRIBUTES` 注入)
- [ ] 类型检查器进 CI 门禁(工具见 §2 附录 A·<你的语言>)
- [ ] 边界数据有 schema 校验;跨进程失败建模成结果类型,不靠异常穿透
- [ ] 日志初始化 / trace-context 关联按语言正确接入(见 §6 附录 B)
- [ ] 日志全部 `event_name + fields` 形式,无散文拼接
- [ ] 一次 run 骨架仅靠 INFO 可重建;DEBUG 生产默认关、可按 trace 开
- [ ] 密钥/PII/客户机密在日志边界脱敏;LLM 全文走 DEBUG/内容开关
- [ ] **跨进程一律传播 W3C `traceparent`**;持久化执行恢复时重建 trace context
- [ ] LLM / agent 场景:若所用 instrumentation 仍依赖旧版迁移机制,`OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` 已设(条件见 §5.1;不依赖则不设)
- [ ] 埋点只依赖 OTel API/SDK + OTLP;应用代码无厂商 SDK import;标准组件用 auto-instrumentation(包见附录 C);厂商差异在 Collector / exporter 层
- [ ] RAG 项目:开 embedding/retrieval span;答案可溯源到 chunk id
- [ ] 业务实体 id 作 span 属性(`order.id` / `run.id`)→ 可按业务 id 反查 trace(零新增列);**不往业务行加 `trace_id` 列**
- [ ] 持久溯源(AI 决策 / 金额 / 对客输出 / 合规)落自己拥有的 `correlation_id`,进专用审计 / outbox store(非热表);`trace_id` 仅作受采样 / 保留约束的尽力而为链接
- [ ] 对外响应回带 `trace_id`(调试)+ 业务 id
- [ ] **本规范的每条铁律都绑了 CI gate(见 §9),不是只写在文档里**

## §9 强制生效(让规范咬人,而非形式化)

**核心命题:没有 gate 的规范 = 形式化,必然漂移。** 一份只写"应当"、靠人工自觉对照清单的规范,会在"没有测试看的地方"悄悄烂掉——埋点的洞恰好出现在没人 gate 的模块,评审与单测全绿、"看着合规",直到线上"查不到任何 trace"才暴露。**强制手段是采纳可观测性的一等交付物,不是事后补丁。**

落地一套规范时,除了写规则,必须同时立下面的 gate(语言无关,机制按栈替换):

### 9.1 conformance 测试:断言 span 覆盖 + parent 正确,且**会变红**
- 用**进程内 span 捕获**(语言的进程内 span 捕获器,见附录 C)写一个 conformance 测试:每条新的 LLM / 工具 / 检索 / 领域决策路径**必须发出其领域 span**,且 **parent 正确**(挂在请求 trace 下,不是孤儿 root)。
- **必须带负例探针证明 gate 会咬人**:故意删掉 span 或断开 parent,测试必须变红。**只测 happy-path 的 conformance 测试不强制任何东西**——它对"漏埋"零敏感。两次运行(正常绿 / 故意破红)都贴出来。
- 断言粒度到属性:领域 span 带规定的枚举/计数/id 属性;`gen_ai.*` generation span 的 parent 是领域 span 而非 root。

### 9.2 gate 必须真在 CI 跑、且能 fail build
- 把 conformance + 类型门禁(§8)接进 CI,**核它真触发**:workflow 放在工具识别的位置(GitHub Actions 只跑**仓库根** `.github/workflows/`,放子目录=静默不跑)、paths filter 覆盖所有该触发的改动、步骤**无 `|| true` / 无 soft-fail**。**在一个真 PR 上验证 gate 确实触发并能挂,别假设。**

### 9.3 每条铁律 → 一个机制,不只散文
- **铁律5(应用代码不 import 厂商 SDK)** → 静态 import 契约强制(各语言 import 守卫见**附录 C**)。让"禁厂商 SDK"是一条会断构建的契约,不是口头约定。
- **铁律4(跨进程传播 traceparent)** → 跨边界 contract / 集成测试断言下游 span 与上游**同 trace_id**。
- **类型纪律(§2)** → 类型检查器进 CI(工具见 §2 附录 A)。
- **孤儿 span 陷阱(可观测性最常见的隐形失败模式,值得点名)**:异步脱离上下文——`create_task` / goroutine / 线程池 / 队列交接——会丢掉 ambient context,子 span 变成孤儿 root,路径"埋了点却不可见"。跨脱离点**捕获并重 attach** context;conformance 测试必须断言异步边界两侧**同 trace_id**。

### 9.4 宪法条款
- 仓库 `AGENTS.md` / `CONTRIBUTING` 写明:**新增 LLM / 工具 / 检索 / 领域决策路径,必须有 parent 正确的领域 span**,指向本 skill。让它成为人 + agent 评审时会对照的成文规则,而非靠记忆。

### 9.5 可执行 conformance 接口

每个接入仓必须在 repo-owned engineering contract 声明:
- `observability_conformance_command`:单一非交互命令,正向全绿 exit 0,任一语义/静态检查失败 exit 非 0,stdout 输出机器可读 JSON summary。
- `observability_conformance_paths`:repo-relative path/glob 列表,覆盖 instrumentation bootstrap、resource/config、LLM/agent/tool/workflow、async worker/streaming 与 conformance fixtures;IaC 用它决定何时触发。

command 必须调用同一 pinned semantic oracle:`references/conformance-profile-v2.json` + `scripts/observability_conformance.py`。<!-- trunk:conformance-profile-v2.json --> 产品仓把真实 spans/resource/process snapshot 归一化后交给 oracle;`run.id` 等高基数关联键不得进入 metric label,该门对普通服务与 GenAI 服务同样生效;async 脱离点必须提供捕获到的 worker/callback span(`async_boundary`、真实 parent、同 trace、`context_restored=true`),不能用 bootstrap bool 代替。`static_guard.semantic_producers` 必须精确等于 profile 钉住的单一 producer,且 `vendor_or_legacy_paths`、`arbitrary_metadata_flatteners` 为空;项目自定义字段 allowlist/一致性键及 forbidden exact/prefix 也只由 profile extension 声明,其中 prefix 扫描完整 snapshot(含 events),避免把 oracle 扩成通用源码 scanner。覆盖:resource ownership、真实 tenant absence/presence、GenAI required/allowed 字段、parent+async propagation、streaming 终态、默认无内容。mutation 至少分别破坏 parent、字段名、tenant boundary、content gate、worker evidence、single producer、vendor/legacy path、metadata flattening、高基数 metric label,每项单独证明 exit 非 0。IaC/delivery 只消费 command、paths、exit code 与 JSON result,**MUST NOT**复制字段清单、解析应用实现或成为语义 source of truth。

**达标线:规范里每一条会被违反且能自动检测的铁律,都要有一个会让 CI 变红的 gate。检测不了的(纯人工判断项)才进人工清单。** 立规范时若只产出文档不产出 gate,等于没立。

---

## §10 接入初始化 checklist(一次性仪式)

> §9 讲"为什么必须有 gate 与 gate 长什么样";本节回答"**什么时候建**":**采纳规范的当天,作为接入仪式的一部分**。实证模式:规范散文被完整搬进项目、gate 排期"以后补"→ 数月后漏埋点/配置漂移才暴露(§9 案例 + 某项目 span 复述噪音在 staging 灌 INFO 数日无人察觉,肉眼看日志才抓到——一条 gate 断言第一次 CI 就会红)。**本 checklist 自包含,不依赖任何编排/流程工具**;若项目另有任务编排体系,由那边引用本节,不反向耦合。

按序走完,每步有完成判据:

| # | 步骤 | 完成判据 |
|---|---|---|
| 1 | **宪法条款**:仓库 AGENTS.md / CONTRIBUTING 写明"新 LLM/工具/检索/领域路径必须有 parent 正确的领域 span",指向本规范 | 条款在 committed tree 里 |
| 2 | **最小 conformance gate**(按语言起手式,见下) | 测试进 CI 且绿 |
| 3 | **负例探针**:故意删 span / 断 parent | gate 变红的运行记录(双跑证据) |
| 4 | **CI wiring 验真** | 一个真 PR 上 gate 真 fail 过一次 |
| 5 | **环境三档矩阵**(§4):dev/staging=DEBUG 可见,prod=INFO 骨架;span 复述导出默认静音 | 部署配置/manifests 里可指认 |
| 6 | **import 守卫**(§9.3/附录 C):禁厂商 SDK 直依赖 | 守卫进 lint/CI |

**最小 conformance gate 起手式(三条断言,语言无关;捕获器按附录 C 选)**:
- ① 一次入站请求产生 server span(root),且业务 id 在 span 属性上;
- ② 该请求路径的日志行携带 trace_id(空 trace_id 的 ERROR = 失败);
- ③ 部署档配置下无 span 复述日志输出(console/logging exporter 静音,§4)。
捕获器按附录 C 选你的语言(进程内 span 捕获器一栏),跑在该语言常规测试载体里;每条断言配一个负例探针。

## 附录 C·埋点与 gate 工具链(选你的语言)

正文(§5.0 auto-instrumentation、§9 import 守卫 / span 捕获器)只给语言无关机制名;具体包名在此一处。**类型检查器见 §2 附录 A,日志接入见 §6 附录 B**(不在此重复)。加一门语言只改本附录。

### 附录 C·Python
- **auto-instrumentation**:`opentelemetry-instrument` + `opentelemetry-instrumentation-{fastapi,requests,sqlalchemy,…}`(零代码产出 HTTP / DB / 框架基线 span)。
- **进程内 span 捕获器**(conformance 测试):`InMemorySpanExporter`(`opentelemetry-sdk` `export.in_memory_span_exporter`)。
- **import 守卫**(强制铁律5):`import-linter` `forbidden_modules`(禁应用层 import 厂商 SDK)。

### 附录 C·Go
- **auto-instrumentation**:`otelhttp` / `otelgrpc` 等 `go.opentelemetry.io/contrib` instrumentation。
- **进程内 span 捕获器**:`tracetest.SpanRecorder`(`go.opentelemetry.io/otel/sdk/trace/tracetest`)。
- **import 守卫**:`depguard`(golangci-lint)禁 import 厂商 SDK 包。

### 附录 C·Java
- **auto-instrumentation**:`-javaagent:opentelemetry-javaagent.jar`(自动织入 HTTP / DB / 框架 span)。
- **进程内 span 捕获器**:`InMemorySpanExporter`(`opentelemetry-sdk-testing`)。
- **import 守卫**:ArchUnit 规则禁应用包依赖厂商 SDK 包。

### 附录 C·Rust
- **auto-instrumentation**:框架中间件(`tower-http` 的 `TraceLayer` 等)+ `tracing` / `tracing-opentelemetry`。
- **进程内 span 捕获器**:自建 in-memory `SpanExporter` 或 `tracing` 测试订阅器捕获导出的 span。
- **import 守卫**:clippy `disallowed-types` / `disallowed-methods`(deny 级)或 `cargo-deny` 禁厂商 SDK crate。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall