Migrer vers OpenTelemetry Ruby

Le SDK X-Ray pour Ruby nécessitait que vous configuriez votre code à l'aide de plug-ins de service.

require 'aws-xray-sdk'

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

Pour une application Ruby on Rails, placez votre code de configuration dans un initialiseur Rails. Pour plus d'informations, consultez Mise en route avec . Pour tous les programmes Ruby instrumentés manuellement, vous devez utiliser la OpenTelemetry::SDK.configure méthode pour configurer le SDK OpenTelemetry Ruby.

Installez d'abord les packages suivants :

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

Configurez ensuite le OpenTelemetry SDK via le code de configuration qui s'exécute lors de l'initialisation de votre programme. Il est recommandé de configurer les composants suivants :

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 ont également le concept d'instrumentations de bibliothèque. Leur activation créera automatiquement des étendues pour les bibliothèques telles que le AWS SDK. OpenTelemetry offre la possibilité d'activer toutes les instrumentations de bibliothèque ou de spécifier les instrumentations de bibliothèque à activer.

Pour activer toutes les instrumentations, installez d'abord le opentelemetry-instrumentation-all package :

bundle add opentelemetry-instrumentation-all
        

Ensuite, mettez à jour la configuration pour activer toutes les instrumentations de bibliothèque, comme indiqué ci-dessous :

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

OpenTelemetry SDKs ont également le concept d'instrumentations de bibliothèque. Leur activation créera automatiquement des étendues pour les bibliothèques telles que le AWS SDK. OpenTelemetry offre la possibilité d'activer toutes les instrumentations de bibliothèque ou de spécifier les instrumentations de bibliothèque à activer.

Pour activer toutes les instrumentations, installez d'abord le opentelemetry-instrumentation-all package :

bundle add opentelemetry-instrumentation-all
        

Ensuite, mettez à jour la configuration pour activer toutes les instrumentations de bibliothèque, comme indiqué ci-dessous :

require 'opentelemetry/instrumentation/all'
...

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

  c.use_all() # Enable all instrumentations
end
        

Avec le SDK X-Ray, le traçage X-Ray est configuré pour le framework Rails lors de l'initialisation.

Exemple — config/initializers/aws _xray.rb

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

Installez d'abord les packages suivants :

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

Ensuite, mettez à jour la configuration pour activer l'instrumentation pour votre application Rails, comme indiqué ci-dessous :

# 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

Pour traiter les AWS demandes sortantes du AWS SDK, les clients du AWS SDK sont corrigés avec X-Ray, comme dans l'exemple suivant :

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 Le SDK pour Ruby V3 prend en charge l'enregistrement et OpenTelemetry l'émission de traces. Pour plus d'informations sur la configuration d'un client de service, consultez la section Configuration des fonctionnalités d'observabilité dans le AWS SDK OpenTelemetry pour Ruby.

Pour instrumenter les appels en aval, le SDK X-Ray pour Ruby a été utilisé pour patcher net/http la bibliothèque utilisée par votre application :

require 'aws-xray-sdk'

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

XRay.recorder.configure(config)
        

Pour activer l'net/httpinstrumentation à l'aide de OpenTelemetry, installez d'abord le opentelemetry-instrumentation-net_http package :

bundle add opentelemetry-instrumentation-net_http
        

Ensuite, mettez à jour la configuration pour activer l'net/httpinstrumentation comme indiqué ci-dessous :

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

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

end
        

À l'aide de X-Ray, le aws-xray-sdk package vous a demandé de créer manuellement des segments et leurs sous-segments secondaires pour suivre votre application. Vous avez peut-être également ajouté des annotations et des métadonnées X-Ray à vos segments ou sous-segments :

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
        

Vous pouvez utiliser des intervalles personnalisés pour surveiller les performances des activités internes qui ne sont pas capturées par les bibliothèques d'instrumentation. Notez que seules les plages du type server sont converties en segments X-Ray, toutes les autres plages sont converties en sous-segments X-Ray. Par défaut, les intervalles sontINTERNAL.

Tout d'abord, créez un traceur afin de générer des spans, que vous pouvez obtenir grâce à la OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>') méthode. Cela fournira une instance Tracer enregistrée globalement dans la OpenTelemetry configuration de votre application. Il est courant d'avoir un seul traceur pour l'ensemble d'une application. Créez un OpenTelemetry traceur et utilisez-le pour créer des travé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
        

Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK

Utilisez set_attribute cette méthode pour ajouter des attributs à chaque intervalle. Notez que par défaut, tous ces attributs d'étendue seront convertis en métadonnées dans les données brutes de X-Ray. Pour garantir qu'un attribut est converti en annotation et non en métadonnées, vous pouvez ajouter cette clé d'aws.xray.annotationsattribut à la liste des attributs. Pour plus d'informations, consultez 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
        

Une fois Active Tracing activé sur Lambda, aucune configuration supplémentaire n'est requise pour utiliser le SDK X-Ray. Lambda créera un segment représentant l'invocation du gestionnaire Lambda, et vous pouvez créer des sous-segments ou des bibliothèques d'instruments à l'aide du SDK X-Ray sans aucune configuration supplémentaire.

Examinez l'exemple de code de fonction Lambda suivant (sans instrumentation) :

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

Pour instrumenter manuellement votre Lambda, vous devez :

Le code suivant illustre la fonction Lambda après les modifications requises. Vous pouvez créer des travées personnalisées supplémentaires pour compléter les travées fournies automatiquement.

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