Migre a Ruby OpenTelemetry

X-Ray SDK para Ruby requería que configurara el 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, coloque el 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 SDK de OpenTelemetry Ruby.

Primero, instale 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 que configure 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, primero instale 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 incluyen 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, primero instale 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 X-Ray SDK, el rastreo de X-Ray se configura para el marco de Rails tras la inicialización.

Ejemploconfig/initializers/aws: _xray.rb

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 de la aplicación de 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 llamadas posteriores, se usó el X-Ray SDK para Ruby con el fin de aplicar parches a la biblioteca de net/http que utiliza la 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 instale el opentelemetry-instrumentation-net_http paquete:

bundle add opentelemetry-instrumentation-net_http
        

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

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

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

end
        

Con X-Ray, el paquete de aws-xray-sdk que requería para crear segmentos manualmente y sus subsegmentos secundarios a fin de rastrear la aplicación. Es posible que también haya agregado anotaciones y metadatos de X-Ray a los 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 intervalos de tipo servidor se convierten en segmentos de X-Ray, todos los demás intervalos se convierten en subsegmentos de X-Ray. Por defecto, los intervalos son INTERNAL.

En primer lugar, cree un rastreador para generar intervalos, que puede obtener mediante el método OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>'). Esto proporcionará una instancia de Tracer que se registrará globalmente en la OpenTelemetry configuración de su aplicación. Es común tener un solo rastreador para toda la aplicación. Cree un OpenTelemetry rastreador y utilícelo 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

Use el método set_attribute para agregar atributos a cada intervalo. 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 agregar esa clave del atributo a la lista del atributo aws.xray.annotations. Para obtener más información, consulte Habilitar anotaciones de X-Ray 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 que se habilitase el rastreo activo en Lambda, no se requiere ninguna configuración adicional para usar el X-Ray SDK. Lambda creará un segmento que represente la invocación del controlador de Lambda y puede crear subsegmentos o bibliotecas de instrumentos mediante el X-Ray SDK sin necesidad de realizar ninguna configuración adicional.

Tenga en cuenta el código de la función de Lambda de ejemplo siguiente (sin instrumentación):

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

Para instrumentar su Lambda de forma manual, necesitará lo siguiente:

El código siguiente muestra la función de 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