Application Real-Time Monitoring Service:OpenTelemetry を使用した Ruby トレースデータのレポート

サポートされているフレームワーク

自動計測は、以下を含む広範囲の Ruby ライブラリをカバーしています。

完全なリストについては、「OpenTelemetry Ruby contrib リポジトリ」をご参照ください。

ステップ 1：Rails プロジェクトの作成

すでに Rails アプリケーションをお持ちの場合は、このステップをスキップします。

gem install rails
rails new <your-project-name>
cd <your-project-name>

<your-project-name> をご利用のアプリケーション名に置き換えます (例：rails new otel-demo)。

Rails is not currently installed on this system というエラーが表示された場合は、ターミナルを閉じて再度開き、コマンドを再度実行してください。

ステップ 2：OpenTelemetry gem の追加

これらの行をプロジェクトの Gemfile に追加します。

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

次に、依存関係をインストールします。

gem install bundler   # Bundler がすでにインストールされている場合はスキップします
bundle install

ステップ 3：OpenTelemetry SDK の設定

config/initializers/opentelemetry.rb を作成します。

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: '<endpoint>' # ご利用の OpenTelemetry HTTP エンドポイントに置き換えます。
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::HOST_NAME => '<your-host-name>',
  })
  c.service_name = '<your-service-name>'
  c.use_all() # Enable auto-instrumentation for all supported libraries.
end

プレースホルダーを実際の値に置き換えます。

ステップ 4：アプリケーションの開始

rails server

期待される出力：

* Puma version: 5.6.5 (ruby 2.7.2-p137) ("Birdie's Version")
*  Min threads: 5
*  Max threads: 5
*  Environment: development
*          PID: 79842
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

ステップ 5：データレポートの検証

ブラウザで http://127.0.0.1:3000 を開きます。ターミナルに次のログ出力が表示された場合、トレースデータは OpenTelemetry 向けマネージドサービスにエクスポートされています。

Started GET "/" for 127.0.0.1 at 2023-01-01 10:00:00 +0800
Processing by Rails::WelcomeController#index as HTML
  Rendering /Users/username/.rvm/gems/ruby-2.7.2/gems/railties-7.0.4.3/lib/rails/templates/rails/welcome/index.html.erb
  Rendered /Users/username/.rvm/gems/ruby-2.7.2/gems/railties-7.0.4.3/lib/rails/templates/rails/welcome/index.html.erb (Duration: 0.8ms | Allocations: 665)
Completed 200 OK in 6ms (Views: 2.1ms | ActiveRecord: 0.0ms | Allocations: 5440)

ステップ 1：依存関係のインストール

次の OpenTelemetry 依存関係をインストールします。

gem install opentelemetry-api
gem install opentelemetry-sdk
gem install opentelemetry-exporter-otlp

ステップ 2：SDK の初期化

ファイル (例：manual.rb) を作成し、OTLP エクスポーターを設定します。BatchSpanProcessor はスパンをバッファーし、バッチで送信してパフォーマンスを向上させます。

require 'opentelemetry/sdk'
require 'opentelemetry-exporter-otlp'

OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: '<endpoint>' # ご利用の OpenTelemetry HTTP エンドポイントに置き換えます。
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAMESPACE => 'tracing',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => '<your-service-name>',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })
end

プレースホルダーを置き換えます。

ステップ 3：スパンの作成

トレーサーを取得し、スパンを作成します。

tracer = OpenTelemetry.tracer_provider.tracer('<your-tracer-name>', '0.1.0')

tracer.in_span('parent_span') do |parent_span|
  # ここにアプリケーションロジックを記述します。
end

トレーサー名は、ARMS コンソールで計測ライブラリを識別します。トレースされるコンポーネントを説明する名前を選択します (例：'order-service' または 'payment-processor')。

ステップ 4：属性の追加とスパンコンテキストの読み取り

スパンブロック内で、属性を追加し、トレース ID とスパン ID を取得します。

tracer.in_span('parent_span') do |parent_span|
  current_span = OpenTelemetry::Trace::current_span
  current_span.set_attribute('key', 'value')
  pp current_span.context.trace_id
  pp current_span.context.span_id
end

ステップ 5：ネストされたスパンの作成

操作間の親子関係を表すために、in_span 呼び出しをネストします。

tracer.in_span('parent_span') do |parent_span|
  # 親スパンロジック。
  tracer.in_span('child_span') do |child_span|
    current_span = OpenTelemetry::Trace::current_span
    pp current_span  # これは子スパンです。
  end
end

完全な例

この例は、スパン作成、属性、イベント、ネストされたスパン、およびエラー処理を単一のスクリプトでカバーしています。

require 'opentelemetry/sdk'
require 'opentelemetry-exporter-otlp'

OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: '<endpoint>' # ご利用の OpenTelemetry HTTP エンドポイントに置き換えます。
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAMESPACE => 'tracing',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => 'ruby_demo',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })

  # または、Resources API を使用せずにサービス名を設定します。
  # c.service_name = 'ruby_demo'
end

tracer = OpenTelemetry.tracer_provider.tracer('instrumentation_library_name', '0.1.0')

tracer.in_span('parent_span') do |parent_span|
  # スパン属性を設定します。
  parent_span.set_attribute('language', 'ruby')
  parent_span.set_attribute("attribute_key", ["attribute_value1", "attribute_value1", "attribute_value1"])

  # スパンイベントを追加します。
  parent_span.add_event("event", attributes: {
    "pid" => 1234,
    "signal" => "SIGHUP"
  })

  # トレース ID とスパン ID を読み取ります。
  current_span = OpenTelemetry::Trace::current_span
  pp current_span.context.trace_id
  pp current_span.context.span_id

  tracer.in_span('child_span') do |child_span|
    child_span.add_attributes({
      "key1" => "value1",
      "key2" => "value2"
    })

    child_span.add_event("mock exception here")

    begin
      raise 'An error has occurred'
    rescue
      # スパンをエラーとしてマークします。
      child_span.status = OpenTelemetry::Trace::Status.error("error in child span")
    end

    pp child_span
  end
end

sleep 10

アプリケーションを実行します。

ruby manual.rb