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、1 つのルート Span、1 つの 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 は検証範囲に含まれていません。

Guanceにトレースを送る場合は、共通設定で DataKit OpenTelemetry HTTP 受信を有効にし、OpenTelemetry Ruby SDKに従って HTTP/protobuf のエクスポート先を設定します。SDK の初期化は引き続き必要です。DataKit との接続は実際のアプリケーション環境で別途検証してください。ローカル Collector の検証結果は DataKit への保存を証明しません。

実際の Net::HTTP リクエストを発生させ、Guanceの「APM > トレース」で設定したサービス名を検索します。Trace、Span、親子関係を確認してください。

更新とロールバック¶

ソース配布物ごとに独立したディレクトリを使用します。検証済みアーカイブ、チェックサム、SOURCE.txt、アプリケーションの Gemfile、ロックファイル、SDK 初期化設定を保持してください。更新前にリリースノートを確認し、必要な計装経路を検証します。

ロールバック時は以前のソース参照、依存関係、初期化設定に戻し、アプリケーションを再起動してテレメトリを再検証します。詳細はソースインストールガイドを参照してください。