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 Python
**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 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 démon 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, 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 SDK X-Ray pour Python est un projet open source. Vous pouvez suivre le projet et soumettre des problèmes et des pull requests sur GitHub : [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-python)- xray-sdk-python
Si vous utilisez Django ou Flask, commencez par [ajouter l'intergiciel du SDK à votre application](xray-sdk-python-middleware.md) afin de suivre les demandes entrantes. L'intergiciel crée un [segment](xray-concepts.md#xray-concepts-segments) 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](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
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](xray-concepts.md#xray-concepts-tracingheader). Pour les autres fonctions, vous pouvez [configurer Lambda](xray-services-lambda.md) pour échantillonner et suivre les demandes entrantes. Dans les deux cas, Lambda crée le segment et le fournit au SDK X-Ray.
**Note**
Sur Lambda, le SDK X-Ray 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 nœud pour chaque fonction Lambda. En ajoutant le SDK, vous pouvez instrumenter votre code de fonction pour ajouter des sous-segments au segment de fonction enregistré par Lambda. Pour plus d’informations, consultez [AWS Lambda et AWS X-Ray](xray-services-lambda.md).
Voir un [Nœuds](scorekeep-lambda.md#scorekeep-lambda-worker) exemple de fonction Python instrumentée dans Lambda.
Utilisez ensuite le SDK X-Ray pour Python pour instrumenter les appels en aval en appliquant des [correctifs aux bibliothèques de votre application](xray-sdk-python-patching.md). Le kit SDK prend en charge les bibliothèques suivantes :
**Bibliothèques prises en charge**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK pour Python (Boto) Clients de l'instrument.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`— Version du client Amazon DynamoDB de l'instrument PynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Versions intégrées à Instrument [asyncio](https://docs.python.org/3/library/asyncio.html) du SDK pour les clients Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` — Clients HTTP de haut niveau de l'instrument.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)— Instrument les clients HTTP de bas niveau et les bibliothèques de niveau supérieur qui les utilisent.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clients de l'instrument.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`— Instrument les clients MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`— Interface PostgreSQL en Python pur de l'instrument.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`— Adaptateur de base de données PostgreSQL Instrument.
+ `[pymongo](https://pypi.org/project/pymongo/)`— Instrument les clients MongoDB.
+ `[pymysql](https://pypi.org/project/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 d'autres services 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](xray-sdk-python-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 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](xray-sdk-python-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-python-subsegments.md). 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 consulter la documentation de référence sur les classes et les méthodes du SDK, consultez le manuel de référence des [API du AWS X-Ray SDK pour Python](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference).
## Prérequis
Le SDK X-Ray 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 pour 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 SDK X-Ray pour Python est disponible à `pip` l'adresse.
+ **Package** — `aws-xray-sdk`
Ajoutez le kit SDK en tant que dépendance dans le fichier `requirements.txt`.
**Example 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`
# Configuration du kit de développement X-Ray pour Python
**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 pour Python possède une classe nommée `xray_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.
**Topics**
+ [Plug-ins de service](#xray-sdk-python-configuration-plugins)
+ [Règles d'échantillonnage](#xray-sdk-python-configuration-sampling)
+ [Logging](#xray-sdk-python-configuration-logging)
+ [Configuration de l'enregistreur dans le code](#xray-sdk-python-middleware-configuration-code)
+ [Configuration de l'enregistreur avec Django](#xray-sdk-python-middleware-configuration-django)
+ [Variables d’environnement](#xray-sdk-python-configuration-envvars)
## Plug-ins de service
Permet `plugins` d'enregistrer des informations sur le service hébergeant votre application.
**Plug-ins**
+ Amazon EC2 — `EC2Plugin` ajoute l'ID de l'instance, la zone de disponibilité et le groupe de CloudWatch journaux.
+ Elastic `ElasticBeanstalkPlugin` Beanstalk : ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement.
+ Amazon ECS — `ECSPlugin` 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 un plug-in, appelez `configure` sur l'enregistreur `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()
```
**Note**
Comme `plugins` ils sont transmis sous forme de tuple, veillez à inclure une fin `,` lorsque vous spécifiez un seul plugin. Par exemple, `plugins = ('EC2Plugin',)`
Vous pouvez également utiliser des [variables d'environnement](#xray-sdk-python-configuration-envvars), qui ont la priorité sur les valeurs définies dans le code, pour configurer l'enregistreur.
Configurez les plug-ins avant les [bibliothèques de correctifs](xray-sdk-python-patching.md) pour enregistrer les appels en aval.
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 % de toutes les 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.
Activé AWS Lambda, vous ne pouvez pas modifier le taux d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des demandes échantillonnées par ce service seront enregistrés par Lambda. Si le suivi actif est activé et qu'aucun en-tête de suivi n'est présent, Lambda prend la décision d'échantillonnage.
Pour configurer les règles d'échantillonnage de sauvegarde`xray_recorder.configure`, appelez, comme indiqué dans l'exemple suivant, où se *rules* trouve soit un dictionnaire de règles, soit le chemin absolu vers un fichier JSON contenant des règles d'échantillonnage.
```
xray_recorder.configure(sampling_rules=rules)
```
Pour utiliser uniquement les règles locales, configurez l'enregistreur avec une instruction `LocalSampler`.
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
Vous pouvez également configurer l'enregistreur mondial afin qu'il désactive l'échantillonnage et instrumente toutes les demandes entrantes.
**Example main.py — Désactive l'échantillonnage**
```
xray_recorder.configure(sampling=False)
```
## Logging
Le SDK utilise le `logging` module intégré de Python avec un niveau de `WARNING` journalisation par défaut. Obtenez une référence à l'enregistreur d'événements pour la classe `aws_xray_sdk` et appelez `setLevel` sur ce dernier pour configurer le niveau de journalisation différent pour la bibliothèque et le reste de l'application.
**Example app.py — Journalisation**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
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-python-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.
+ `service`— Définissez un nom de service que le SDK utilise pour les segments.
+ `plugins`— Enregistrez des informations sur les AWS ressources de votre application.
+ `sampling`— Réglez sur `False` pour désactiver l'échantillonnage.
+ `sampling_rules`— Définissez le chemin du fichier JSON contenant vos [règles d'échantillonnage](#xray-sdk-python-configuration-sampling).
**Example main.py — Désactive les exceptions manquantes dans le contexte**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Configuration de l'enregistreur avec Django
Si vous utilisez l'infrastructure Django, vous pouvez utiliser le fichier Django `settings.py` pour configurer les options de l'enregistreur mondial.
+ `AUTO_INSTRUMENT`(Django uniquement) — Enregistrez des sous-segments pour les opérations de rendu de base de données et de modèles intégrées.
+ `AWS_XRAY_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.
+ `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray.
+ `AWS_XRAY_TRACING_NAME`— Définissez un nom de service que le SDK utilise pour les segments.
+ `PLUGINS`— Enregistrez des informations sur les AWS ressources de votre application.
+ `SAMPLING`— Réglez sur `False` pour désactiver l'échantillonnage.
+ `SAMPLING_RULES`— Définissez le chemin du fichier JSON contenant vos [règles d'échantillonnage](#xray-sdk-python-configuration-sampling).
Pour activer la configuration de l'enregistreur dans `settings.py`, ajoutez l'intergiciel Django à la liste des applications installées.
**Example settings.py — Applications installées**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
Configurez les paramètres disponibles dans un dictionnaire nommé `XRAY_RECORDER`.
**Example settings.py — Applications installées**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
'SAMPLING': False,
}
```
## Variables d’environnement
Vous pouvez utiliser des variables d'environnement pour configurer le SDK X-Ray pour Python. 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 du service que vous avez défini par programmation.
+ `AWS_XRAY_SDK_ENABLED`— Lorsqu'il est défini sur`false`, le SDK est désactivé. Par défaut, le kit SDK est activé, sauf si la variable d'environnement est définie sur false.
+ Lorsque cette option est désactivée, l'enregistreur mondial génère automatiquement des segments et des sous-segments fictifs qui ne sont pas envoyés au démon, et l'application automatique des correctifs est désactivée. Les intergiciels sont écrits en tant que wrapper sur l'enregistreur mondial. Tous les segments et sous-segments générés via l'intergiciel deviennent également des segments et sous-segments factices .
+ Définissez la valeur de `AWS_XRAY_SDK_ENABLED` via la variable d'environnement ou via une interaction directe avec l'objet `global_sdk_config` de la bibliothèque `aws_xray_sdk`. Les paramètres définis dans la variable d'environnement remplacent ces interactions.
+ `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray. Par défaut, le SDK utilise à la fois `127.0.0.1:2000` les données de trace (UDP) et l'échantillonnage (TCP). 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.
**Format**
+ **Même port** — `address:port`
+ **Différents ports** — `tcp:address:port udp:address:port`
+ `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 pour le middleware Python
**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 vous ajoutez le middleware à votre application et que vous configurez un nom de segment, le SDK X-Ray pour Python crée un segment pour chaque requête échantillonnée. Ce segment comprend la durée, la méthode et l'état de la demande HTTP. L'instrumentation supplémentaire crée des sous-segments sur ce segment.
Le SDK X-Ray pour Python prend en charge les intergiciels suivants pour instrumenter les requêtes HTTP entrantes :
+ Django
+ Flask
+ Bottle
**Note**
Pour les AWS Lambda fonctions, Lambda crée un segment pour chaque requête échantillonnée. Pour plus d’informations, consultez [AWS Lambda et AWS X-Ray](xray-services-lambda.md).
Voir un [Nœuds](scorekeep-lambda.md#scorekeep-lambda-worker) exemple de fonction Python instrumentée dans Lambda.
Pour les scripts ou applications Python sur d'autres frameworks, vous pouvez [créer des segments manuellement](#xray-sdk-python-middleware-manual).
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.
**Topics**
+ [Ajout des intergiciels à votre application (Django)](#xray-sdk-python-adding-middleware-django)
+ [Ajout des intergiciels à votre application (Flask)](#xray-sdk-python-adding-middleware-flask)
+ [Ajout des intergiciels à votre application (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Instrumentation manuelle du code Python](#xray-sdk-python-middleware-manual)
+ [Configuration d'une stratégie d'attribution de noms de segment](#xray-sdk-python-middleware-naming)
## Ajout des intergiciels à votre application (Django)
Ajoutez les intergiciels à la liste `MIDDLEWARE` dans le fichier `settings.py`. L'intergiciel X-Ray doit figurer sur la première ligne du fichier `settings.py` afin que les demandes qui échouent dans d'autres intergiciels soient enregistrées.
**Example settings.py - SDK X-Ray pour intergiciel Python**
```
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```
Ajoutez l'application Django du SDK X-Ray à la `INSTALLED_APPS` liste de votre `settings.py` fichier. Cela permettra de configurer l'enregistreur X-Ray lors du démarrage de votre application.
**Example settings.py - SDK X-Ray pour l'application Python Django**
```
INSTALLED_APPS = [
'aws_xray_sdk.ext.django',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
```
Configurez un nom de segment dans le fichier [`settings.py`](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py — Nom du segment**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
Cela indique à l'enregistreur X-Ray de suivre les requêtes traitées par votre application Django avec le taux d'échantillonnage par défaut. Vous pouvez [configurer les paramètres du fichier Django de l'enregistreur](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) pour appliquer les règles d'échantillonnage personnalisées ou modifier d'autres paramètres.
**Note**
Comme `plugins` ils sont transmis sous forme de tuple, veillez à inclure une fin `,` lorsque vous spécifiez un seul plugin. Par exemple, `plugins = ('EC2Plugin',)`
## Ajout des intergiciels à votre application (Flask)
Pour instrumenter l'application Flask, vous devez d'abord configurer un nom de segment dans l'élément `xray_recorder`. Utilisez ensuite la fonction `XRayMiddleware` pour corriger votre application Flask dans le code.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```
Cela indique à l'enregistreur X-Ray de suivre les demandes traitées par votre application Flask avec le taux d'échantillonnage par défaut. Vous pouvez [configurer l'enregistreur dans le code](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) pour appliquer les règles d'échantillonnage personnalisées ou modifier d'autres paramètres.
## Ajout des intergiciels à votre application (Bottle)
Pour instrumenter votre application Bottle, vous devez d'abord configurer un nom de segment dans l'élément `xray_recorder`. Utilisez ensuite la fonction `XRayMiddleware` pour corriger votre application Bottle dans le code.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
app = Bottle()
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```
Cela indique à l'enregistreur X-Ray de suivre les demandes traitées par votre application Bottle avec le taux d'échantillonnage par défaut. Vous pouvez [configurer l'enregistreur dans le code](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) pour appliquer les règles d'échantillonnage personnalisées ou modifier d'autres paramètres.
## Instrumentation manuelle du code Python
Si vous n'utilisez pas Django ni Flask, vous pouvez créer 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.
**Example main.py — Instrumentation manuelle**
```
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
# Close the subsegment and segment
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-python-adding-middleware-django).
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 dans Django, ajoutez le paramètre `DYNAMIC_NAMING` au fichier [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py — Dénomination dynamique**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
Vous pouvez utiliser '\$1' dans le modèle pour correspondre à n'importe quelle chaîne ou '?' pour correspondre à un seul caractère. Pour Flask, [configurez l'enregistreur dans le code](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py — Nom du segment**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**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-python-configuration.md#xray-sdk-python-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 Python afin de patcher les bibliothèques utilisées par votre application. Le SDK X-Ray pour Python peut appliquer des correctifs aux bibliothèques suivantes.
**Bibliothèques prises en charge**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK pour Python (Boto) Clients de l'instrument.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`— Version du client Amazon DynamoDB de l'instrument PynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Versions intégrées à Instrument [asyncio](https://docs.python.org/3/library/asyncio.html) du SDK pour les clients Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` — Clients HTTP de haut niveau de l'instrument.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)— Instrument les clients HTTP de bas niveau et les bibliothèques de niveau supérieur qui les utilisent.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Clients de l'instrument.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`— Instrument les clients MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)`— Interface PostgreSQL en Python pur de l'instrument.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`— Adaptateur de base de données PostgreSQL Instrument.
+ `[pymongo](https://pypi.org/project/pymongo/)`— Instrument les clients MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Clients basés sur Instrument PyMy SQL pour MySQL et MariaDB.
Lorsque vous utilisez une bibliothèque patchée, le SDK X-Ray pour Python crée un sous-segment pour l'appel et enregistre les informations 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' AWS Lambda.
**Note**
Si vous utilisez SQLAlchemy ORM, vous pouvez instrumenter vos requêtes SQL en important la version du SDK des classes SQLAlchemy de session et de requête. Voir [Utiliser l' SQLAlchemyORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) pour obtenir des instructions.
Pour corriger toutes les bibliothèques disponibles, utilisez la fonction `patch_all` dans `aws_xray_sdk.core`. Certaines bibliothèques, telles que `httplib` et `urllib`, peuvent avoir besoin d'activer la double application de correctifs en appelant `patch_all(double_patch=True)`.
**Example main.py — Corrige toutes les bibliothèques prises en charge**
```
import boto3
import botocore
import requests
import sqlite3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
```
Pour corriger une seule bibliothèque, appelez le `patch` selon un tuple du nom de la bibliothèque. Pour ce faire, vous devrez fournir une liste d'éléments unique.
**Example main.py — Bibliothèques spécifiques aux correctifs**
```
import boto3
import botocore
import requests
import mysql-connector-python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
libraries = (['botocore'])
patch(libraries)
```
**Note**
Dans certains cas, la clé que vous utilisez pour corriger une bibliothèque ne correspond pas au nom de la bibliothèque. Certaines clés tiennent lieu d'alias pour une ou plusieurs bibliothèques.
`httplib` – `[httplib](https://docs.python.org/2/library/httplib.html)` et [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`
## Suivi du contexte pour le travail asynchrone
Pour les bibliothèques `asyncio` intégrées ou pour [créer des sous-segments pour les fonctions asynchrones](xray-sdk-python-subsegments.md), vous devez également configurer le SDK X-Ray pour Python avec un contexte asynchrone. Importez la `AsyncContext` classe et transmettez-en une instance à l'enregistreur X-Ray.
**Note**
Les bibliothèques de support de l'infrastructure web, comme AIOHTTP, ne sont pas traitées via le module `aws_xray_sdk.core.patcher`. Elles n'apparaîtront pas dans le catalogue `patcher` des bibliothèques prises en charge.
**Example main.py — Correctif aioboto3**
```
import asyncio
import aioboto3
import requests
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch
libraries = (['aioboto3'])
patch(libraries)
```
# Suivi des appels du AWS SDK avec le SDK X-Ray pour Python
**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).
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 Python suit les appels en aval dans des [sous-segments](xray-sdk-python-subsegments.md). 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 Python instrumente automatiquement tous les clients du AWS SDK lorsque vous appliquez un [correctif à la `botocore` bibliothèque](xray-sdk-python-patching.md). 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
# Suivi des appels aux services Web HTTP en aval à l'aide du SDK X-Ray pour Python
**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).
Lorsque votre application fait des appels à des microservices ou à du protocole HTTP public APIs, vous pouvez utiliser le SDK X-Ray pour Python pour instrumenter ces appels et ajouter l'API au graphe de service en tant que service en aval.
Pour instrumenter les clients HTTP, [corrigez la bibliothèque](xray-sdk-python-patching.md) que vous utilisez pour effectuer les appels sortants. Si vous utilisez `requests` ou Python intégré dans un client HTTP, c'est tout ce dont vous avez besoin de faire. Pour `aiohttp`, configurez également l'enregistreur avec un [contexte asynchrone](xray-sdk-python-patching.md#xray-sdk-python-patching-async).
Si vous utilisez l'API client de `aiohttp` 3, vous devez également configurer `ClientSession` avec une instance de la configuration de suivi fournie par le kit SDK.
**Example [API Client `aiohttp` 3](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**
```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo():
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()
```
Lorsque vous instrumentez un appel à une API Web en aval, le SDK X-Ray pour Python enregistre un sous-segment contenant des informations sur la requête et la réponse HTTP. X-Ray utilise le sous-segment pour générer un segment inféré pour l'API distante.
**Example Sous-segment pour un appel HTTP en aval**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segment déduit pour un appel HTTP en aval**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Génération de sous-segments personnalisés avec le SDK X-Ray pour Python
**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`.
**Example main.py — Sous-segment personnalisé**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
Pour créer un sous-segment pour une fonction synchrone, utilisez le décorateur `@xray_recorder.capture`. Vous pouvez transmettre un nom pour le sous-segment à la fonction de capture ou le laisser utiliser le nom de la fonction.
**Example main.py — Sous-segment de fonction**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
Pour une fonction asynchrone, utilisez le décorateur `@xray_recorder.capture_async` et transmettez un contexte asynchrone à l'enregistreur.
**Example main.py — Sous-segment de fonction asynchrone**
```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')
async def create_user():
...
async def main():
await myfunc()
```
Lorsque vous créez un sous-segment au sein d'un segment ou d'un autre sous-segment, le SDK X-Ray pour Python génère un identifiant et enregistre l'heure de début et 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 Python
**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-python-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 Python](#xray-sdk-python-segment-annotations)
+ [Enregistrement de métadonnées avec le SDK X-Ray pour Python](#xray-sdk-python-segment-metadata)
+ [Utilisateur enregistrant IDs avec le SDK X-Ray pour Python](#xray-sdk-python-segment-userid)
## Enregistrer des annotations avec le SDK X-Ray pour Python
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
or
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Appelez `put_annotation` avec une clé de type chaîne et une valeur de type booléen, numérique ou chaîne.
```
document.put_annotation("mykey", "my value");
```
L'exemple suivant montre comment appeler `putAnnotation` avec une clé String qui inclut un point et une valeur booléenne, numérique ou de chaîne.
```
document.putAnnotation("testkey.test", "my value");
```
Vous pouvez également utiliser la méthode `put_annotation` sur le `xray_recorder`. Cette méthode enregistre les annotations sur le sous-segment actuel ou, si aucun sous-segment n'est ouvert, sur le segment.
```
xray_recorder.put_annotation("mykey", "my value");
```
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 `put_annotation` 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 Python
**Avertissement**
N'ajoutez pas d'objets comportant des références circulaires en tant que valeurs de métadonnées dans le kit de développement X-Ray pour Python. Ces objets ne peuvent pas être sérialisés en JSON et peuvent créer des boucles infinies dans le SDK. Évitez également d'ajouter des objets complexes et volumineux sous forme de métadonnées pour éviter les problèmes de performances.
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
or
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Appelez `put_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.
```
document.put_metadata("my key", "my value", "my namespace");
```
or
Appelez `put_metadata` avec seulement une clé et une valeur.
```
document.put_metadata("my key", "my value");
```
Vous pouvez également utiliser la méthode `put_metadata` sur le `xray_recorder`. Cette méthode enregistre les métadonnées sur le sous-segment actuel ou, si aucun sous-segment n'est ouvert, sur le segment.
```
xray_recorder.put_metadata("my key", "my value");
```
Si vous ne spécifiez pas d'espace de noms, le kit de développement logiciel utilise `default`. Si vous appelez deux fois `put_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 Python
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Appelez `setUser` avec l'ID de type chaîne de l'utilisateur ayant envoyé la demande.
```
document.set_user("U12345");
```
Vous pouvez appeler `set_user` 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).
# Instrumentation des infrastructures web déployées dans des environnements sans serveur
**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 AWS X-Ray pour Python permet d'instrumenter les frameworks Web déployés dans des applications sans serveur. Le sans serveur désigne l'architecture native du cloud qui vous permet de déléguer davantage de responsabilités opérationnelles à AWS ce qui augmente votre agilité et votre innovation.
L'architecture sans serveur est un modèle d'application logicielle qui vous permet de créer et d'exécuter des applications et des services sans vous soucier des serveurs. Cela permet d'éliminer les tâches de gestion des infrastructures, comme le provisionnement de serveur ou de cluster, la correction, la maintenance des systèmes d'exploitation et l'allocation de capacités. Vous pouvez en concevoir des solutions sans serveur pour pratiquement n'importe quel type d'application ou de service backend. Tous les aspects nécessaires à l'exécution et à la mise à l'échelle de votre application avec une haute disponibilité sont gérés à votre place.
Ce didacticiel vous montre comment instrumenter automatiquement AWS X-Ray sur un framework Web, tel que Flask ou Django, déployé dans un environnement sans serveur. L'instrumentation X-Ray de l'application vous permet de visualiser tous les appels en aval effectués, en commençant par Amazon API Gateway via votre AWS Lambda fonction, et les appels sortants effectués par votre application.
Le SDK X-Ray pour Python prend en charge les frameworks d'applications Python suivants :
+ Flask version 0.8 ou ultérieure
+ Django version 1.0 ou ultérieure
Ce didacticiel développe un exemple d'application sans serveur déployée sur Lambda et invoquée par API Gateway. Ce didacticiel utilise Zappa pour déployer automatiquement l'application sur Lambda et pour configurer le point de terminaison API Gateway.
## Conditions préalables
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) — Version 2.7 ou 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)— Vérifiez que vous êtes AWS CLI configuré avec le compte Région AWS dans lequel vous allez déployer votre application.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## Étape 1 : Créer un environnement
Au cours de cette étape, vous allez créer un environnement virtuel à l'aide de `virtualenv` pour héberger une application.
1. À l'aide du AWS CLI, créez un répertoire pour l'application. Accédez ensuite au nouveau répertoire.
```
mkdir serverless_application
cd serverless_application
```
1. Créez ensuite un environnement virtuel au sein de votre nouveau répertoire. Utilisez la commande suivante pour l'activer.
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. Installez X-Ray, Flask, Zappa et la bibliothèque Requests dans votre environnement.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. Ajoutez le code d'application au répertoire `serverless_application`. Pour cet exemple, nous pouvons effectuer la création à partir de l'exemple [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) de Flasks.
Dans le répertoire `serverless_application`, créez un fichier nommé `my_app.py`. Utilisez ensuite un éditeur de texte pour ajouter les commandes suivantes. Cette application instrumente la bibliothèque Requests, applique les correctifs de l'intergiciel de l'application Flask et ouvre le point de terminaison `'/'`.
```
# Import the X-Ray modules
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
from aws_xray_sdk.core import patcher, xray_recorder
from flask import Flask
import requests
# Patch the requests module to enable automatic instrumentation
patcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service name
xray_recorder.configure(service='My First Serverless App')
# Instrument the Flask application
XRayMiddleware(app, xray_recorder)
@app.route('/')
def hello_world():
resp = requests.get("https://aws.amazon.com")
return 'Hello, World: %s' % resp.url
```
## Étape 2 : Créer et déployer un environnement Zappa
Au cours de cette étape, vous utiliserez Zappa pour configurer automatiquement un point de terminaison API Gateway, puis le déployer sur Lambda.
1. Initialisez Zappa depuis le répertoire `serverless_application`. Pour cet exemple, nous utilisons les paramètres par défaut, mais si vous avez des préférences de personnalisation, Zappa affiche des instructions de configuration.
```
zappa init
```
```
What do you want to call this environment (default 'dev'): dev
...
What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
...
...
It looks like this is a Flask application.
What's the modular path to your app's function?
This will likely be something like 'your_module.app'.
We discovered: my_app.app
Where is your app's function? (default 'my_app.app'): my_app.app
...
Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
```
1. Activez X-Ray. Ouvrez le fichier `zappa_settings.json` et vérifiez s'il ressemble à l'exemple.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********"
}
}
```
1. Ajoutez `"xray_tracing": true` comme entrée au fichier de configuration.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********",
"xray_tracing": true
}
}
```
1. Déployez l'application. Cela configure automatiquement le point de terminaison API Gateway et télécharge votre code sur Lambda.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## Étape 3 : activer le suivi X-Ray pour API Gateway
Au cours de cette étape, vous allez interagir avec la console API Gateway pour activer le suivi X-Ray.
1. Connectez-vous à la console API Gateway AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
1. Recherchez votre API nouvellement générée. Vous devez obtenir quelque chose de similaire à `serverless-exam-dev`.
1. Choisissez **Stages (Étapes)**.
1. Choisissez le nom de votre étape de déploiement. La valeur par défaut est `dev`.
1. Sous l'onglet **Logs/Tracing (Journaux/Suivi)**, cochez la case **Enable X-Ray Tracing (Activer le suivi X-Ray)**.
1. Choisissez **Save Changes (Enregistrer les modifications)**.
1. Accédez au point de terminaison dans votre navigateur. Si vous avez utilisé l'exemple d'application `Hello World`, il doit afficher les éléments suivants.
```
"Hello, World: https://aws.amazon.com/"
```
## Étape 4 : Afficher le suivi créé
Au cours de cette étape, vous allez interagir avec la console X-Ray pour afficher la trace créée par l'exemple d'application. Pour obtenir une présentation plus détaillée de l'analyse des suivis, veuillez consulter [Affichage de la cartographie des services](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Affichez les segments générés par API Gateway, la fonction Lambda et le conteneur Lambda.
1. Sous le segment de fonction Lambda, visualisez un sous-segment nommé. `My First Serverless App` Il est suivi par un deuxième sous-segment nommé `https://aws.amazon.com`.
1. Lors de l'initialisation, Lambda peut également générer un troisième sous-segment nommé. `initialization`
![\[Vue du segment de suivi.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/serverless-traceView.png)
![\[Vue du graphique de services\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/serverless-serviceView.png)
## Étape 5 : nettoyer
Supprimez toujours les ressources que vous n'utilisez plus pour éviter d'accumuler des coûts imprévus. Comme le montre ce tutoriel, des outils tels que Zappa rationalisent le redéploiement sans serveur.
Pour supprimer votre application de Lambda, d'API Gateway et d'Amazon S3, exécutez la commande suivante dans le répertoire de votre projet à l'aide du. AWS CLI
```
zappa undeploy dev
```
## Étapes suivantes
Ajoutez des fonctionnalités supplémentaires à votre application en ajoutant des AWS clients et en les instrumentant avec X-Ray. Pour en savoir plus sur les options informatiques sans serveur, rendez-vous sur [Serverless](https://aws.amazon.com/serverless) on. AWS