OpenTelemetry Ruby への移行

X-Ray SDK for Ruby では、サービスプラグインを使用してコードを設定する必要がありました。

require 'aws-xray-sdk'

XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk])
        

Ruby on Rails アプリケーションの場合は、設定コードを Rails イニシャライザに配置します。詳細については、「 の使用開始」を参照してください。手動で計装されたすべての Ruby プログラムでは、OpenTelemetry::SDK.configure メソッドを使用して OpenTelemetry Ruby SDK を設定する必要があります。

まず、以下のパッケージをインストールします。

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray
        

次に、プログラムが初期化されたときに実行される設定コードを使用して OpenTelemetry SDK を設定します。以下のコンポーネントを設定することをお勧めします。

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

# Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator
require 'opentelemetry-propagator-xray'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-service-name'

  c.add_span_processor(
    # Use the BatchSpanProcessor to send traces in groups instead of one at a time
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      # Use the default OLTP Exporter to send traces to the ADOT Collector
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        # The OpenTelemetry Collector is running as a sidecar and listening on port 4318
        endpoint:"http://127.0.0.1:4318/v1/traces"
      )
    )
  )
  
  # The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls
  c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new]
end
        

OpenTelemetry SDK には、ライブラリ計装の概念もあります。これらを有効にすると、 AWS SDK などのライブラリのスパンが自動的に作成されます。OpenTelemetry には、すべてのライブラリ計装を有効にするか、どのライブラリ計装を有効にするかを指定するオプションがあります。

すべての計装を有効にするには、まず opentelemetry-instrumentation-all パッケージをインストールします。

bundle add opentelemetry-instrumentation-all
        

次に、設定を以下のように更新して、すべてのライブラリ計装を有効にします。

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDK には、ライブラリ計装の概念もあります。これらを有効にすると、 AWS SDK などのライブラリのスパンが自動的に作成されます。OpenTelemetry には、すべてのライブラリ計装を有効にするか、どのライブラリ計装を有効にするかを指定するオプションがあります。

すべての計装を有効にするには、まず opentelemetry-instrumentation-all パッケージをインストールします。

bundle add opentelemetry-instrumentation-all
        

次に、設定を以下のように更新して、すべてのライブラリ計装を有効にします。

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

X-Ray SDK では、X-Ray トレースは初期化時に Rails フレームワーク用に設定されます。

例 – config/initializers/aws_xray.rb

Rails.application.config.xray = {
  name: 'my app',
  patch: %I[net_http aws_sdk],
  active_record: true
}
        

まず、以下のパッケージをインストールします。

bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view
        

次に、以下に示すように、Rails アプリケーションの計装を有効にするように設定を更新します。

# During SDK configuration
OpenTelemetry::SDK.configure do |c|

  ...

  c.use 'OpenTelemetry::Instrumentation::Rails'
  c.use 'OpenTelemetry::Instrumentation::Rack'
  c.use 'OpenTelemetry::Instrumentation::ActionPack'
  c.use 'OpenTelemetry::Instrumentation::ActiveSupport'
  c.use 'OpenTelemetry::Instrumentation::ActionView'
  
  ...
  
end

AWS SDK からの送信 AWS リクエストを計測するために、 AWS SDK クライアントには次の例のように X-Ray のパッチが適用されます。

require 'aws-xray-sdk'
require 'aws-sdk-s3'

# Patch AWS SDK clients
XRay.recorder.configure(plugins: [:aws_sdk])

# Use the instrumented client
s3 = Aws::S3::Client.new
s3.list_buckets
        

AWS SDK for Ruby V3 は、OpenTelemetry トレースの記録と出力をサポートします。サービスクライアントの OpenTelemetry を設定する方法については、 AWS SDK for Ruby の「オブザーバビリティ機能の設定」を参照してください。

ダウンストリームコールを計装する際、X-Ray SDK for Ruby は、アプリケーションで使用する net/http ライブラリにパッチを適用するために使用されました。

require 'aws-xray-sdk'

config = {
  name: 'my app',
  patch: %I[net_http]
}

XRay.recorder.configure(config)
        

OpenTelemetry を使用して net/http 計装を有効にするには、まず opentelemetry-instrumentation-net_http パッケージをインストールします。

bundle add opentelemetry-instrumentation-net_http
        

次に、以下のように設定を更新して net/http 計装を有効にします。

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

  c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
  ...

end
        

X-Ray を使用して、アプリケーションを追跡するセグメントとその子サブセグメントを手動で作成するには、aws-xray-sdk パッケージが必要でした。セグメントまたはサブセグメントに X-Ray 注釈とメタデータを追加する場合もありました。

require 'aws-xray-sdk'
...

# Start a segment
segment = XRay.recorder.begin_segment('my-service')

# Add annotations (indexed key-value pairs)
segment.annotations[:user_id] = 'user-123'
segment.annotations[:payment_status] = 'completed'

# Add metadata (non-indexed data)
segment.metadata[:order] = {
  id: 'order-456',
  items: [
    { product_id: 'prod-1', quantity: 2 },
    { product_id: 'prod-2', quantity: 1 }
  ],
  total: 67.99
}

# Add metadata to a specific namespace
segment.metadata(namespace: 'payment') do |metadata|
  metadata[:transaction_id] = 'tx-789'
  metadata[:payment_method] = 'credit_card'
end

# Create a subsegment with annotations and metadata
segment.subsegment('payment-processing') do |subsegment1|
  subsegment1.annotations[:payment_id] = 'pay-123'
  subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' }
  
  # Create a nested subsegment
  subsegment1.subsegment('operation-2') do |subsegment2|
    # Do more work...
  end
end

# Close the segment
segment.close
        

カスタムスパンを使用すると、計装ライブラリでキャプチャされない内部アクティビティのパフォーマンスをモニタリングできます。Server タイプのスパンのみが X-Ray セグメントに変換され、他のすべてのスパンは X-Ray サブセグメントに変換されることに注意してください。デフォルトでは、スパンは INTERNAL です。

まず、OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') メソッドで取得できるスパンを生成するためにトレーサーを作成します。これにより、アプリケーションの OpenTelemetry 設定にグローバルに登録されているトレーサーインスタンスが提供されます。アプリケーション全体で 1 つのトレーサーを持つことが一般的です。OpenTelemetry トレーサーを作成し、それを使用してスパンを作成します。

require 'opentelemetry-sdk'

...

# Get a tracer
tracer = OpenTelemetry.tracer_provider.tracer('my-application')

# Create a server span (equivalent to X-Ray segment)
tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
  # Do work...
  
  # Create nested spans of default kind INTERNAL will become an X-Ray subsegment
  tracer.in_span('operation-1') do |child_span1|
    # Set attributes (equivalent to X-Ray annotations and metadata)
    child_span1.set_attribute('key', 'value')
    
    # Do more work...
    tracer.in_span('operation-2') do |child_span2|
      # Do more work...
    end
  end
end
        

OpenTelemetry SDK を使用してトレースに注釈とメタデータを追加する

set_attribute メソッドを使用して、各スパンに属性を追加します。デフォルトでは、これらのスパン属性はすべて X-Ray の未加工データのメタデータに変換されることに注意してください。属性がメタデータではなく注釈に変換されるようにするには、その属性のキーを aws.xray.annotations 属性のリストに追加します。詳細については、「Enable The Customized X-Ray Annotations」を参照してください。

# SERVER span will become an X-Ray segment
tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
    # Your server logic here
    span.set_attribute('attribute.key', 'attribute.value')
    span.set_attribute("metadataKey", "metadataValue")
    span.set_attribute("annotationKey1", "annotationValue")
    
    # Create X-Ray annotations
    span.set_attribute("aws.xray.annotations", ["annotationKey1"])
end
        

Lambda でアクティブトレースを有効にした後、X-Ray SDK を使用するために必要な追加の設定はありません。Lambda は Lambda ハンドラー呼び出しを表すセグメントを作成し、追加の設定なしで X-Ray SDK を使用してサブセグメントまたは計装ライブラリを作成できます。

次のサンプル Lambda 関数コード (計装なし) を検討してください。

require 'json'
def lambda_handler(event:, context:)
    # TODO implement
    { statusCode: 200, body: JSON.generate('Hello from Lambda!') }
end
        

Lambda を手動で計装するには、以下を行う必要があります。

次のコードは、必要な変更が行われた後の Lambda 関数を示しています。追加のカスタムスパンを作成すると、自動的に提供されるスパンを補完できます。

require 'json'
require 'opentelemetry-sdk'
require 'aws/distro/opentelemetry/exporter/xray/udp'
require 'opentelemetry/propagator/xray'
require 'opentelemetry/instrumentation/aws_lambda'

# Initialize OpenTelemetry SDK outside handler
OpenTelemetry::SDK.configure do |c|
  # Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
      AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new
    )
  )
  
  # Configure X-Ray Lambda propagator
  c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator]
  
  # Set minimal resource information
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME']
  })
  c.use 'OpenTelemetry::Instrumentation::AwsLambda'
end

module LambdaFunctions
  class Handler
    extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
    def self.process(event:, context:)
      "Hello!"
    end
    instrument_handler :process
  end
end