Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Migrer vers OpenTelemetry Ruby
Pour migrer vos applications Ruby du SDK X-Ray vers l' OpenTelemetry instrumentation, utilisez les exemples de code et les instructions suivants pour l'instrumentation manuelle.
**Topics**
+ [Instrumentez manuellement vos solutions avec le SDK](#manual-instrumentation-ruby)
+ [Suivi des demandes entrantes (instrumentation Rails)](#tracing-incoming-requests-ruby)
+ [AWS Instrumentation du SDK](#aws-sdk-instrumentation-ruby)
+ [Instrumentation des appels HTTP sortants](#http-instrumentation-ruby)
+ [Support d'instrumentation pour d'autres bibliothèques](#xray-migration-libraries-ruby)
+ [Création manuelle de données de trace](#manual-trace-creation-ruby)
+ [Instrumentation manuelle Lambda](#lambda-instrumentation-ruby)
## Instrumentez manuellement vos solutions avec le SDK
------
#### [ Tracing setup with X-Ray SDK ]
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])
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Note**
L'échantillonnage à distance X-Ray n'est actuellement pas disponible pour être configuré pour OpenTelemetry Ruby.
Pour une application Ruby on Rails, placez votre code de configuration dans un initialiseur Rails. Pour plus d'informations, consultez [Mise en route avec ](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). 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 :
+ `OTLP Exporter`— Nécessaire pour l'exportation des traces vers l' CloudWatch agent et le OpenTelemetry collecteur
+ `An AWS X-Ray Propagator`— Nécessaire pour propager le contexte de trace aux AWS services intégrés à X-Ray
```
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
```
------
## Suivi des demandes entrantes (instrumentation Rails)
------
#### [ With X-Ray SDK ]
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
}
```
------
#### [ With OpenTelemetry SDK ]
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
```
------
## AWS Instrumentation du SDK
------
#### [ With X-Ray SDK ]
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
```
------
#### [ With OpenTelemetry SDK ]
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 ](sdk-for-ruby/v3/developer-guide/observability.html) pour Ruby.
------
## Instrumentation des appels HTTP sortants
Lorsque vous effectuez des appels HTTP vers des services externes, vous devrez peut-être instrumenter les appels manuellement si l'instrumentation automatique n'est pas disponible ou ne fournit pas suffisamment de détails.
------
#### [ With X-Ray SDK ]
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)
```
------
#### [ With OpenTelemetry SDK ]
Pour activer l'`net/http`instrumentation à 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/http`instrumentation comme indiqué ci-dessous :
```
OpenTelemetry::SDK.configure do |c|
...
c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
...
end
```
------
## Support d'instrumentation pour d'autres bibliothèques
Vous trouverez la liste complète des instrumentations de bibliothèque prises en charge pour OpenTelemetry Ruby sous [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation).
Vous pouvez également effectuer une recherche OpenTelemetry dans le registre pour savoir si l'instrumentation est OpenTelemetry compatible. Pour plus d'informations, consultez la section [Registre](https://opentelemetry.io/ecosystem/registry/).
## Création manuelle de données de trace
------
#### [ With X-Ray SDK ]
À 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
```
------
#### [ With OpenTelemetry SDK ]
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 sont`INTERNAL`.
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('')` 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.annotations`attribut à la liste des attributs. Pour plus d'informations, consultez [Enable The Customized X-Ray Annotations.](https://aws-otel.github.io/docs/getting-started/x-ray#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
```
------
## Instrumentation manuelle Lambda
------
#### [ With X-Ray SDK ]
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.
------
#### [ With OpenTelemetry SDK ]
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 :
1. Ajoutez les gemmes suivantes pour votre Lambda
```
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-propagator-xray'
gem 'aws-distro-opentelemetry-exporter-xray-udp'
gem 'opentelemetry-instrumentation-aws_lambda'
gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher
```
1. Initialisez le OpenTelemetry SDK en dehors de votre gestionnaire Lambda. Il est recommandé de configurer le OpenTelemetry SDK avec :
1. Un processeur span simple doté d'un exportateur de span UDP X-Ray pour envoyer des traces au point de terminaison UDP X-Ray de Lambda
1. Un propagateur X-Ray Lambda
1. `service_name`configuration à définir sur le nom de la fonction Lambda
1. Dans votre classe de gestionnaire Lambda, ajoutez les lignes suivantes pour instrumenter votre gestionnaire Lambda :
```
class Handler
extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
...
instrument_handler :process
end
```
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
```
------
Voici un exemple de carte de trace d'une fonction Lambda instrumentée écrite en Ruby.
Vous pouvez également utiliser des couches Lambda OpenTelemetry pour configurer votre Lambda. Pour plus d'informations, consultez [OpenTelemetry AWS-Lambda Instrumentation](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage).