OpenTelemetry eBPF 插桩 OBI 1.0 发布：零代码采集指标与 Trace，配置和部署接口有了兼容承诺

原文信息：本文译自 OpenTelemetry 官方博客《OpenTelemetry eBPF Instrumentation reaches v1.0.0》，作者 Tyler Yahn（Splunk），发布于 2026 年 10 月 30 日。原文链接：https://opentelemetry.io/blog/2026/obi-v1-release/ 。原文采用 CC BY 4.0 许可。本文为翻译，文中原有链接已改为文字说明，具体文档请在原文中点击查看；译者在文末补充了译者注。

译者导语：想给线上服务加链路追踪，却没法改代码、没法逐个语言接 SDK？OpenTelemetry eBPF Instrumentation（OBI，前身是 Grafana Beyla）正是为此而生：在 Linux 内核层用 eBPF 抓取请求，零代码产出指标和 Trace。现在它发布了 1.0，配置和部署接口开始有了兼容性承诺，可以认真考虑放进生产环境了。下面是官方发布说明的全文翻译。

我们很高兴地宣布：OpenTelemetry eBPF Instrumentation（简称 OBI）v1.0.0 正式发布！

OBI 能为正在运行的 Linux 应用带来 OpenTelemetry 可观测性，而且无需修改应用源码。它借助 eBPF，再配合针对各语言运行时的插桩（instrumentation），跨服务、跨语言、跨框架采集应用的指标和链路追踪（trace）。你可以先从请求速率、错误、延迟和服务依赖关系看起，随着需求增长再逐步深入。

这个版本兑现了我们为 2026 年定下的头号目标：为 OBI 打下稳定的基础。它凝结了一整年的工作——扩大插桩覆盖面、提高正确性、加强发布工具链，并建立起用户长期运维 OBI 所需的兼容性与遥测迁移规范。

对用户来说，最重要的变化是可预期：升级前知道会发生什么，出现变化时知道该怎么往前走。

OBI 1.0 为配置和部署制定了成文的兼容性承诺（见原文 versioning 文档链接），覆盖 Config v2 及其自动生成的 schema、文档中列出的部署接口，以及受支持的运行环境。

在遥测数据方面，我们承诺的是：随着 OBI 和 OpenTelemetry 演进，始终提供可靠的迁移路径。OBI 输出的遥测数据中，一部分遵循已稳定的语义约定（semantic conventions），另一部分对应的约定仍在制定中，后者会随约定成熟而变化。对于遵循稳定约定的遥测数据，如果实际行为与约定不符，我们也会作为 bug 修正。

为了让这种演进可控，OBI 用一个兼容 Weaver 的 schema 注册表来描述自己输出的遥测数据。OpenTelemetry Weaver 帮助我们定义、校验并评审这些遥测数据是否符合应遵循的约定。对于能够表达的变更，已发布的遥测 schema 会描述版本之间的转换；需要额外操作的变更，则由发布说明和迁移指南加以解释。

对于维护仪表盘、告警和数据处理管道的团队，这意味着可以提前规划升级、有条不紊地适配。我们的承诺是：遥测数据演进时，始终有一条受支持的前进路径，并提供理解和管理这些变化所需的定义、工具和指南。

在这个基础之上，项目在各个方面都取得了长足进展。

• 更广泛地看清应用依赖。 在通往 1.0 的各个版本中，OBI 新增了对 MQTT、NATS、AMQP 1.0、MSSQL、Couchbase、Memcached 和 Aerospike 等系统的插桩。对于运维混合技术栈的团队，这意味着可以用同一种插桩方式了解更多数据库和消息系统的活动。支持矩阵（support matrix）文档列出了每种协议的覆盖范围、Trace 上下文传播能力和限制。

• 更好的 Trace，更有用的服务细节。 HTTP/2 和 gRPC 上下文传播的改进，加强了对已有连接、多路复用流量和单个流上下文的处理。框架路由发现扩展到了 Django、FastAPI、Flask、Rails、.NET 以及多个 PHP 框架。有了路由模板，团队可以区分出慢接口，又不会让每个不同的 URL 都变成一条独立的指标序列。

• 从自动插桩走向贴合业务的洞察。 在受支持的 OpenTelemetry Go Trace API 和 Auto SDK 配置下，OBI 可以采集应用自己创建的 span。Node.js 也新增了可选的手动 span 采集，适用于没有注册 SDK 的应用。这样，开发者可以为业务操作补充细节，周边的自动插桩仍交给 OBI——前提是满足文档中的运行时要求。

• 排查故障时有更多上下文。 Trace 与日志关联（trace-log correlation）能为受支持的应用日志附上 Trace 上下文，帮助团队从一个请求的调用路径直接跳到相关日志。Mattia Meleleo 写过一篇零代码 Trace–日志关联的实操文章，演示了它在两个服务之间的效果以及如何开启。OBI 还新增了 Go、Java、.NET、Node.js 和 Python 的运行时指标，以及 TCP 重传、连接失败等网络指标。运行时指标目前仍是实验特性，能否使用取决于具体运行时和启用的功能。

• 为 AI 应用插桩。 OBI 的覆盖范围扩展到了模型服务商、向量嵌入（embedding）、重排序（reranking）、向量检索和 MCP 交互，包括工具调用与检索的插桩，以及对 OpenAI 兼容网关和 Ollama 的原生支持。这些能力让团队可以把 AI 依赖和应用的其他部分放在一起排查。需要注意，提取详细内容要显式开启载荷采集（payload capture）和相应功能配置，并非所有部署都会自动启用。

1.0 背后的很多工作不像新增一个协议那样显眼，却是运维插桩工具必不可少的。贡献者们加固了解析器，修正了生命周期和导出行为，修复了缓冲区安全和连接中断相关的 bug，并改进了 Trace 的父子关系。发布工具链新增了签名制品、校验和以及软件物料清单（SBOM），验证范围也扩大到更多内核版本和 CPU 架构。这些投入帮助用户评估和运维自己部署的软件。

对现有用户来说，Config v2 是 1.0 的配置契约。它从 v0.11.0 起就已可用，带有自动生成的 schema，以及 obi config validate 和 obi config migrate 两个命令。Config v1 出于向后兼容仍受支持，但已冻结，不再修复问题，也不再加新功能。请按照配置迁移指南操作，检查通过环境变量传入的配置，并先在金丝雀（canary）部署中比对遥测数据，再大范围推广。把 OBI 嵌入 Collector 使用的用户，选版本时还要留意 receiver 单独的 v0 发布线。

如果你是 OBI 新用户，可以先在一台受支持的 Linux 主机或 Kubernetes 集群上，挑一个有代表性的服务试起来。把数据导出到你的 OpenTelemetry Collector 或兼容后端，看看产出的指标和 Trace，再逐步扩大范围。当你需要 OBI 自动观测不到的业务上下文时，各语言的 Agent 和手动插桩依然很有价值。

OBI 起源于 Grafana 捐赠的 Beyla，并在多家组织与更广泛的 OpenTelemetry 社区协作下发布了第一个 alpha 版本。正是这种协作，把项目一路带到了 1.0。

特别感谢以下贡献者，他们长期投入的工作让这个里程碑成为可能：

• Nikola Grcevski 和 Mario Macias：打造了 OBI 的插桩基础，并扩展了运行时支持、服务发现、框架集成和配置。
• Nimrod Avni：配置 schema 生成、Collector 集成、协议覆盖，以及遥测注册表和 Weaver 校验工作。
• Mattia Meleleo：Trace–日志关联、Trace 上下文处理、Go 插桩改进和发布准备。
• Rafael Roquetto：eBPF 基础设施、缓冲区处理、解析器加固和性能优化。
• Giuseppe Ognibene：网络可观测性、BPF 校验器（verifier）测试、运行时指标，以及插桩与导出器的正确性。
• Stephen Lang：加强 CI、集成测试和 ARM 覆盖，并改进了应用插桩。
• Marc Tudurí：扩展协议插桩、Python 异步追踪，以及 Python 和 .NET 运行时指标。
• Haibin Zhang：扩展 GenAI 插桩，包括向量嵌入、重排序、Qwen 和 MCP。

也感谢每一位贡献过代码、评审过变更、改进过文档、报告过 bug 或分享过 OBI 运行经验的社区成员。复现步骤、部署反馈和对异常行为的提问，都帮助我们把项目做得更好。这个版本属于每一位帮助它走到今天的人。

1.0 发布之后，我们将把这股势头转向规划 OBI 在 2027 年的工作——也希望你来一起决定方向。

如果你一直在关注某个 issue，希望支持某种协议或运行时，或者有能让 OBI 在你的环境里更好用的功能需求，请告诉我们：可以在 OBI 的 GitHub 仓库已有 issue 下补充你的使用场景、提交功能请求，或者到 SIG eBPF Instrumentation 的例会上分享想法。说说你想实现什么、眼下被什么卡住、一个好的解决方案能帮你做成什么。

欢迎试用 OBI 1.0，分享你的使用体验，帮我们决定接下来做什么。

译者注

1. OBI 和语言 Agent 怎么选：OBI 在内核层"旁路"观测网络调用，优点是零代码、跨语言、对存量服务和第三方二进制同样有效；局限是看不到函数内部的业务逻辑。常见做法是先用 OBI 铺开 RED 指标（请求速率、错误、延迟）和服务拓扑，再对核心服务补充 Java/Go 等语言 Agent 或手动埋点。
2. 落地前检查内核：eBPF 插桩依赖较新的 Linux 内核和相应权限（通常需要特权容器或 CAP_BPF/CAP_SYS_ADMIN 等能力）。在国内常见的发行版和自建集群上，建议先核对 OBI 文档里的受支持环境，再在测试节点上验证；老内核节点可能无法使用全部功能。
3. 在华为云上的用法：在云容器引擎 CCE 集群中，OBI 可以 DaemonSet 方式部署到节点，把 OTLP 数据发往自建的 OpenTelemetry Collector，再转存到兼容 OTLP 的后端（如应用性能管理 APM 或自建 Jaeger/Prometheus）。从 Config v1 升级的用户，务必先跑一遍 obi config migrate 并在金丝雀节点上比对指标名称和标签，避免已有仪表盘和告警失效。

相关阅读

• OpenTelemetry 版本策略调整：补丁版本也能发安全修复，升级前要查什么：https://bbs.huaweicloud.com/blogs/f237a6c452924797bb2a3555c4c00e58