Ruby 源码接入¶

Beacon Ruby 是基于 OpenTelemetry Ruby Contrib 的插桩源码项目。应用通过源码引用所需的插桩 gem，并显式初始化 OpenTelemetry SDK，使用 OTLP HTTP/protobuf 导出链路。

Beacon Ruby 保留上游 gem 标识，以源码包形式发布。它不提供独立的 beacon-ruby gem、可执行 Agent 或零代码预加载入口，不能仅通过设置环境变量开启采集。

前置条件¶

安装项目支持的 Ruby 工具链和 Bundler，并确保可访问 GitHub 和 RubyGems。运行环境要求见源码安装指南。
本地链路验证需要 Linux、Python 和 Docker。按源码包内的验收说明提前下载验证脚本使用的 Collector 镜像。

下载与安装¶

从 Beacon Ruby 发布页面选择发行源码，将源码归档、SOURCE.txt 和 SHA256SUMS 下载到同一新目录。
在下载目录校验文件：
```
sha256sum -c SHA256SUMS
```
确认校验通过后再解压源码归档，进入源码根目录。SOURCE.txt 记录源码提交与上游基线；源码包包含许可证，依赖需另外安装。

应用集成可参考源码包内的 Gemfile：从同一份 Beacon 源码引用 opentelemetry-instrumentation-base 和 opentelemetry-instrumentation-net_http，并使用所选发行源码匹配的 opentelemetry-sdk、opentelemetry-exporter-otlp 依赖。调整源码路径为应用实际部署位置，提交应用的 Gemfile 和 Gemfile.lock。

直接从 RubyGems 安装同名插桩 gem 会选择上游包；应检查 Bundler 的依赖来源，确认应用加载的是选定的 Beacon 源码。

初始化 SDK¶

在应用启动阶段加载所需库，再初始化 SDK 并启用 Net::HTTP 插桩：

require 'bundler/setup'
require 'net/http'
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'
require 'opentelemetry-instrumentation-net_http'

OpenTelemetry::SDK.configure do |config|
  config.service_name = 'my-ruby-service'
  config.use 'OpenTelemetry::Instrumentation::Net::HTTP'
end

将此配置合并到应用现有的初始化逻辑中，避免重复初始化 SDK。插桩库只为经过受支持库的调用创建 Span，不会自动覆盖任意业务方法。根 Span、请求及退出前刷新示例见源码包内的 Ruby 示例。

验证 Net::HTTP 链路¶

先用随源码提供的验证脚本确认依赖和插桩路径。在源码根目录执行：

cd beacon/validation
BUNDLE_FROZEN=true bundle install
BUNDLE_FROZEN=true python3 collector_smoke.py

脚本使用锁定的依赖和 Collector 镜像，启动临时 HTTP 服务与本地 OpenTelemetry Collector，执行插桩后的 Ruby HTTP 请求。它检查服务名 beacon-ruby-import-smoke、一个根 Span 和一个 HTTP 客户端 Span，以及两者相同的 Trace ID 和父子关系。成功时输出：

Collector received the service identity and correlated root/client spans.

脚本结束后会清理临时服务、容器和链路输出。此流程验证合成请求到达本地 Collector，不代表生产后端已经入库。

接收端与能力范围¶

已发布的验收记录覆盖基础插桩库、Net::HTTP 语义模式，以及 OTLP HTTP/protobuf 到本地 Collector 的 Trace 导出。Rails、其他集成、DataKit、Metric、Log、Profile 和 Security 尚不在已验证范围内。

如需将链路上报到观测云，可参照公共配置开启 DataKit OpenTelemetry HTTP 接收端，并按 OpenTelemetry Ruby SDK说明配置 HTTP/protobuf 导出地址。SDK 初始化仍需保留。DataKit 接入需要在实际应用环境中单独验证，不能将本地 Collector 验证结果视为 DataKit 入库证明。

验证时产生真实 Net::HTTP 请求，再进入观测云「应用性能监测 > 链路」，按配置的服务名筛选，检查 Trace、Span 和父子关系。

升级与回滚¶

每份发行源码使用独立目录，保留已校验的归档、校验文件、SOURCE.txt、应用 Gemfile、锁文件和 SDK 初始化配置。升级时先阅读发布说明，并验证所需插桩路径。

回滚时恢复此前的源码引用、依赖及初始化配置，重启应用并重新验证遥测数据。更多说明见源码安装指南。