OpenTelemetry Ruby SDK¶

本文采用 SDK Instrumentation 方式：在应用代码中初始化 OpenTelemetry Ruby SDK，并启用框架插桩库来采集 Rails、Rack、Sinatra 及受支持的 HTTP、数据库等组件调用。框架插桩库可以自动创建 Span，但需要显式接入 SDK；仅安装 Gem 或设置环境变量不会自动开启采集。

按 Ruby 官方文档 当前的状态，Trace 已稳定，Metric 和 Log 仍在开发中。本文仅配置 Trace，通过 OTLP/HTTP + Protobuf 发送到 DataKit，再由 DataKit 上报到 观测云。

Ruby + OpenTelemetry Ruby SDK -> OTLP/HTTP -> DataKit -> 观测云

前置条件¶

• CRuby 3.1 或更高版本，以及 Bundler；具体 Gem 和框架的版本约束以其发布说明和 Gemfile.lock 为准。
• 已有可正常运行的 Ruby 应用，以下以 Rails 为例。
• 已安装 DataKit，并通过目标工作空间的安装命令配置好数据上报地址和 Token。
• 应用能够访问 DataKit 的 HTTP 端口 9529。本文不涉及 Kubernetes。

一、开启 OpenTelemetry 采集器¶

进入 DataKit 配置目录。仅在尚无 opentelemetry.conf 时复制示例，已有配置请在原文件中调整：

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp -n opentelemetry.conf.sample opentelemetry.conf

确认 opentelemetry.conf 包含以下配置。customer_tags 用于保留自定义资源标签：

[[inputs.opentelemetry]]
  customer_tags = ["team"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

应用和 DataKit 在同一主机时可使用 127.0.0.1:9529；分开部署时，需修改 DataKit 主配置 datakit.conf 中的 [http_api].listen 为应用可访问的监听地址，并配置网络访问控制。HTTP 监听地址不在 opentelemetry.conf 中设置。

重启并检查 DataKit：

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

/v1/ping 仅验证 DataKit HTTP 服务可达，不能证明链路已入库。完整配置参见 OpenTelemetry 采集器和 DataKit 主配置。

二、应用接入 OpenTelemetry¶

安装依赖¶

在应用根目录执行，依赖会写入 Gemfile。提交并部署更新后的 Gemfile 和 Gemfile.lock，确保生产环境也安装这些 Gem：

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

初始化 SDK 和框架插桩¶

新增 config/initializers/opentelemetry.rb：

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

c.use_all 启用已安装且与应用依赖兼容的插桩。示例通过环境变量设置服务名，因此无需额外写入 c.service_name。如果已有 SDK 初始化逻辑，请合并到同一处，避免重复初始化。

非 Rails 应用应在启动阶段尽早加载上述配置，并遵循对应框架插桩库的加载顺序。opentelemetry-instrumentation-all 不会为不受支持的库或任意业务方法自动创建 Span；支持范围参见 Ruby 插桩库。

配置并启动应用¶

在启动应用的同一终端设置以下环境变量；跨主机部署时，把 127.0.0.1 替换为应用可访问的 DataKit 地址：

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:9529/otel/v1/traces"
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_TRACES_SAMPLER="parentbased_always_on"

bundle exec rails server -b 127.0.0.1 -p 3000

示例使用 Rails 开发服务器验证接入。生产环境请将环境变量配置到实际的 systemd、进程管理器或部署配置中，并重启所有应用进程；不要只在交互式终端设置。

本文使用的 opentelemetry-exporter-otlp 是 HTTP/Protobuf Exporter，不能通过将协议改为 grpc 并使用 4317 端口来切换为 gRPC。

三、数据上报参数¶

生产环境可改用比例采样：

export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

0.1 表示约 10% 的根链路被采样，子 Span 仍遵循父级采样决定。环境变量必须在 SDK 初始化前生效。

本文未安装或配置 Log、Metric 导出管道，也不保证设置其他语言的信号开关即可启用它们。应用日志可单独使用 DataKit 日志文件采集；若需与链路关联，需在日志中写入当前 Span 的 Trace ID，并通过 Pipeline 解析为 trace_id。

验证与排查¶

1. 访问应用中真实存在的业务接口，触发受支持的 Web、HTTP 或数据库调用；仅启动进程不一定产生 Span。
2. 等待批量导出后，在 观测云 应用性能监测中按服务名 order-service 查询链路。
3. 没有数据时，先用 OTEL_TRACES_EXPORTER=console 重启应用并再次请求；有 Span 输出说明插桩已生效，排查后恢复为 otlp。
4. 有 Span 但上报失败时，检查 DataKit 采集器是否启用、HTTP 地址是否包含 /otel/v1/traces、应用进程是否继承环境变量，以及应用与 DataKit 的错误日志。
5. 短生命周期脚本结束前应调用 OpenTelemetry.tracer_provider.shutdown，等待缓冲数据导出；强制终止进程可能丢失尚未发送的 Span。

参考文档¶

• OpenTelemetry Ruby
• Ruby 入门
• Ruby 插桩库
• Ruby Exporter