計装ライブラリの使用

アプリを開発する際、作業を加速するためにサードパーティのライブラリやフレームワークを使用することがあるでしょう。 OpenTelemetryを使用してアプリを計装する場合、使用するサードパーティのライブラリやフレームワークにトレース、ログ、メトリクスを手動で追加するために時間を費やすことを避けたいことがあります。

多くのライブラリやフレームワークはすでにOpenTelemetryをサポートしているか、OpenTelemetryの計装を介してサポートされているため、テレメトリーを生成してオブザーバビリティバックエンドにエクスポートできます。

サードパーティのライブラリやフレームワークを使用しているアプリやサービスを計装する場合は、このページの手順に従って、ネイティブに計装されたライブラリと依存関係の計装ライブラリの使用方法を学んでください。

ネイティブに計装されたライブラリを使用する

デフォルトでOpenTelemetryサポートが付属しているライブラリの場合、アプリにOpenTelemetry SDKを追加して設定することで、そのライブラリから発行されるトレース、メトリクス、ログを取得できます。

ライブラリによっては、計装のために追加の構成が必要な場合があります。 詳細はライブラリごとのドキュメントをご覧ください。

• Elasticsearch Ruby Client

計装ライブラリの使用

ライブラリにOpenTelemetryが組み込まれていない場合は、計装ライブラリを使用して、ライブラリやフレームワークのテレメトリーデータを生成できます。

たとえば、Railsを使用していて、opentelemetry-instrumentation-railsを有効にしている場合、実行中のRailsアプリはコントローラーへの受信リクエストのテレメトリーデータを自動的に生成します。

すべての計装ライブラリの構成

OpenTelemetry Rubyは、Rubyベースのすべての計装ライブラリを単一のパッケージにバンドルしたメタパッケージである opentelemetry-instrumentation-all を提供します。 最小限の労力で、すべてのライブラリのテレメトリーを追加するための便利な方法です。

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

アプリケーションライフサイクルの早いタイミングで構成します。 Railsのイニシャライザーを使用した下記の例を参照してください。

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.use_all() # すべての計装を有効化します！
end

このコードにより、すべての計装ライブラリがインストールされ、アプリで使用しているライブラリに一致するものが有効になります。

特定の計装ライブラリの構成を上書きする

すべての計装ライブラリを有効化しつつ、特定の計装ライブラリの構成を上書きしたい場合は、構成マップパラメーターを使用して use_all を呼び出します。 キーはライブラリを表し、値はその特定の構成パラメーターです。

たとえば、Redis 計装を 除く すべての計装をアプリにインストールする方法は次のとおりです。

require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  config = {'OpenTelemetry::Instrumentation::Redis' => { enabled: false }}
  c.use_all(config)
end

さらに多くの計装を上書きするには、config マップに別のエントリを追加します。

環境変数を使用して特定の計装ライブラリの構成を上書きする

環境変数を使用して、特定の計装ライブラリを無効化することもできます。 環境変数によって無効化された計装は、ローカル構成よりも優先されます。 環境変数の命名規則は、ライブラリ名を大文字にして :: をアンダースコアに置き換え、OPENTELEMETRY を OTEL_LANG に短縮し、最後に _ENABLED を追加したものです。

たとえば、OpenTelemetry::Instrumentation::Sinatra の環境変数名は OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED です。

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false

特定の計装ライブラリの構成

より選択的に特定の計装ライブラリのみをインストールして使用することもできます。 たとえば、Sinatra と Faraday のみを使用し、Faraday に追加の構成パラメーターを設定する方法は次のとおりです。

はじめに、使用したい特定の計装ライブラリをインストールします。

gem install opentelemetry-instrumentation-sinatra
gem install opentelemetry-instrumentation-faraday

次に、それらを構成します。

require 'opentelemetry/sdk'

# デフォルト構成で、互換性のあるすべての計装をインストールします
OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::Sinatra'
  c.use 'OpenTelemetry::Instrumentation::Faraday', { opt: 'value' }
end

環境変数を使用して特定の計装ライブラリを構成する

環境変数を使用して、特定の計装ライブラリのオプションを定義することもできます。 例によって、環境変数は計装の名前を大文字にして :: をアンダースコアに置き換え、OPENTELEMETRY を OTEL_{LANG} に短縮し、最後に _CONFIG_OPTS を追加したものです。

たとえば、OpenTelemetry::Instrumentation::Faraday の環境変数名は OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS です。 peer_service=new_service;span_kind=client の値は、前のセクションでFaradayに設定されたオプションを上書きします。

export OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS="peer_service=new_service;span_kind=client"

次の表は、オプションのデータ型に応じた許容される値の形式を示しています。

次のステップ

計装ライブラリは、Rubyアプリに関する多くの有用なテレメトリーデータを生成する最も簡単な方法です。 しかし、アプリケーションロジック特有のデータは生成しません。 そのためには、計装コードを使用して、計装ライブラリからの計装を強化する必要があります。