View a markdown version of this page

AWS X-Ray SDK for Python - AWS X-Ray
RequisitiGestione delle dipendenze

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

AWS X-Ray SDK for Python

Nota

X-Ray SDK/Daemon Avviso di manutenzione: il 25 febbraio 2026, AWS X-Ray SDKs/Daemon entrerà in modalità manutenzione, in cui AWS limiterà le versioni di X-Ray SDK e Daemon per risolvere solo i problemi di sicurezza. Per ulteriori informazioni sulla tempistica dell'assistenza, consulta. Cronologia di X-Ray SDK e Daemon Support Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere Migrazione dalla X-Ray strumentazione alla strumentazione. OpenTelemetry

L' X-Ray SDK per Python è una libreria per applicazioni web Python che fornisce classi e metodi per generare e inviare dati di traccia al demone. X-Ray I dati di traccia includono informazioni sulle richieste HTTP in entrata servite dall'applicazione e sulle chiamate che l'applicazione effettua ai servizi downstream utilizzando l' AWS SDK, i client HTTP o un connettore di database SQL. Puoi anche possibile creare manualmente dei segmenti e aggiungere informazioni di debug in annotazioni e metadati.

Puoi scaricare l'SDK tramite pip.

$ pip install aws-xray-sdk
Nota

L' X-Ray SDK per Python è un progetto open source. Puoi seguire il progetto e inviare problemi e richieste pull su GitHub: github. com/aws/aws-xray-sdk-python

Se utilizzi Django o Flask, per tracciare le richieste in entrata inizia aggiungendo il middleware dell'SDK alla tua applicazione. Il middleware crea un segmento per ogni richiesta tracciata e completa il segmento quando viene inviata la risposta. Fino a che il segmento è aperto, puoi usare i metodi del client dell'SDK per aggiungere informazioni al segmento e creare sottosegmenti per tracciare le chiamate a valle. L'SDK, inoltre, registra automaticamente le eccezioni sollevate dall'applicazione per il tempo durante il quale il segmento è aperto. Per altre applicazioni, puoi creare i segmenti manualmente.

Per le funzioni Lambda richiamate da un'applicazione o un servizio con strumenti, Lambda legge l'intestazione di tracciamento e traccia automaticamente le richieste campionate. Intestazione di tracciamento Per altre funzioni, puoi configurare Lambda per campionare e tracciare le richieste in arrivo. In entrambi i casi, Lambda crea il segmento e lo fornisce all'SDK. X-Ray

Nota

Su Lambda, l' X-Ray SDK è opzionale. Se non lo usi nella tua funzione, la mappa del servizio includerà comunque un nodo per il servizio Lambda e uno per ogni funzione Lambda. Aggiungendo l'SDK, puoi utilizzare il codice della funzione per aggiungere sottosegmenti al segmento di funzione registrato da Lambda. Per ulteriori informazioni, consulta AWS Lambda e AWS X-Ray.

Vedi Worker per un esempio di funzione Python strumentata in Lambda.

Quindi, usa l' X-Ray SDK per Python per strumentare le chiamate a valle applicando patch alle librerie della tua applicazione. L'SDK supporta le seguenti librerie.

Librerie supportate

  • botocore, boto3 — Client per strumenti. AWS SDK for Python (Boto)

  • pynamodb— La versione di Instrument PynamoDB del client Amazon DynamoDB.

  • aiobotocore, aioboto3 — Instrument asyncio: versioni integrate dell'SDK per client Python (Boto3).

  • requests, — Client HTTP di alto livello per Instrument. aiohttp

  • httplib, http.client — Client HTTP di basso livello dello strumento e librerie di livello superiore che li utilizzano.

  • sqlite3— Client SQLite di Instrument.

  • mysql-connector-python— Client MySQL di Instrument.

  • pg8000— Interfaccia Pure-Python PostgreSQL dello strumento.

  • psycopg2— Adattatore per database PostgreSQL Instrument.

  • pymongo— Client MongoDB per strumenti.

  • pymysql— Client basati su PyMy SQL di Instrument per MySQL e MariaDB.

Ogni volta che l'applicazione effettua chiamate a AWS, a un database SQL o ad altri servizi HTTP, l'SDK registra le informazioni sulla chiamata in un sottosegmento. Servizi AWS e le risorse a cui accedi all'interno dei servizi vengono visualizzate come nodi a valle sulla mappa di traccia per aiutarti a identificare errori e problemi di limitazione sulle singole connessioni.

Dopo aver iniziato a utilizzare l'SDK, personalizzane il comportamento configurando il registratore e il middleware. Puoi aggiungere dei plugin per memorizzare i dati sulle risorse di elaborazione sulle quali è eseguita la tua applicazione, personalizzare il comportamento di campionamento definendo regole di campionatura e impostare il livello di log per visualizzare più o meno informazioni generate dall'SDK nei log dell'applicazione.

Registra ulteriori informazioni sulle richieste e sull'attività svolta dalla tua applicazione in annotazioni e metadati. Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con espressioni filtro, in modo da poter cercare tracce che contengono dati specifici. Le immissioni di metadati sono meno restrittive e possono registrare interi oggetti e array, qualsiasi cosa che possa essere serializzata in JSON.

Annotazioni e metadata

Le annotazioni e i metadati sono testo arbitrario che aggiungi ai segmenti con l'SDK. X-Ray Le annotazioni sono indicizzate per essere utilizzate con le espressioni di filtro. I metadati non sono indicizzati, ma possono essere visualizzati nel segmento raw con la console o l'API. X-Ray Chiunque conceda l'accesso in lettura X-Ray può visualizzare questi dati.

Quando disponi di una notevole quantità di client analizzati nel tuo codice, un singolo segmento per la richiesta può contenere un numero elevato di sottosegmenti, uno per ciascuna delle chiamate effettuate con un client analizzato. Puoi organizzare e raggruppare i sottosegmenti inglobando le chiamate del client sottosegmenti personalizzati. Puoi creare un sottosegmento personalizzato per un'intera funzione o per qualsiasi parte del codice. Puoi quindi memorizzare metadati e annotazioni nel sottosegmento invece di scrivere tutto all'interno del segmento padre.

Per la documentazione di riferimento per le classi e i metodi dell'SDK, consulta l'AWS X-Ray SDK for Python API Reference.

Requisiti

L' X-Ray SDK per Python supporta le seguenti versioni del linguaggio e della libreria.

  • Python: 2.7, 3.4 e versioni successive

  • Django — 1.10 e versioni successive

  • Flask — 0.10 e versioni successive

  • aiohttp — 2.3.0 e versioni successive

  • AWS SDK for Python (Boto)— 1.4.0 e versioni successive

  • botocore — 1.5.0 e versioni successive

  • enum — 0.4.7 e versioni successive, per le versioni di Python 3.4.0 e precedenti

  • jsonpickle — 1.0.0 e versioni successive

  • setuptools — 40.6.3 e versioni successive

  • wrapt — 1.11.0 e versioni successive

Gestione delle dipendenze

L' X-Ray SDK per Python è disponibile da. pip

  • Pacchetto: aws-xray-sdk

Aggiungi l'SDK come dipendenza nel file requirements.txt.

Esempio requirements.txt
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3

Se si utilizza Elastic Beanstalk per distribuire l'applicazione, Elastic Beanstalk installa automaticamente tutti i pacchetti. requirements.txt