AWS X-Ray SDK pour Python

Note

X-Ray SDK/Daemon Avis de maintenance — Le 25 février 2026, il passera en mode maintenance, où les versions du X-Ray SDK et du démon AWS seront limitées pour résoudre uniquement les problèmes de sécurité. AWS X-Ray SDKs/Daemon Pour plus d'informations sur la chronologie du support, consultezChronologie du support pour le SDK et Daemon X-Ray. Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, consultez la section Migration d'une X-Ray instrumentation à OpenTelemetry une autre.

Le X-Ray SDK pour Python est une bibliothèque pour les applications Web Python qui fournit des classes et des méthodes permettant de générer et d'envoyer des données de trace au X-Ray démon. 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 effectue aux services en aval à l'aide du AWS SDK, des clients HTTP ou d'un connecteur de base de données SQL. 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 avec pip.

$ pip install aws-xray-sdk

Note

Le X-Ray SDK pour Python est un projet open source. Vous pouvez suivre le projet, soumettre des problèmes et des pull requests sur GitHub : github. com/aws/aws-xray-sdk-python

Si vous utilisez Django ou Flask, commencez par ajouter l'intergiciel du SDK à votre application afin de suivre les demandes entrantes. L'intergiciel crée un segment pour chaque demande suivie et termine le segment lorsque la réponse est envoyée. 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 autres applications, vous pouvez créer des segments manuellement.

Pour les fonctions Lambda appelées par une application ou un service instrumenté, Lambda lit l'en-tête de suivi et trace automatiquement les requêtes échantillonnées. Pour les autres fonctions, vous pouvez configurer Lambda pour échantillonner et suivre les demandes entrantes. Dans les deux cas, Lambda crée le segment et le fournit au X-Ray SDK.

Note

Sur Lambda, le X-Ray SDK est facultatif. Si vous ne l'utilisez pas dans votre fonction, votre carte de service inclura toujours un nœud pour le service Lambda et un pour chaque fonction Lambda. En ajoutant le SDK, vous pouvez instrumenter le code de votre fonction pour ajouter des sous-segments au segment de fonction enregistré par Lambda. Pour plus d’informations, consultez AWS Lambda et AWS X-Ray.

Consultez un Nœuds exemple de fonction Python instrumentée en Lambda.

Ensuite, utilisez le X-Ray SDK pour Python pour instrumenter les appels en aval en appliquant des correctifs aux bibliothèques de votre application. Le kit SDK prend en charge les bibliothèques suivantes :

Bibliothèques prises en charge

• botocore, boto3 — AWS SDK for Python (Boto) Clients d'instruments.

• pynamodb— Instruez la version du client Amazon DynamoDB de PynamoDB.

• aiobotocore, aioboto3 — Versions intégrées au mode asynchrone des instruments du SDK pour les clients Python (Boto3).

• requests, aiohttp — Instrument les clients HTTP de haut niveau.

• httplib, http.client — Instrument les clients HTTP de bas niveau et les bibliothèques de niveau supérieur qui les utilisent.

• sqlite3— Instrument les clients SQLite.

• mysql-connector-python— Instrument les clients MySQL.

• pg8000— Interface Pure-Python PostgreSQL de l'instrument.

• psycopg2— Adaptateur de base de données PostgreSQL pour instruments.

• pymongo— Instrument les clients MongoDB.

• pymysql— Clients basés sur Instrument PyMy SQL pour MySQL et MariaDB.

Chaque fois que votre application appelle une base de données SQL ou un autre service HTTP, le SDK enregistre les informations relatives à l'appel dans un sous-segment. AWS 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.

Après avoir commencé à utiliser le SDK, personnalisez son comportement en configurant l'enregistreur et le middleware. 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 définir le niveau de journal afin d'afficher plus ou moins d'informations du kit de développement logiciel 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).

Annotations et métadonnées

Les annotations et les métadonnées sont du texte arbitraire que vous ajoutez aux segments à l'aide du X-Ray SDK. Les annotations sont indexées pour être utilisées avec des expressions de filtre. Les métadonnées ne sont pas indexées, mais peuvent être affichées dans le segment brut à l'aide de la X-Ray console ou de l'API. 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. Vous pouvez créer un sous-segment personnalisé pour la totalité d'une fonction ou pour une section de code. Vous pouvez ensuite enregistrer des métadonnées et des annotations sur le sous-segment au lieu de tout écrire sur le segment parent.

Pour obtenir de la documentation de référence sur les classes et les méthodes du SDK, consultez la référence de l'API AWS X-Ray SDK pour Python.

Exigences

Le X-Ray SDK pour Python prend en charge les versions de langage et de bibliothèque suivantes.

• Python — 2.7, 3.4 et versions ultérieures

• Django — 1.10 et versions ultérieures

• Flask — 0.10 et versions ultérieures

• aiohttp — 2.3.0 et versions ultérieures

• AWS SDK for Python (Boto)— 1.4.0 et versions ultérieures

• botocore — 1.5.0 et versions ultérieures

• enum — 0.4.7 et versions ultérieures, pour les versions 3.4.0 et antérieures de Python

• jsonpickle — 1.0.0 et versions ultérieures

• setuptools — 40.6.3 et versions ultérieures

• wrapt — 1.11.0 et versions ultérieures

Gestion des dépendances

Le X-Ray SDK pour Python est disponible à l'adresse. pip

• Colis — aws-xray-sdk

Ajoutez le kit SDK en tant que dépendance dans le fichier requirements.txt.

Exemple requirements.txt

aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3

Si vous utilisez Elastic Beanstalk pour déployer votre application, Elastic Beanstalk installe automatiquement tous les packages. requirements.txt