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. # 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.