Migrar para Ruby OpenTelemetry

O X-Ray SDK for 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 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 que você configure 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 opentelemetry-instrumentation-all pacote:

bundle add opentelemetry-instrumentation-all
        

Em seguida, atualize a configuração para habilitar todas as instrumentações da 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 opentelemetry-instrumentation-all pacote:

bundle add opentelemetry-instrumentation-all
        

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

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Com o X-Ray SDK, 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 as chamadas downstream, o X-Ray SDK for Ruby foi usado para corrigir net/http a biblioteca que seu aplicativo usa:

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 ativar a net/http instrumentação, conforme mostrado abaixo:

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

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

end
        

Usando o X-Ray, o aws-xray-sdk pacote exigia que você criasse manualmente segmentos e seus subsegmentos secundários para rastrear seu aplicativo. 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. Observe que somente extensões do tipo servidor são convertidas em segmentos de X-Ray, todas as outras extensões são convertidas em subsegmentos de X-Ray. Por padrão, os intervalos sãoINTERNAL.

Primeiro, crie um Tracer para gerar extensões, que você pode obter por meio do OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') método. Isso fornecerá uma instância do Tracer registrada globalmente na OpenTelemetry configuração do seu aplicativo. É comum ter um único Tracer para uma aplicação inteira. 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 set_attribute método para adicionar atributos a cada extensão. Observe que, por padrão, todos esses atributos de amplitude 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, você pode adicionar essa chave de atributos à lista de atributos. 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 Active Tracing foi habilitado no Lambda, não há necessidade de configurações adicionais para usar o X-Ray SDK. O Lambda criará um segmento representando a invocação do manipulador Lambda, e você poderá criar subsegmentos ou bibliotecas de instrumentos usando o X-Ray SDK sem nenhuma configuração adicional.

Considere o seguinte exemplo de código da função 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, você precisará:

O código a seguir demonstra a função 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