OpenTelemetry Ruby SDK¶

この記事では、SDK インストルメンテーション方式を採用します。アプリケーションコードで OpenTelemetry Ruby SDK を初期化し、フレームワークのインストルメンテーションライブラリを有効化して、Rails、Rack、Sinatra、およびサポート対象の HTTP、データベースなどのコンポーネント呼び出しを収集します。フレームワークのインストルメンテーションライブラリは Span を自動生成できますが、SDK への明示的な接続が必要です。Gem をインストールするか環境変数を設定するだけでは、自動的に収集は開始されません。

Ruby 公式ドキュメント の現在の状況によると、トレースは安定しており、メトリクスとログはまだ開発中です。この記事ではトレースのみを設定し、OTLP/HTTP + Protobuf で DataKit に送信して、DataKit から Guance に送信します。

Ruby + OpenTelemetry Ruby SDK -> OTLP/HTTP -> DataKit -> Guance

前提条件¶

• CRuby 3.1 以降と Bundler が必要です。各 Gem およびフレームワークのバージョン制約は、それぞれのリリースノートと Gemfile.lock に従います。
• 正常に動作する Ruby アプリケーションが必要です。以下では Rails を例に説明します。
• DataKit をインストールし、対象ワークスペースのインストールコマンドでデータ送信先アドレスと Token を設定しておいてください。
• アプリケーションから DataKit の HTTP ポート 9529 にアクセスできる必要があります。この記事では Kubernetes は扱いません。

1. 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 メイン設定 を参照してください。

2. アプリケーションへの 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 に切り替えることはできません。

3. データ送信パラメータ¶

本番環境では比率サンプリングに切り替えることもできます。

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

0.1 は、ルートトレースの約 10% がサンプリングされることを示します。子 Span は引き続き親のサンプリング決定に従います。環境変数は SDK の初期化前に有効である必要があります。

この記事ではログとメトリクスのエクスポートパイプラインはインストールも設定も行いません。また、他の言語のシグナルスイッチを設定するだけでそれらが有効になることも保証しません。アプリケーションログは単独で DataKit の ログファイル収集 を使用できます。トレースと関連付ける場合は、ログに現在の Span の Trace ID を書き込み、Pipeline で trace_id として解析する必要があります。

検証とトラブルシューティング¶

1. アプリケーション内の実際に存在する業務インターフェースにアクセスし、サポート対象の Web、HTTP、またはデータベース呼び出しを発生させます。プロセスを起動するだけでは Span が生成されるとは限りません。
2. バッチエクスポートを待った後、Guance アプリケーションパフォーマンスモニタリング（APM）でサービス名 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