Configuration du kit SDK X-Ray pour Python

Le kit SDK X-Ray pour Python 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 :EC2Plugin ajoute l'ID d'instance, la zone de disponibilité et le groupe de CloudWatch journaux.

• Elastic Beanstalk :ElasticBeanstalkPlugin ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement.

• Amazon ECS :ECSPlugin ajoute l'ID du conteneur.

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

Commeplugins 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, 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 pour enregistrer les appels en aval.

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

ActivéAWS Lambda, vous ne pouvez pas modifier la fréquence d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des requêtes é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, appelez xray_recorder.configure, comme illustré dans l'exemple suivant, où rules représente soit un dictionnaire de règles soit le chemin absolu d'un fichier JSON contenant les 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.

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

xray_recorder.configure(sampling=False)

Journalisation

Le SDK utilise lelogging module intégré de Python avec un niveau deWARNING 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.

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

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.

• service— Définissez un nom de service que le SDK utilise pour les segments.

• plugins— Enregistrez des informations sur lesAWS ressources de votre application.

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

• sampling_rules— Définissez le chemin du fichier JSON contenant vos règles d'échantillonnage.

Exemple main.py — Désactive les exceptions manquantes au 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— 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.

• AWS_XRAY_DAEMON_ADDRESS— Définissez l'hôte et le port de l'écouteur du démon X-Ray.

• AWS_XRAY_TRACING_NAME— Définissez un nom de service que le SDK utilise pour les segments.

• PLUGINS— Enregistrez des informations sur lesAWS ressources de votre application.

• SAMPLING— Réglez surFalse pour désactiver l'échantillonnage.

• SAMPLING_RULES— Définissez le chemin du fichier JSON contenant vos règles d'échantillonnage.

Pour activer la configuration de l'enregistreur dans settings.py, ajoutez l'intergiciel Django à la liste des applications installées.

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

Exemple 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 kit 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— Lorsque ce paramètre est défini surfalse, désactive le SDK. 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 démon X-Ray. Par défaut, le SDK utilise à la fois127.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 autre port 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— 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— Lance 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.