Migrieren Sie zu Ruby OpenTelemetry

Das X-Ray-SDK für Ruby erforderte, dass Sie Ihren Code mit Service-Plug-ins konfigurieren.

require 'aws-xray-sdk'

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

Platzieren Sie für eine Ruby on Rails-Anwendung Ihren Konfigurationscode in einem Rails-Initialisierer. Weitere Informationen finden Sie unter Erste Schritte mit . Für alle manuell instrumentierten Ruby-Programme müssen Sie die OpenTelemetry::SDK.configure Methode verwenden, um das Ruby-SDK zu konfigurieren. OpenTelemetry

Installieren Sie zunächst die folgenden Pakete:

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

Als Nächstes konfigurieren Sie das OpenTelemetry SDK mithilfe des Konfigurationscodes, der bei der Initialisierung Ihres Programms ausgeführt wird. Es wird empfohlen, die folgenden Komponenten zu konfigurieren:

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 haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.

Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDKs haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.

Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Mit dem X-Ray SDK wird das X-Ray-Tracing bei der Initialisierung für das Rails-Framework konfiguriert.

Beispiel — _xray.rb config/initializers/aws

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

Installieren Sie zunächst die folgenden Pakete:

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

Aktualisieren Sie als Nächstes die Konfiguration, um die Instrumentierung für Ihre Rails-Anwendung zu aktivieren, wie unten gezeigt:

# 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

Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, werden die AWS SDK-Clients wie im folgenden Beispiel mit X-Ray gepatcht:

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 Das SDK for Ruby V3 bietet Unterstützung für das Aufzeichnen und Ausgeben OpenTelemetry von Spuren. Informationen zur Konfiguration OpenTelemetry für einen Service-Client finden Sie unter Konfiguration von Observability-Funktionen im AWS SDK for Ruby.

Um Downstream-Aufrufe zu instrumentieren, wurde das X-Ray-SDK SDK for Ruby verwendet, um die net/http Bibliothek zu patchen, die Ihre Anwendung verwendet:

require 'aws-xray-sdk'

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

XRay.recorder.configure(config)
        

Um die net/http Instrumentierung zu aktivieren OpenTelemetry, installieren Sie zunächst das opentelemetry-instrumentation-net_http Paket:

bundle add opentelemetry-instrumentation-net_http
        

Aktualisieren Sie als Nächstes die Konfiguration, um die net/http Instrumentierung wie folgt zu aktivieren:

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

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

end
        

Mit X-Ray mussten Sie für das aws-xray-sdk Paket manuell Segmente und deren untergeordnete Untersegmente erstellen, um Ihre Anwendung zu verfolgen. Möglicherweise haben Sie Ihren Segmenten oder Untersegmenten auch X-Ray-Anmerkungen und -Metadaten hinzugefügt:

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
        

Sie können benutzerdefinierte Zeitspannen verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt. Standardmäßig sind Spans. INTERNAL

Erstellen Sie zunächst einen Tracer, um Spans zu generieren, die Sie mit der Methode abrufen können. OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') Dadurch wird eine Tracer-Instanz bereitgestellt, die global in der Konfiguration Ihrer Anwendung registriert ist. OpenTelemetry Es ist üblich, einen einzigen Tracer für eine gesamte Anwendung zu haben. Erstellen Sie einen OpenTelemetry Tracer und verwenden Sie ihn, um Spans zu erstellen:

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
        

Hinzufügen von Anmerkungen und Metadaten zu Traces mit SDK OpenTelemetry

Verwenden Sie die set_attribute Methode, um jedem Bereich Attribute hinzuzufügen. Beachten Sie, dass alle diese Span-Attribute standardmäßig in Metadaten in X-Rohdaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie diesen Attributschlüssel zur aws.xray.annotations Attributliste hinzufügen. Weitere Informationen finden Sie unter Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.

# 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
        

Nachdem Active Tracing auf Lambda aktiviert wurde, sind keine zusätzlichen Konfigurationen erforderlich, um das X-Ray SDK zu verwenden. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie können Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellen.

Betrachten Sie das folgende Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung):

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

Um Ihr Lambda manuell zu instrumentieren, müssen Sie:

Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen.

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