AWS X-Ray SDK pour Ruby

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.

gem 'aws-sdk'

Si vous utilisez Rails, commencez par ajouter le middleware du SDK X-Ray pour suivre les demandes entrantes. Un filtre de demande crée un segment. 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.

Utilisez ensuite le SDK X-Ray pour instrumenter vos AWS SDK for Ruby clients HTTP et SQL en configurant l'enregistreur pour qu'il applique 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. 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. Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les expressions de filtre, 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).

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

Prérequis

Le SDK X-Ray nécessite Ruby 2.3 ou version ultérieure et est compatible avec les bibliothèques suivantes :