Migrasi ke Ruby OpenTelemetry

X-Ray SDK for Ruby mengharuskan Anda untuk mengonfigurasi kode Anda dengan plug-in layanan.

require 'aws-xray-sdk'

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

Untuk aplikasi Ruby on Rails, tempatkan kode konfigurasi Anda di penginisialisasi Rails. Untuk informasi selengkapnya, lihat Memulai. Untuk semua program Ruby yang diinstrumentasi secara manual, Anda harus menggunakan OpenTelemetry::SDK.configure metode ini untuk mengkonfigurasi OpenTelemetry Ruby SDK.

Pertama, instal paket-paket berikut:

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

Selanjutnya, konfigurasikan OpenTelemetry SDK melalui kode konfigurasi yang berjalan saat program Anda diinisialisasi. Disarankan agar Anda mengkonfigurasi komponen-komponen berikut:

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 juga memiliki konsep instrumentasi perpustakaan. Mengaktifkan ini akan secara otomatis membuat rentang untuk pustaka seperti SDK. AWS OpenTelemetry menyediakan opsi untuk mengaktifkan semua instrumentasi perpustakaan atau menentukan instrumentasi perpustakaan mana yang akan diaktifkan.

Untuk mengaktifkan semua instrumentasi, instal paket terlebih dahulu: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

Selanjutnya, perbarui konfigurasi untuk mengaktifkan semua instrumentasi pustaka seperti yang ditunjukkan di bawah ini:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDKs juga memiliki konsep instrumentasi perpustakaan. Mengaktifkan ini akan secara otomatis membuat rentang untuk pustaka seperti SDK. AWS OpenTelemetry menyediakan opsi untuk mengaktifkan semua instrumentasi perpustakaan atau menentukan instrumentasi perpustakaan mana yang akan diaktifkan.

Untuk mengaktifkan semua instrumentasi, instal paket terlebih dahulu: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

Selanjutnya, perbarui konfigurasi untuk mengaktifkan semua instrumentasi pustaka seperti yang ditunjukkan di bawah ini:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Dengan X-Ray SDK, penelusuran X-Ray dikonfigurasi untuk kerangka Rails setelah inisialisasi.

Contoh - config/initializers/aws _xray.rb

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

Pertama, instal paket-paket berikut:

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

Selanjutnya, perbarui konfigurasi untuk mengaktifkan instrumentasi untuk aplikasi Rails Anda seperti yang ditunjukkan di bawah ini:

# 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

Untuk menginstrumentasikan AWS permintaan keluar dari AWS SDK, klien AWS SDK ditambal dengan X-Ray seperti contoh berikut:

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 menyediakan dukungan untuk merekam dan memancarkan jejak. OpenTelemetry Untuk informasi tentang cara mengonfigurasi klien layanan, lihat Mengonfigurasi fitur observabilitas di AWS SDK OpenTelemetry for Ruby.

Untuk instrumen panggilan hilir, X-Ray SDK for Ruby digunakan untuk menambal net/http library yang digunakan aplikasi Anda:

require 'aws-xray-sdk'

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

XRay.recorder.configure(config)
        

Untuk mengaktifkan net/http instrumentasi menggunakan OpenTelemetry, pertama instal opentelemetry-instrumentation-net_http paket:

bundle add opentelemetry-instrumentation-net_http
        

Selanjutnya, perbarui konfigurasi untuk mengaktifkan net/http instrumentasi seperti yang ditunjukkan di bawah ini:

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

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

end
        

Menggunakan X-Ray, aws-xray-sdk paket mengharuskan Anda untuk membuat segmen dan sub-segmen anak mereka secara manual untuk melacak aplikasi Anda. Anda mungkin juga telah menambahkan anotasi X-Ray dan metadata ke segmen atau sub-segmen Anda:

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
        

Anda dapat menggunakan rentang kustom untuk memantau kinerja aktivitas internal yang tidak ditangkap oleh pustaka instrumentasi. Perhatikan bahwa hanya rentang server jenis yang diubah menjadi segmen X-Ray, semua rentang lainnya diubah menjadi sub-segmen X-Ray. Secara default, bentang adalahINTERNAL.

Pertama, buat Tracer untuk menghasilkan bentang, yang dapat Anda peroleh melalui metode iniOpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>'). Ini akan memberikan instance Tracer yang terdaftar secara global dalam OpenTelemetry konfigurasi aplikasi Anda. Adalah umum untuk memiliki satu Tracer untuk seluruh aplikasi. Buat OpenTelemetry pelacak dan gunakan untuk membuat bentang:

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
        

Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry

Gunakan set_attribute metode untuk menambahkan atribut ke setiap rentang. Perhatikan bahwa secara default, semua atribut rentang ini akan diubah menjadi metadata dalam data mentah X-Ray. Untuk memastikan bahwa atribut diubah menjadi anotasi dan bukan metadata, Anda dapat menambahkan kunci atribut tersebut ke daftar atribut. aws.xray.annotations Untuk informasi selengkapnya, lihat Mengaktifkan Anotasi X-Ray yang Disesuaikan.

# 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
        

Setelah Active Tracing diaktifkan di Lambda, tidak ada konfigurasi tambahan yang diperlukan untuk menggunakan X-Ray SDK. Lambda akan membuat segmen yang mewakili pemanggilan penangan Lambda, dan Anda dapat membuat sub-segmen atau pustaka instrumen menggunakan X-Ray SDK tanpa konfigurasi tambahan.

Pertimbangkan contoh kode fungsi Lambda berikut (tanpa instrumentasi):

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

Untuk instrumen Lambda Anda secara manual, Anda harus:

Kode berikut menunjukkan fungsi Lambda setelah perubahan yang diperlukan. Anda dapat membuat rentang kustom tambahan untuk melengkapi rentang yang disediakan secara otomatis.

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