Migre a Ruby OpenTelemetry

X-Ray SDK for Ruby requería que configuraras tu código con complementos de servicio.

require 'aws-xray-sdk'

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

Para una aplicación de Ruby on Rails, coloca tu código de configuración en un inicializador de Rails. Para obtener más información, consulte Introducción. Para todos los programas de Ruby instrumentados manualmente, debes usar el OpenTelemetry::SDK.configure método para configurar el OpenTelemetry SDK de Ruby.

Primero, instala los siguientes paquetes:

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

A continuación, configure el OpenTelemetry SDK mediante el código de configuración que se ejecuta cuando se inicializa el programa. Se recomienda configurar los siguientes componentes:

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 también tienen el concepto de instrumentaciones de biblioteca. Al habilitarlas, se crearán automáticamente intervalos para bibliotecas como el SDK. AWS OpenTelemetry ofrece la opción de habilitar todas las instrumentaciones de la biblioteca o especificar qué instrumentaciones de la biblioteca se deben habilitar.

Para habilitar todas las instrumentaciones, instale primero el paquete: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

A continuación, actualice la configuración para habilitar todas las instrumentaciones de la biblioteca, como se muestra a continuación:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDKs también tienen el concepto de instrumentaciones de biblioteca. Al habilitarlas, se crearán automáticamente intervalos para bibliotecas como el SDK. AWS OpenTelemetry ofrece la opción de habilitar todas las instrumentaciones de la biblioteca o especificar qué instrumentaciones de la biblioteca se deben habilitar.

Para habilitar todas las instrumentaciones, instale primero el paquete: opentelemetry-instrumentation-all

bundle add opentelemetry-instrumentation-all
        

A continuación, actualice la configuración para habilitar todas las instrumentaciones de la biblioteca, como se muestra a continuación:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Con el SDK de X-Ray, el rastreo de rayos X se configura para el marco de Rails tras la inicialización.

Ejemplo: _xray.rb config/initializers/aws

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

Primero, instale los siguientes paquetes:

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

A continuación, actualice la configuración para habilitar la instrumentación en su aplicación Rails, como se muestra a continuación:

# 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

Para instrumentar AWS las solicitudes salientes del AWS SDK, los clientes del AWS SDK se parchean con X-Ray, como en el siguiente ejemplo:

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 El SDK for Ruby V3 admite el registro y la emisión OpenTelemetry de trazas. Para obtener información sobre cómo configurar OpenTelemetry un cliente de servicio, consulta Cómo configurar las funciones de observabilidad en el AWS SDK for Ruby.

Para instrumentar las llamadas posteriores, se usó el SDK de X-Ray para Ruby para parchear la net/http biblioteca que usa tu aplicación:

require 'aws-xray-sdk'

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

XRay.recorder.configure(config)
        

Para habilitar el uso de la net/http instrumentación OpenTelemetry, primero instala el opentelemetry-instrumentation-net_http paquete:

bundle add opentelemetry-instrumentation-net_http
        

A continuación, actualice la configuración para habilitar la net/http instrumentación como se muestra a continuación:

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

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

end
        

Con X-Ray, el aws-xray-sdk paquete requería que creara segmentos manualmente y sus subsegmentos secundarios para rastrear su aplicación. Es posible que también hayas agregado anotaciones y metadatos de X-Ray a tus segmentos o subsegmentos:

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
        

Puede utilizar intervalos personalizados para supervisar el rendimiento de las actividades internas que no se recopilan en las bibliotecas de instrumentación. Tenga en cuenta que solo los tramos del tipo servidor se convierten en segmentos de rayos X, todos los demás tramos se convierten en subsegmentos de rayos X. Por defecto, los intervalos son. INTERNAL

Primero, crea un rastreador para generar intervalos, que puedes obtener mediante este método. OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') Esto proporcionará una instancia de Tracer que se registrará globalmente en la configuración de la aplicación. OpenTelemetry Es habitual tener un único Tracer para toda la aplicación. Cree un OpenTelemetry rastreador y úselo para crear intervalos:

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
        

Añadir anotaciones y metadatos a las trazas con el SDK OpenTelemetry

Usa el set_attribute método para agregar atributos a cada tramo. Tenga en cuenta que, de forma predeterminada, todos estos atributos de intervalo se convertirán en metadatos en los datos sin procesar de X-Ray. Para garantizar que un atributo se convierta en una anotación y no en metadatos, puede añadir esa clave de atributos a la lista de aws.xray.annotations atributos. Para obtener más información, consulte Habilitar las anotaciones de rayos X personalizadas.

# 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
        

Después de habilitar Active Tracing en Lambda, no se requieren configuraciones adicionales para usar el SDK de X-Ray. Lambda creará un segmento que represente la invocación del controlador de Lambda y usted puede crear subsegmentos o bibliotecas de instrumentos mediante el SDK de X-Ray sin necesidad de realizar ninguna configuración adicional.

Considere el siguiente ejemplo de código de función Lambda (sin instrumentación):

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

Para instrumentar manualmente su Lambda, necesitará:

El código siguiente muestra la función Lambda después de los cambios necesarios. Puede crear intervalos personalizados adicionales para complementar los intervalos que se proporcionan automáticamente.

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