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.
# AWS X-Ray SDK pour Ruby
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Le SDK X-Ray est une bibliothèque pour les applications Web Ruby qui fournit des classes et des méthodes permettant de générer et d'envoyer des données de trace au daemon X-Ray. Les données de suivi incluent des informations sur les requêtes HTTP entrantes traitées par l'application et les appels que l'application envoie aux services en aval à l'aide du AWS SDK, de clients HTTP ou d'un client d'enregistrement actif. Vous pouvez également créer des segments manuellement et ajouter des informations de débogage dans les annotations et les métadonnées.
Vous pouvez télécharger le kit SDK en l'ajoutant à votre gemfile et en exécutant `bundle install`.
**Example Gemfile**
```
gem 'aws-sdk'
```
Si vous utilisez Rails, commencez par [ajouter le middleware du SDK X-Ray](xray-sdk-ruby-middleware.md) pour suivre les demandes entrantes. Un filtre de demande crée un [segment](xray-concepts.md#xray-concepts-segments). Lorsque le segment est ouvert, vous pouvez utiliser les méthodes du client du SDK pour ajouter des informations au segment et créer des sous-segments afin de suivre les appels en aval. Le kit de développement logiciel (SDK) enregistre aussi automatiquement les exceptions que votre application renvoie quand le segment est ouvert. Pour les applications non-Rails, vous pouvez [créer des segments manuellement](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual).
Utilisez ensuite le SDK X-Ray pour instrumenter vos AWS SDK pour Ruby clients HTTP et SQL en [configurant l'enregistreur pour qu'il applique](xray-sdk-ruby-patching.md) des correctifs aux bibliothèques associées. Chaque fois que vous appelez une ressource Service AWS ou une ressource en aval avec un client instrumenté, le SDK enregistre les informations relatives à l'appel dans un sous-segment. Services AWS et les ressources auxquelles vous accédez au sein des services apparaissent sous forme de nœuds en aval sur la carte de trace pour vous aider à identifier les erreurs et les problèmes de limitation sur les connexions individuelles.
Une fois que vous êtes familiarisé avec le SDK, personnalisez son comportement en [configurant l'enregistreur](xray-sdk-ruby-configuration.md). Vous pouvez ajouter des plug-ins pour enregistrer les données sur les ressources de calcul exécutant votre application, personnaliser le comportement d'échantillonnage en définissant des règles d'échantillonnage et fournir un enregistreur d'événements afin d'afficher plus ou moins d'informations du kit SDK dans vos journaux d'application.
Enregistrez les informations supplémentaires sur les demandes et le travail que votre application effectue dans les [annotations et les métadonnées](xray-sdk-ruby-segment.md). Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les [expressions de filtre](xray-console-filters.md), de telle sorte que vous pouvez explorer les suivis qui contiennent des données spécifiques. Les entrées des métadonnées sont moins restrictives et peuvent enregistrer des objets et tableaux entiers (tout ce qui peut être sérialisé en JSON).
**Annotations et métadonnées**
Les annotations et les métadonnées sont du texte arbitraire que vous ajoutez aux segments avec le kit de développement X-Ray. Les annotations sont indexées pour être utilisées avec les expressions de filtre. Les métadonnées ne sont pas indexées, mais peuvent être consultées dans le segment brut à l'aide de la console ou de l'API X-Ray. Toute personne à qui vous accordez un accès en lecture à X-Ray peut consulter ces données.
Lorsque vous avez un grand nombre de clients instrumentés dans votre code, un seul segment de demande peut contenir un grand nombre de sous-segments, un par appel effectué à l'aide d'un client instrumenté. Vous pouvez organiser et grouper les sous-segments en enveloppant les appels clients dans des [sous-segments personnalisés](xray-sdk-ruby-subsegments.md). Vous pouvez créer un sous-segment personnalisé pour une fonction complète ou une quelconque section du code, puis enregistrer les métadonnées et les annotations sur le sous-segment au lieu de tout écrire sur le segment parent.
Pour consulter la documentation de référence sur les classes et les méthodes du SDK, consultez le manuel de référence de l'[AWS X-Ray API SDK for Ruby](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference).
## Prérequis
Le SDK X-Ray nécessite Ruby 2.3 ou version ultérieure et est compatible avec les bibliothèques suivantes :
+ AWS SDK pour Ruby version 3.0 ou ultérieure
+ Rails version 5.1 ou version ultérieure
# Configuration du SDK X-Ray pour Ruby
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Le SDK X-Ray pour Ruby possède une classe `XRay.recorder` nommée qui fournit l'enregistreur global. Vous pouvez configurer l'enregistreur mondial afin qu'il personnalise l'intergiciel qui crée des segments pour les appels HTTP entrants.
**Topics**
+ [Plug-ins de service](#xray-sdk-ruby-configuration-plugins)
+ [Règles d'échantillonnage](#xray-sdk-ruby-configuration-sampling)
+ [Logging](#xray-sdk-ruby-configuration-logging)
+ [Configuration de l'enregistreur dans le code](#xray-sdk-ruby-configuration-code)
+ [Configuration de l'enregistreur avec Rails](#xray-sdk-ruby-middleware-configuration-rails)
+ [Variables d’environnement](#xray-sdk-ruby-configuration-envvars)
## Plug-ins de service
Permet `plugins` d'enregistrer des informations sur le service hébergeant votre application.
**Plug-ins**
+ Amazon EC2 : `ec2` ajoute l'ID de l'instance et la zone de disponibilité.
+ Elastic `elastic_beanstalk` Beanstalk : ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement.
+ Amazon ECS — `ecs` ajoute l'ID du conteneur.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
Pour utiliser des plug-ins, spécifiez-les dans l'objet de configuration que vous transmettez à l'enregistreur.
**Example main.rb — Configuration du plugin**
```
my_plugins = %I[ec2 elastic_beanstalk]
config = {
plugins: my_plugins,
name: 'my app',
}
XRay.recorder.configure(config)
```
Vous pouvez également utiliser des [variables d'environnement](#xray-sdk-ruby-configuration-envvars), qui ont la priorité sur les valeurs définies dans le code, pour configurer l'enregistreur.
Le SDK utilise également les paramètres du plugin pour définir le `origin` champ du segment. Cela indique le type de AWS ressource qui exécute votre application. Lorsque vous utilisez plusieurs plug-ins, le SDK utilise l'ordre de résolution suivant pour déterminer l'origine : ElasticBeanstalk > EKS > ECS > EC2.
## Règles d'échantillonnage
Le SDK utilise les règles d'échantillonnage que vous définissez dans la console X-Ray pour déterminer les demandes à enregistrer. La règle par défaut suit la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires provenant de tous les services envoient des traces à X-Ray. [Créez des règles supplémentaires dans la console X-Ray](xray-console-sampling.md) pour personnaliser la quantité de données enregistrées pour chacune de vos applications.
Le SDK applique les règles personnalisées dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, le SDK applique uniquement la première règle.
**Note**
Si le SDK ne parvient pas à accéder à X-Ray pour obtenir des règles d'échantillonnage, il revient à une règle locale par défaut concernant la première demande chaque seconde, et 5 % des demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler sampling APIs ou ne peut pas se connecter au daemon X-Ray, qui agit comme un proxy TCP pour les appels d'API effectués par le SDK.
Vous pouvez également configurer le SDK pour charger des règles d'échantillonnage à partir d'un document JSON. Le SDK peut utiliser les règles locales comme solution de rechange dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement les règles locales.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
Cet exemple définit une règle personnalisée et une règle par défaut. La règle personnalisée applique un taux d'échantillonnage de 5 % sans nombre minimum de demandes à suivre pour les chemins sous-jacents. `/api/move/` La règle par défaut suit la première demande chaque seconde et 10 % des demandes supplémentaires.
L'inconvénient de définir des règles localement est que la cible fixe est appliquée par chaque instance de l'enregistreur indépendamment, au lieu d'être gérée par le service X-Ray. Au fur et à mesure que vous déployez de nouveaux hôtes, le taux fixe est multiplié, ce qui complique le contrôle de la quantité de données enregistrées.
Pour configurer les règles de sauvegarde, définissez un hachage pour le document dans l'objet de configuration que vous transmettez à l'enregistreur.
**Example main.rb — Configuration des règles de sauvegarde**
```
require 'aws-xray-sdk'
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}
config = {
sampling_rules: my_sampling_rules,
name: 'my app',
}
XRay.recorder.configure(config)
```
Pour stocker les règles d'échantillonnage de manière indépendante, définissez le hachage dans un fichier distinct et demandez au fichier de l'extraire dans votre application.
**Example config/sampling-rules.rb**
```
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}
```
**Example main.rb — Règle d'échantillonnage à partir d'un fichier**
```
require 'aws-xray-sdk'
require 'config/sampling-rules.rb'
config = {
sampling_rules: my_sampling_rules,
name: 'my app',
}
XRay.recorder.configure(config)
```
Pour utiliser uniquement des règles locales, exigez les règles d'échantillonnage et configurez le `LocalSampler`.
**Example main.rb — Échantillonnage de règles locales**
```
require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'
config = {
sampler: LocalSampler.new,
name: 'my app',
}
XRay.recorder.configure(config)
```
Vous pouvez également configurer l'enregistreur mondial afin qu'il désactive l'échantillonnage et instrumente toutes les demandes entrantes.
**Example main.rb — Désactive l'échantillonnage**
```
require 'aws-xray-sdk'
config = {
sampling: false,
name: 'my app',
}
XRay.recorder.configure(config)
```
## Logging
Par défaut, l'enregistreur place les événements de niveau informations dans `$stdout`. Vous pouvez personnaliser la journalisation en définissant un [enregistreur d'événements](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) dans l'objet de configuration que vous transmettez à l'enregistreur.
**Example main.rb — Journalisation**
```
require 'aws-xray-sdk'
config = {
logger: my_logger,
name: 'my app',
}
XRay.recorder.configure(config)
```
Utilisez les journaux de débogage pour identifier les problèmes, tels que des sous-segments ouverts, lorsque vous [générez manuellement des sous-segments](xray-sdk-ruby-subsegments.md).
## Configuration de l'enregistreur dans le code
D'autres paramètres sont disponibles à partir de la méthode `configure` dans `XRay.recorder`.
+ `context_missing`— Réglé sur `LOG_ERROR` pour éviter de générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert.
+ `daemon_address`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray.
+ `name`— Définissez un nom de service que le SDK utilise pour les segments.
+ `naming_pattern`— Définissez un modèle de nom de domaine pour utiliser la [dénomination dynamique](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming).
+ `plugins`— Enregistrez des informations sur les AWS ressources de votre application à l'aide de [plugins](#xray-sdk-ruby-configuration-plugins).
+ `sampling`— Réglez sur `false` pour désactiver l'échantillonnage.
+ `sampling_rules`— Définissez le hachage contenant vos [règles d'échantillonnage](#xray-sdk-ruby-configuration-sampling).
**Example main.rb — Désactive les exceptions manquantes dans le contexte**
```
require 'aws-xray-sdk'
config = {
context_missing: 'LOG_ERROR'
}
XRay.recorder.configure(config)
```
## Configuration de l'enregistreur avec Rails
Si vous utilisez l'infrastructure Rails, vous pouvez configurer les options sur l'enregistreur mondial dans un fichier Ruby sous `app_root/initializers`. Le SDK X-Ray prend en charge une clé de configuration supplémentaire à utiliser avec Rails.
+ `active_record`— Paramétré sur `true` pour enregistrer les sous-segments des transactions de base de données Active Record.
Configurez les paramètres disponibles dans un objet de configuration nommé `Rails.application.config.xray`.
**Example config/initializers/aws\$1xray.rb**
```
Rails.application.config.xray = {
name: 'my app',
patch: %I[net_http aws_sdk],
active_record: true
}
```
## Variables d’environnement
Vous pouvez utiliser des variables d'environnement pour configurer le SDK X-Ray pour Ruby. Le kit SDK prend en charge les variables suivantes:
+ `AWS_XRAY_TRACING_NAME`— Définissez un nom de service que le SDK utilise pour les segments. Remplace le nom de service que vous définissez sur la [stratégie d'attribution de noms de segment](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) du filtre servlet.
+ `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray. Par défaut, le SDK envoie les données de suivi à`127.0.0.1:2000`. Utilisez cette variable si vous avez configuré le démon pour qu'il [écoute sur un port différent](xray-daemon-configuration.md) ou s'il s'exécute sur un autre hôte.
+ `AWS_XRAY_CONTEXT_MISSING`— Réglé sur `RUNTIME_ERROR` pour générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert.
**Valeurs valides**
+ `RUNTIME_ERROR`— Lance une exception d'exécution.
+ `LOG_ERROR`— Enregistrez une erreur et continuez (par défaut).
+ `IGNORE_ERROR`— Ignorez l'erreur et continuez.
Des erreurs liées à des segments ou sous-segments manquants peuvent se produire lorsque vous essayez d'utiliser un client instrumenté dans un code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans un code qui génère un nouveau thread.
Les variables d'environnement remplacent les valeurs définies dans le code.
# Suivi des demandes entrantes avec le kit de développement X-Ray SDK for Ruby Middleware
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Vous pouvez utiliser le SDK X-Ray pour suivre les requêtes HTTP entrantes traitées par votre application sur une instance EC2 dans Amazon EC2 ou Amazon AWS Elastic Beanstalk ECS.
Si vous utilisez Rails, servez-vous de l'intergiciel Rails pour instrumenter les demandes HTTP entrantes. Lorsque vous ajoutez le middleware à votre application et que vous configurez un nom de segment, le SDK X-Ray pour Ruby crée un segment pour chaque requête échantillonnée. Tous les segments créés par une instrumentation supplémentaire deviennent des sous-segments du segment au niveau de la demande qui fournit des informations sur la demande et la réponse HTTP. Ces informations comprennent la durée, la méthode et l'état de la demande.
Chaque segment porte un nom qui identifie votre application dans la carte des services. Le segment peut être nommé de manière statique ou vous pouvez configurer le SDK pour qu'il soit nommé dynamiquement en fonction de l'en-tête de l'hôte dans la demande entrante. La dénomination dynamique vous permet de regrouper les traces en fonction du nom de domaine indiqué dans la demande et d'appliquer un nom par défaut si le nom ne correspond pas au modèle attendu (par exemple, si l'en-tête de l'hôte est falsifié).
**Demandes transmises**
Si un équilibreur de charge ou un autre intermédiaire transmet une demande à votre application, X-Ray prend l'adresse IP du client depuis l'`X-Forwarded-For`en-tête de la demande plutôt que depuis l'adresse IP source du paquet IP. L'adresse IP du client enregistrée pour une demande transférée peut être falsifiée, elle ne doit donc pas être fiable.
Lorsqu'une demande est transmise, le SDK définit un champ supplémentaire dans le segment pour l'indiquer. Si le segment contient le champ `x_forwarded_for` défini sur`true`, l'adresse IP du client a été extraite de l'`X-Forwarded-For`en-tête de la requête HTTP.
L'intergiciel crée un segment pour chaque demande entrante avec un bloc `http` contenant les informations suivantes :
+ **Méthode HTTP** : GET, POST, PUT, DELETE, etc.
+ **Adresse du client** : adresse IP du client qui a envoyé la demande.
+ **Code de réponse** : code de réponse HTTP pour la demande terminée.
+ **Moment** : heure de début (date de réception de la demande) et heure de fin (date d'envoi de la réponse).
+ **Agent utilisateur** — Le formulaire `user-agent` de la demande.
+ **Longueur du contenu** : `content-length` extrait de la réponse.
## Utilisation de l'intergiciel Rails
Pour utiliser l'intergiciel, mettez à jour votre gemfile pour inclure le [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html) requis.
**Example Gemfile - Rails**
```
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
```
Pour utiliser le middleware, vous devez également [configurer l'enregistreur](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) avec un nom qui représente l'application dans la carte de trace.
**Example config/initializers/aws\$1xray.rb**
```
Rails.application.config.xray = {
name: 'my app'
}
```
## Instrumentation manuelle du code
Si vous n'utilisez pas Rails, créez des segments manuellement. Vous pouvez créer un segment pour chaque demande entrante, ou créer des segments autour de clients HTTP ou AWS SDK corrigés afin de fournir un contexte permettant à l'enregistreur d'ajouter des sous-segments.
```
# Start a segment
segment = XRay.recorder.begin_segment 'my_service'
# Start a subsegment
subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'
# Add metadata or annotation here if necessary
my_annotations = {
k1: 'v1',
k2: 1024
}
segment.annotations.update my_annotations
# Add metadata to default namespace
subsegment.metadata[:k1] = 'v1'
# Set user for the segment (subsegment is not supported)
segment.user = 'my_name'
# End segment/subsegment
XRay.recorder.end_subsegment
XRay.recorder.end_segment
```
## Configuration d'une stratégie d'attribution de noms de segment
AWS X-Ray utilise un *nom de service* pour identifier votre application et la distinguer des autres applications, bases de données, ressources externes APIs et AWS ressources utilisées par votre application. Lorsque le SDK X-Ray génère des segments pour les demandes entrantes, il enregistre le nom du service de votre application dans le [champ du nom](xray-api-segmentdocuments.md#api-segmentdocuments-fields) du segment.
Le SDK X-Ray peut nommer les segments d'après le nom d'hôte dans l'en-tête de la requête HTTP. Cependant, cet en-tête peut être falsifié, ce qui peut entraîner la création de nœuds inattendus dans votre carte de service. Pour éviter que le SDK ne nomme les segments de manière incorrecte en raison de demandes contenant des en-têtes d'hôte falsifiés, vous devez spécifier un nom par défaut pour les demandes entrantes.
Si votre application traite des demandes pour plusieurs domaines, vous pouvez configurer le SDK pour qu'il utilise une stratégie de dénomination dynamique afin de refléter cela dans les noms des segments. Une stratégie de dénomination dynamique permet au SDK d'utiliser le nom d'hôte pour les demandes qui correspondent à un modèle attendu et d'appliquer le nom par défaut aux demandes qui ne le sont pas.
Par exemple, il se peut qu'une seule application envoie des demandes à trois sous-domaines : `www.example.com``api.example.com`, et`static.example.com`. Vous pouvez utiliser une stratégie de dénomination dynamique avec le modèle `*.example.com` pour identifier les segments de chaque sous-domaine avec un nom différent, ce qui permet d'obtenir trois nœuds de service sur la carte des services. Si votre application reçoit des demandes dont le nom d'hôte ne correspond pas au modèle, vous verrez un quatrième nœud sur la carte des services avec un nom de remplacement que vous spécifiez.
Pour utiliser le même nom pour tous les segments de demande, spécifiez le nom de votre application lorsque vous configurez l'enregistreur, comme illustré dans les [sections précédentes](#xray-sdk-ruby-middleware-rails).
Une stratégie d'attribution de noms dynamique définit un modèle auquel doivent correspondre les noms d'hôte et un nom par défaut à utiliser si le nom d'hôte de la demande HTTP ne correspond pas au modèle. Pour nommer des segments de façon dynamique, spécifiez un modèle d'affectation de noms dans le hachage de configuration.
**Example main.rb — Dénomination dynamique**
```
config = {
naming_pattern: '*mydomain*',
name: 'my app',
}
XRay.recorder.configure(config)
```
Vous pouvez utiliser '\$1' dans le modèle pour correspondre à n'importe quelle chaîne ou '?' pour correspondre à un seul caractère.
**Note**
Vous pouvez remplacer le nom de service par défaut que vous définissez avec la `AWS_XRAY_TRACING_NAME`variable d'environnement[Variables d’environnement](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars).
# Correction des bibliothèques pour instrumenter les appels en aval
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Pour instrumenter les appels en aval, utilisez le SDK X-Ray pour Ruby afin de patcher les bibliothèques utilisées par votre application. Le SDK X-Ray pour Ruby peut appliquer des correctifs aux bibliothèques suivantes.
**Bibliothèques prises en charge**
+ `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)`— Clients HTTP de l'instrument.
+ `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— AWS SDK pour Ruby Clients de l'instrument.
Lorsque vous utilisez une bibliothèque patchée, le SDK X-Ray pour Ruby crée un sous-segment pour l'appel et enregistre les informations issues de la demande et de la réponse. Un segment doit être disponible pour que le kit SDK puisse créer le sous-segment à partir de l'intergiciel SDK ou d'un appel à `XRay.recorder.begin_segment`.
Pour patcher des bibliothèques, spécifiez-les dans l'objet de configuration que vous transmettez à l'enregistreur X-Ray.
**Example main.rb — Bibliothèques de correctifs**
```
require 'aws-xray-sdk'
config = {
name: 'my app',
patch: %I[net_http aws_sdk]
}
XRay.recorder.configure(config)
```
# Suivi des appels du AWS SDK avec le SDK X-Ray pour Ruby
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Lorsque votre application fait des appels Services AWS pour stocker des données, écrire dans une file d'attente ou envoyer des notifications, le SDK X-Ray pour Ruby suit les appels en aval [dans](xray-sdk-ruby-subsegments.md) des sous-segments. Les ressources tracées Services AWS et auxquelles vous accédez au sein de ces services (par exemple, un compartiment Amazon S3 ou une file d'attente Amazon SQS) apparaissent sous forme de nœuds en aval sur la carte de suivi de la console X-Ray.
Le SDK X-Ray pour Ruby instrumente automatiquement AWS tous les clients du SDK lorsque [vous appliquez un correctif `aws-sdk`](xray-sdk-ruby-patching.md) à la bibliothèque. Vous ne pouvez pas instrumenter des clients individuels.
Pour tous les services, vous pouvez voir le nom de l'API appelée dans la console X-Ray. Pour un sous-ensemble de services, le SDK X-Ray ajoute des informations au segment afin d'améliorer la granularité de la carte des services.
Par exemple, lorsque vous passez un appel avec un client DynamoDB instrumenté, le SDK ajoute le nom de la table au segment pour les appels qui ciblent une table. Dans la console, chaque table apparaît sous la forme d'un nœud distinct dans la carte des services, avec un nœud DynamoDB générique pour les appels qui ne ciblent pas une table.
**Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Lorsque vous accédez aux ressources nommées, les appels vers les services suivants créent des nœuds supplémentaires dans la cartographie des services. Les appels qui ne ciblent pas de ressources spécifiques créent un nœud générique pour le service.
+ **Amazon DynamoDB — Nom** de la table
+ **Amazon Simple Storage Service** : nom du compartiment et de la clé
+ **Amazon Simple Queue Service** — Nom de la file d'attente
# Génération de sous-segments personnalisés avec le SDK X-Ray
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Les sous-segments étendent le [segment](xray-concepts.md#xray-concepts-segments) d'une trace avec des détails sur le travail effectué afin de répondre à une demande. Chaque fois que vous passez un appel avec un client instrumenté, le SDK X-Ray enregistre les informations générées dans un sous-segment. Vous pouvez créer des sous-segments supplémentaires pour regrouper d'autres sous-segments, pour mesurer les performances d'une section de code ou pour enregistrer des annotations et des métadonnées.
Pour gérer des sous-segments, utilisez les méthodes `begin_subsegment` et `end_subsegment`.
```
subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote'
my_annotations = { id: 12345 }
subsegment.annotations.update my_annotations
XRay.recorder.end_subsegment
```
Pour créer un sous-segment pour une fonction, encapsulez-le dans un appel à `XRay.recorder.capture`.
```
XRay.recorder.capture('name_for_subsegment') do |subsegment|
resp = myfunc() # myfunc is your function
subsegment.annotations.update k1: 'v1'
resp
end
```
Lorsque vous créez un sous-segment au sein d'un segment ou d'un autre sous-segment, le SDK X-Ray génère un identifiant pour celui-ci et enregistre l'heure de début et l'heure de fin.
**Example Sous-segment avec des métadonnées**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Ajoutez des annotations et des métadonnées aux segments avec le SDK X-Ray pour Ruby
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Vous pouvez enregistrer des informations supplémentaires sur les demandes, l'environnement ou votre application à l'aide d'annotations et de métadonnées. Vous pouvez ajouter des annotations et des métadonnées aux segments créés par le SDK X-Ray ou aux sous-segments personnalisés que vous créez.
Les **annotations sont des** paires clé-valeur avec des chaînes, des nombres ou des valeurs booléennes. Les annotations sont indexées pour être utilisées avec les expressions de [filtre](xray-console-filters.md). Utilisez les annotations pour enregistrer les données que vous souhaitez utiliser pour regrouper les suivis dans la console ou lors de l'appel de l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
Les **métadonnées sont des** paires clé-valeur qui peuvent contenir des valeurs de n'importe quel type, y compris des objets et des listes, mais qui ne sont pas indexées pour être utilisées avec des expressions de filtre. Utilisez les métadonnées pour enregistrer des données supplémentaires que vous souhaitez stocker dans le traçage, mais que vous n'avez pas besoin d'utiliser pour la recherche.
En plus des annotations et des métadonnées, vous pouvez également [enregistrer les chaînes d'ID utilisateur](#xray-sdk-ruby-segment-userid) sur des segments. IDs Les utilisateurs sont enregistrés dans un champ distinct sur les segments et sont indexés pour être utilisés dans le cadre de la recherche.
**Topics**
+ [Enregistrer des annotations avec le SDK X-Ray pour Ruby](#xray-sdk-ruby-segment-annotations)
+ [Enregistrement de métadonnées avec le SDK X-Ray pour Ruby](#xray-sdk-ruby-segment-metadata)
+ [Utilisateur enregistrant IDs avec le SDK X-Ray pour Ruby](#xray-sdk-ruby-segment-userid)
## Enregistrer des annotations avec le SDK X-Ray pour Ruby
Utilisez les annotations pour enregistrer les informations sur les segments ou sous-segments qui doivent être indexés pour la recherche.
**Exigences liées aux annotations**
+ **Clés** — La clé d'une annotation X-Ray peut comporter jusqu'à 500 caractères alphanumériques. Vous ne pouvez pas utiliser d'espaces ou de symboles autres qu'un point ou un point (.)
+ **Valeurs** — La valeur d'une annotation X-Ray peut comporter jusqu'à 1 000 caractères Unicode.
+ Nombre d'**annotations** : vous pouvez utiliser jusqu'à 50 annotations par trace.
**Pour enregistrer les annotations**
1. Obtenez une référence au segment ou sous-segment en cours à partir d'`xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
or
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Appelez `update` avec une valeur de hachage.
```
my_annotations = { id: 12345 }
document.annotations.update my_annotations
```
L'exemple suivant montre comment appeler `update` avec une clé d'annotation contenant un point.
```
my_annotations = { testkey.test: 12345 }
document.annotations.update my_annotations
```
Le kit de développement logiciel enregistre les annotations sous forme de paires clé-valeur dans un objet `annotations` du document de segment. Si vous appelez deux fois `add_annotations` avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées.
Pour rechercher les suivis ayant des annotations avec des valeurs spécifiques, utilisez le mot clé `annotation[key]` dans une [expression de filtre](xray-console-filters.md).
## Enregistrement de métadonnées avec le SDK X-Ray pour Ruby
Utilisez les métadonnées pour enregistrer des informations sur les segments ou sous-segments qui n'ont pas besoin d'être indexés pour la recherche. Les valeurs des métadonnées peuvent être de type chaîne, valeur numérique, valeur booléenne ou tout objet à même d'être sérialisé en un tableau ou objet JSON.
**Pour enregistrer les métadonnées**
1. Obtenez une référence au segment ou sous-segment en cours à partir d'`xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
or
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Appelez `metadata` avec une clé de type chaîne, une valeur de type booléen, numérique, chaîne ou objet et un espace de noms de type chaîne.
```
my_metadata = {
my_namespace: {
key: 'value'
}
}
subsegment.metadata my_metadata
```
Si vous appelez deux fois `metadata` avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées.
## Utilisateur enregistrant IDs avec le SDK X-Ray pour Ruby
Enregistrez les segments utilisateur IDs sur demande pour identifier l'utilisateur qui a envoyé la demande.
**Pour enregistrer un utilisateur IDs**
1. Obtenez une référence au segment en cours à partir d'`xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
1. Définissez le champ utilisateur du segment sur un ID de chaîne de l'utilisateur qui a envoyé la demande.
```
segment.user = 'U12345'
```
Vous pouvez définir l'utilisateur dans vos contrôleurs pour enregistrer l'ID utilisateur dès que votre application commence le traitement d'une demande.
Pour rechercher les suivis d'un ID utilisateur, utilisez le mot clé `user` dans une [expression de filtre](xray-console-filters.md).