Migrar para Ruby OpenTelemetry

O SDK do X-Ray para Ruby exigia que você configurasse seu código com plug-ins de serviço.

require 'aws-xray-sdk'

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

Para um aplicativo Ruby on Rails, coloque seu código de configuração em um inicializador Rails. Para obter mais informações, consulte Conceitos básicos do . Para todos os programas Ruby instrumentados manualmente, você deve usar o OpenTelemetry::SDK.configure método para configurar o SDK do OpenTelemetry Ruby.

Primeiro, instale os seguintes pacotes:

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

Em seguida, configure o OpenTelemetry SDK por meio do código de configuração que é executado quando o programa é inicializado. É recomendável configurar os seguintes 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 também têm o conceito de instrumentações de biblioteca. Habilitá-los criará automaticamente extensões para bibliotecas como o AWS SDK. OpenTelemetry fornece a opção de ativar todas as instrumentações da biblioteca ou especificar quais instrumentações da biblioteca devem ser ativadas.

Para habilitar todas as instrumentações, primeiro instale o pacote opentelemetry-instrumentation-all:

bundle add opentelemetry-instrumentation-all
        

Em seguida, atualize a configuração para habilitar todas as instrumentações de biblioteca, conforme mostrado abaixo:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDKs também têm o conceito de instrumentações de biblioteca. Habilitá-los criará automaticamente extensões para bibliotecas como o AWS SDK. OpenTelemetry fornece a opção de ativar todas as instrumentações da biblioteca ou especificar quais instrumentações da biblioteca devem ser ativadas.

Para habilitar todas as instrumentações, primeiro instale o pacote opentelemetry-instrumentation-all:

bundle add opentelemetry-instrumentation-all
        

Em seguida, atualize a configuração para habilitar todas as instrumentações de biblioteca, conforme mostrado abaixo:

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Com o SDK do X-Ray, o rastreamento do X-Ray é configurado para a estrutura do Rails na inicialização.

Exemplo — config/initializers/aws _xray.rb

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

Primeiro, instale os seguintes pacotes:

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

Em seguida, atualize a configuração para habilitar a instrumentação para sua aplicação Rails, conforme mostrado abaixo:

# 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 as AWS solicitações de saída do AWS SDK, os clientes do AWS SDK são corrigidos com X-Ray, como no exemplo a seguir:

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 O SDK for Ruby V3 fornece suporte para gravação e emissão de traços. OpenTelemetry Para obter informações sobre como configurar um cliente de serviço, consulte Configuração de recursos de observabilidade no AWS SDK OpenTelemetry for Ruby.

Para instrumentar chamadas downstream, o SDK do X-Ray para Ruby foi usado para aplicar patches à biblioteca net/http usada pela aplicação:

require 'aws-xray-sdk'

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

XRay.recorder.configure(config)
        

Para habilitar o uso da net/http instrumentação OpenTelemetry, primeiro instale o opentelemetry-instrumentation-net_http pacote:

bundle add opentelemetry-instrumentation-net_http
        

Em seguida, atualize a configuração para habilitar a instrumentação de net/http, conforme mostrado abaixo:

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

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

end
        

Ao usar o X-Ray, o pacote aws-xray-sdk necessário para criar manualmente segmentos e seus subsegmentos filho para rastrear sua aplicação. Você também pode ter adicionado anotações e metadados do X-Ray aos seus segmentos ou 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
        

Você pode usar extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Somente extensões do tipo Servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray. Por padrão, as extensões são INTERNAL.

Primeiro, crie um Rastreador para gerar extensões, que podem ser obtidas por meio do método OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>'). Isso fornecerá uma instância do Tracer registrada globalmente na OpenTelemetry configuração do seu aplicativo. É comum ter um único rastreador para um aplicativo inteiro. Crie um OpenTelemetry rastreador e use-o para criar extensões:

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
        

Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry

Use o método set_attribute para adicionar atributos a cada extensão. Por padrão, todos esses atributos de extensão serão convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação, e não em metadados, adicione a chave desses atributos à lista do atributo aws.xray.annotations. Para obter mais informações, consulte Enable The Customized X-Ray Annotations.

# 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
        

Depois que o Rastreamento ativo for habilitado no Lambda, não haverá necessidade de configurações adicionais para usar o SDK do X-Ray. O Lambda criará um segmento representando a invocação do manipulador do Lambda, e você poderá criar subsegmentos ou bibliotecas de instrumentos usando o SDK do X-Ray sem nenhuma configuração adicional.

Considere o seguinte exemplo de código de função do Lambda (sem instrumentação):

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

Para instrumentar manualmente seu Lambda, é necessário:

O código a seguir demonstra a função do Lambda após as alterações necessárias. Você pode criar extensões personalizadas adicionais para complementar as extensões fornecidas automaticamente.

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