OpenTelemetry best practices: A user's guide to getting started with OpenTelemetry 未开始

题记与说明

这篇讲什么

Grafana Labs 官方的 OpenTelemetry 落地实践指南，整理自高频用户提问、社区讨论与内部经验。全文约 12 个主题，每节以一句 TL;DR 开头，覆盖：自动/手动插桩取舍、初始化顺序、属性设计、语义约定、三种遥测数据的关联、批处理、采样策略、Span Events、Context Propagation 与 Baggage、Span Metrics 生成 RED 指标、Collector 架构与 Exporter。

核心观点

1. 自动插桩优先：先用 auto-instrumentation 拿到基础覆盖，发现缺口再针对性补手动插桩，不要一上来就手写 span。
2. 属性要克制、要标准化：只加与当前 span 操作相关的属性，拿不准就不加——以后总能再补；尽早采用 OTel 语义约定（semantic conventions），命名用描述性词汇并统一风格。
3. 采样没有万能答案：head sampling（可远程控制）搭配概率性 tail sampling，对多数场景已够用；代价是引入偏差、丢失排障所需上下文。
4. 一定要上 Collector：集中做批处理、压缩、转换和密钥管理；"直连 OTLP endpoint"只建议在测试或小规模开发中使用。
5. Span Metrics 是性价比之王：用 spanmetrics/servicegraph connector 从 trace 自动生成 RED 指标。关键坑：指标必须在采样之前生成——tail sampling 之后再算，10% 采样就只反映 10% 的流量；而 head sampling 的 span 在应用内就被丢弃，根本到不了 Collector。

最值得记住的金句与数据

• "If in doubt, start with auto-instrumentation… and take away what you do not need."（先自动、缺再手补）
• "If you are unsure whether or not to include an attribute, it is always better to err on the side of caution and leave it out. You can always add more attributes later!"
• 10% 概率采样 = 指标只覆盖 10% 的 trace estate；head sampling 的数据在应用代码里就被丢掉，永远不会到达 Agent/Collector。

对我的启发

• Agent 系统天然适合这套模型：一次 Agent 运行就是一条 trace，每次工具调用/LLM 调用是一个 span；"日志里记 traceID、三种遥测可互跳"的关联设计，可以直接搬去做 Agent 的运行记录、回放与排障；RED 指标（请求率/错误率/耗时）同样适合衡量 Agent 工具调用的健康度。
• "自动优先、按需精调"是通用的工具引入策略，与 AI 编程工具的用法一致：先吃满默认能力，再对热点路径手动加码。
• "拿不准就不加"是数据极简主义，个人知识管理同理：宁缺勿滥，防止垃圾字段与无效笔记膨胀；但注意"以后可以再加"的前提是数据源还在。

适合谁读

准备把服务接入 OTel / Prometheus / Grafana / Tempo 生态的后端与平台工程师、SRE；正在选型 APM、想避免供应商锁定的团队；以及想为 Agent / LLM 系统设计可观测性、想直接借鉴一套成熟语义约定与采样权衡方案的人。