observability-standard

可观测性与工程规范

何时应用

写或评审任何后端服务的代码时应用 —— 普通微服务(auth / 网关 / 业务服务)与 agent / 多 agent / RAG 知识库项目一视同仁,尤其涉及:日志接入、OpenTelemetry 埋点、跨进程 context 传播、日志级别选择、跨 trace/log/db 排障、边界数据建模;agent 场景额外涉及编排与子 agent、LLM/工具/检索调用。Python / Go / Java / Rust 通用。即使用户只说"加点日志""接一下 trace""这个错查不到""这请求怎么追",也按本规范做。

总纲

用一条关联主线贯穿定位:trace_id 串起 trace + log;业务库这一环靠**业务 id 同时挂成 span 属性(order.id / run.id)**双向关联,不在业务行存 trace_id(trace 受采样 / 短保留,持久行存它多半是死指针 —— 见 references §2.1)。定位永远是 trace 或业务 id → 查 trace 看哪步 → 查 log 看为什么 → 按业务 id 查 db 看数据对不对,不靠时间戳猜。

五条铁律(所有服务,全部遵守)

1. 一次对外请求 = 一棵 trace。入站请求 handler 是 root span,所有下游(DB / 缓存 / 跨进程调用 —— agent 场景下还有子 agent / LLM / 工具 / 检索)都是子 span。
2. 宽事件优先:每步一条富字段结构化事件;事件名是稳定可聚合标识符,变量进字段;不写散文。
3. 三信号可关联:每条 log 带 trace_id+span_id(随 trace 同采样 / 保留);业务 id 挂成 span 属性以按业务 id 反查 trace,不往业务行加 trace_id 列;需持久溯源处(AI 决策 / 金额 / 对客输出 / 合规)落自己拥有的 correlation_id,优先进专用审计 / outbox 表(见 references §2.1)。
4. 跨进程必传播 W3C traceparent(HTTP / gRPC / 消息队列 / 任何 agent 协议都算)。不传 = trace 断成多棵互不相连的树 = 跨服务定位失效。优先级高于功能。
5. 标准在边界 + 后端无关:跨进程 / 对外响应遵守 OTel 语义约定 + 类型校验(LLM 边界额外遵守 GenAI 约定);内部自由。只依赖 OTel API/SDK + OTLP,应用代码不 import 厂商 SDK(Langfuse / Datadog 等);标准组件优先用官方 auto-instrumentation 自动埋点,手写 span 只补领域环节;厂商差异只在 Collector / exporter 配置层 → 换后端不重埋(见 references §1 铁律5 / §5.0 / 附录 C)。

日志铁律

• 结构化优先:event_name + fields,绝不字符串拼接。日志即数据,不即叙事。宽事件 ≠ JSON:稳定可解析的行式字段格式即可,不强制 JSON 序列化(有实打实的计算开销;日志管道需要机器解析时再升,升级只动导出层配置)。
• 日志在活跃 span 内打出,trace_id/span_id 自动注入;没有 trace_id 的 ERROR 视为 bug。
• 上下文绑一次贯穿全程(语言原生 ambient context 机制,见 references 附录 B),不手传。
• 不要 log-and-throw;密钥/PII/客户机密在边界脱敏;明文 prompt/completion = 数据披露闸(显式 flag + 非 prod + 脱敏;audit 仅哈希),非日志级别。
• 统一 named logger 树(语言原生 per-module logger 机制,见 references 附录 B),级别由配置控,不用环境变量单独门控某条日志。
• 必记(≥ INFO):决策点 + 依据、状态转移、每次跨进程 / LLM / 工具 / 检索调用的边界与结果状态、重试/回退/降级/补偿、每步 token + 成本(agent 场景)。

日志级别判据

判据:这条日志在正常生产运行里读它有意义吗? 有 → INFO;只有出问题深挖才看 → DEBUG。

• INFO 重建"发生了什么"的骨架(每步 / 每次调用 / 每次状态转移一条,不刷高频内循环)。
• DEBUG 重建"为什么"的细节(完整 prompt、推理、原始响应、命中 chunk、跨进程报文全文),生产默认关、可按 trace 动态开。
• ERROR = 失败且影响本次结果,必带 trace + 操作 + 输入标识符 + 栈;WARNING = 降级但请求继续。
• 排障时"光看 INFO 不知走到哪步" → 补 INFO,别常开 DEBUG。
• span 导出日志不是应用日志:trace 信号走 OTLP;console/logging 型 span exporter(各语言 OTel SDK 均有)仅 dev 验证用,部署环境把其 logger 类别阈值默认压到 WARN(此类行每请求复述一条且无请求上下文,是双写噪音)。
• 环境三档矩阵(默认形状):dev = DEBUG(代码内默认,开发就近调试)· staging = DEBUG(部署层配置开)· prod = INFO 骨架(默认安静侧);span 导出行随档位:dev/staging 可见、prod 隐藏。
• 配置分工:语义级别(哪条算 INFO/DEBUG)归代码且默认取安静侧;级别阈值按环境开归部署层运行时配置(rationale 与各语言机制见 references §4);prod 静音 span 导出前确认已有真 OTLP sink,否则 trace 信号整体丢失。