Configuration du kit SDK X-Ray pour Ruby

Le kit SDK X-Ray pour Ruby possède une classe nomméeXRay.recorder 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.

Plug-ins de service

Permetplugins d'enregistrer des informations sur le service hébergeant votre application.

Plugins

• Amazon EC2 —ec2 ajoute l'ID et la zone de disponibilité de l'instance.

• Elastic Beanstalk :elastic_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.

Pour utiliser des plug-ins, spécifiez-les dans l'objet de configuration que vous transmettez à l'enregistreur.

Exemple 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, 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 leorigin champ sur le segment. Cela indique le type deAWS 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 effectue le suivi de la première demande chaque seconde et de 5 % de toutes les demandes supplémentaires, tous services confondus, qui envoient des traces à X-Ray. Créez des règles supplémentaires dans la console X-Ray afin de personnaliser la quantité de données enregistrées pour chacune de vos applications.

Le kit SDK applique les règles personnalisées dans l'ordre de leur définition. 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 à joindre X-Ray pour obtenir les règles d'échantillonnage, il revient à une règle locale par défaut selon laquelle la première demande est effectuée chaque seconde et 5 % des demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler des API d'échantillonnage ou s'il ne peut pas se connecter au démon X-Ray, qui agit en tant que 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 des règles locales comme solution de sauvegarde dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement des règles locales.

Exemple 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 rechercher les chemins/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 davantage d'hôtes, le débit 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.

Exemple main.rb — Configuration des règles de Backup

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.

Exemple config/sampling-rules.rb

my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}

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

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

Exemple main.rb — Désactive l'échantillonnage

require 'aws-xray-sdk'
config = {
  sampling: false,
  name: 'my app',
}
XRay.recorder.configure(config)

Journalisation

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 dans l'objet de configuration que vous transmettez à l'enregistreur.

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

Configuration de l'enregistreur dans le code

D'autres paramètres sont disponibles à partir de la méthode configure dans XRay.recorder.

• context_missing— Défini pourLOG_ERROR é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 démon 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.

• plugins— Enregistrez des informations sur lesAWS ressources de votre application à l'aide de plugins.

• sampling— Réglez surfalse pour désactiver l'échantillonnage.

• sampling_rules— Définissez le hachage contenant vos règles d'échantillonnage.

Exemple main.rb — Désactive les exceptions manquantes au 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— Défini surtrue pour enregistrer des sous-segments pour les transactions de la base de données Active Record.

Configurez les paramètres disponibles dans un objet de configuration nommé Rails.application.config.xray.

Exemple config/initializers/aws_xray.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 kit 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 du filtre servlet.

• AWS_XRAY_DAEMON_ADDRESS— Définissez l'hôte et le port de l'écouteur du démon X-Ray. Par défaut, le SDK envoie les données de trace à127.0.0.1:2000. Utilisez cette variable si vous avez configuré le démon pour qu'il écoute sur un autre port ou s'il s'exécute sur un autre hôte.

• AWS_XRAY_CONTEXT_MISSING— DéfiniRUNTIME_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— Déclenche une exception d'exécution.

  • LOG_ERROR— Consigne une erreur et continue (par défaut).

  • IGNORE_ERROR— Ignorez l'erreur et continuez.

  Des erreurs liées à des segments ou sous-segments manquants peuvent survenir lorsque vous essayez d'utiliser un client instrumenté dans du code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans du code qui génère un nouveau fil de discussion.

Les variables d'environnement remplacent les valeurs définies dans le code.