OpenTelemetry Ruby로 마이그레이션

Ruby용 X-Ray SDK를 사용하려면 서비스 플러그인으로 코드를 구성해야 했습니다.

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 SDKs도 있습니다. 이를 활성화하면 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 SDKs도 있습니다. 이를 활성화하면 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를 사용하면 초기화 시 Rails 프레임워크에 맞게 X-Ray 추적이 구성됩니다.

예 - 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의 관찰성 기능 구성을 참조하세요.

다운스트림 호출을 계측하기 위해 Ruby용 X-Ray SDK를 사용하여 애플리케이션이 사용하는 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
        

사용자 지정 스팬을 사용하여 계측 라이브러리로 캡처되지 않은 내부 활동의 성능을 모니터링할 수 있습니다. 종류의 스팬 서버만 X-Ray 세그먼트로 변환되고 다른 모든 스팬은 X-Ray 하위 세그먼트로 변환됩니다. 기본적으로 스팬은 입니다INTERNAL.

먼저 Tracer를 생성하여 OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') 메서드를 통해 얻을 수 있는 스팬을 생성합니다. 그러면 애플리케이션의 OpenTelemetry 구성에 전역적으로 등록된 Tracer 인스턴스가 제공됩니다. 전체 애플리케이션에 대해 단일 Tracer를 사용하는 것이 일반적입니다. 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 속성 목록에 추가할 수 있습니다. 자세한 내용은 사용자 지정 X-Ray 주석 활성화를 참조하세요.

# 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