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à.
# Uso di Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
Esistono due modi per strumentare un'applicazione Python per inviare tracce a X-Ray:
+ [AWS Distro for OpenTelemetry Python](xray-python-opentel-sdk.md)[: AWS una distribuzione che fornisce un set di librerie open source per l'invio di metriche e tracce correlate a AWS più soluzioni di monitoraggio, tra cui Amazon e OpenSearch Amazon Service CloudWatch AWS X-Ray, tramite AWS Distro for Collector. OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/collector)
+ [AWS X-Ray SDK per Python](xray-sdk-python.md) [— Un insieme di librerie per generare e inviare tracce a X-Ray tramite il demone X-Ray.](xray-daemon.md)
Per ulteriori informazioni, consulta [Scelta tra AWS Distro for OpenTelemetry e X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro per Python OpenTelemetry
Con AWS Distro for OpenTelemetry (ADOT) Python, puoi strumentare le tue applicazioni una sola volta e inviare metriche e tracce correlate a più AWS soluzioni di monitoraggio tra cui Amazon e Amazon Service. CloudWatch AWS X-Ray OpenSearch L'utilizzo di X-Ray con ADOT richiede due componenti: un *OpenTelemetry SDK* abilitato per l'uso con X-Ray e *AWS Distro for OpenTelemetry Collector* abilitato per l'uso con X-Ray. ADOT Python include il supporto per la strumentazione automatica, che consente all'applicazione di inviare tracce senza modifiche al codice.
Per iniziare, consulta la documentazione di [AWS Distro for OpenTelemetry Python](https://aws-otel.github.io/docs/getting-started/python-sdk).
[Per ulteriori informazioni sull'utilizzo di AWS Distro for OpenTelemetry with AWS X-Ray e altro Servizi AWS, consulta [AWS Distro for OpenTelemetry o Distro for Documentation](https://aws-otel.github.io/).AWS OpenTelemetry ](https://aws-otel.github.io/docs/introduction)
[Per ulteriori informazioni sul supporto e l'utilizzo della lingua, vedere AWS Observability on. GitHub](https://github.com/aws-observability)
# AWS X-Ray SDK per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
X-Ray SDK for 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 fornite 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 for Python è un progetto open source. [Puoi seguire il progetto e inviare problemi e richieste pull su GitHub: github. com/aws/aws- xray-sdk-python](https://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](xray-sdk-python-middleware.md). Il middleware crea un [segmento](xray-concepts.md#xray-concepts-segments) 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](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
Per le funzioni Lambda richiamate da un'applicazione o un servizio strumentato, Lambda legge l'intestazione di [tracciamento e traccia automaticamente le richieste campionate](xray-concepts.md#xray-concepts-tracingheader). Per altre funzioni, puoi [configurare Lambda](xray-services-lambda.md) per campionare e tracciare le richieste in arrivo. In entrambi i casi, Lambda crea il segmento e lo fornisce all'X-Ray SDK.
**Nota**
Su Lambda, l'SDK X-Ray è opzionale. Se non lo usi nella tua funzione, la mappa dei servizi 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](xray-services-lambda.md).
Vedi un [Worker](scorekeep-lambda.md#scorekeep-lambda-worker) esempio di funzione Python strumentata in Lambda.
[Successivamente, usa l'X-Ray SDK per Python per strumentare le chiamate downstream applicando patch alle librerie dell'applicazione.](xray-sdk-python-patching.md) L'SDK supporta le seguenti librerie.
**Librerie supportate**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, — Client per strumenti. `[boto3](https://pypi.python.org/pypi/boto3)` AWS SDK per Python (Boto)
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`— La versione di Instrument PynamoDB del client Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Versioni integrate di Instrument [Asyncio](https://docs.python.org/3/library/asyncio.html) di SDK per client Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` — Client HTTP di alto livello dello strumento.
+ `[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)— I client HTTP di basso livello dello strumento e le librerie di livello superiore che li utilizzano.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Client di strumenti.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`— Client MySQL di Instrument.
+ `[pg8000](https://pypi.org/project/pg8000/)`— Interfaccia PostgreSQL dello strumento Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`— Adattatore per database PostgreSQL Instrument.
+ `[pymongo](https://pypi.org/project/pymongo/)`— Client Instrument MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Client basati su Instrument PyMy SQL per MySQL e MariaDB.
Ogni volta che l'applicazione effettua chiamate a AWS 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](xray-sdk-python-configuration.md) 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](xray-sdk-python-segment.md). Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con [espressioni filtro](xray-console-filters.md), in modo da poter cercare tracce che contengono dati specifici. Le immissioni di metadati sono meno restrittive e possono registrare interi oggetti e array, ovvero tutto ciò che può essere serializzato in JSON.
**Annotazioni e metadata**
Le annotazioni e i metadati sono testo arbitrario che aggiungi ai segmenti con X-Ray SDK. Le annotazioni vengono indicizzate per essere utilizzate con le espressioni di filtro. I metadati non sono indicizzati, ma possono essere visualizzati nel segmento non elaborato con la console X-Ray o l'API. Chiunque conceda l'accesso in lettura a 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](xray-sdk-python-subsegments.md). 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](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference) API Reference.
## Requisiti
L'X-Ray SDK per Python supporta le seguenti versioni di linguaggio e 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 per 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`
+ **Package** — `aws-xray-sdk`
Aggiungi l'SDK come dipendenza nel file `requirements.txt`.
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Se utilizzi Elastic Beanstalk per distribuire l'applicazione, Elastic Beanstalk installa automaticamente tutti i pacchetti. `requirements.txt`
# Configurazione dell'SDK X-Ray per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
L'X-Ray SDK per Python ha una classe denominata `xray_recorder` che fornisce il registratore globale. Puoi configurare il registratore globale per personalizzare il middleware che crea i segmenti relativi alle chiamate HTTP in entrata.
**Topics**
+ [Plugin di servizio](#xray-sdk-python-configuration-plugins)
+ [Regole di campionamento](#xray-sdk-python-configuration-sampling)
+ [Registrazione dei log](#xray-sdk-python-configuration-logging)
+ [Configurazione del registratore nel codice](#xray-sdk-python-middleware-configuration-code)
+ [Configurazione del registratore con Django](#xray-sdk-python-middleware-configuration-django)
+ [Variabili di ambiente](#xray-sdk-python-configuration-envvars)
## Plugin di servizio
`plugins`Utilizzatelo per registrare informazioni sul servizio che ospita l'applicazione.
**Plugin**
+ Amazon EC2 : `EC2Plugin` aggiunge l'ID dell'istanza, la zona di disponibilità e il gruppo di CloudWatch log.
+ Elastic `ElasticBeanstalkPlugin` Beanstalk: aggiunge il nome dell'ambiente, l'etichetta della versione e l'ID di distribuzione.
+ Amazon ECS: `ECSPlugin` aggiunge l'ID del contenitore.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
Per usare un plugin, chiama `configure` sul tuo `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()
```
**Nota**
Poiché `plugins` vengono passati come tupla, assicurati di includere un finale `,` quando specifichi un singolo plug-in. Ad esempio, `plugins = ('EC2Plugin',)`
Per configurare il registratore puoi anche utilizzare le [variabili di ambiente](#xray-sdk-python-configuration-envvars), che hanno la precedenza sui valori impostati nel codice.
Configura i plugin prima [applicare le patch alle librerie](xray-sdk-python-patching.md) per memorizzare le chiamate a valle.
L'SDK utilizza anche le impostazioni del plug-in per impostare il `origin` campo sul segmento. Indica il tipo di AWS risorsa che esegue l'applicazione. Quando utilizzate più plugin, l'SDK utilizza il seguente ordine di risoluzione per determinare l'origine: ElasticBeanstalk > EKS > ECS >. EC2
## Regole di campionamento
L'SDK utilizza le regole di campionamento definite nella console X-Ray per determinare quali richieste registrare. La regola predefinita tiene traccia della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive su tutti i servizi che inviano tracce a X-Ray. [Crea regole aggiuntive nella console X-Ray](xray-console-sampling.md) per personalizzare la quantità di dati registrati per ciascuna delle tue applicazioni.
L'SDK applica le regole personalizzate nell'ordine in cui sono definite. Se una richiesta corrisponde a più regole personalizzate, l'SDK applica solo la prima regola.
**Nota**
Se l'SDK non riesce a contattare X-Ray per ottenere le regole di campionamento, torna a una regola locale predefinita della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive per host. Ciò può verificarsi se l'host non dispone dell'autorizzazione per chiamare sampling APIs o non riesce a connettersi al demone X-Ray, che funge da proxy TCP per le chiamate API effettuate dall'SDK.
Puoi anche configurare l'SDK per caricare le regole di campionamento da un documento JSON. L'SDK può utilizzare le regole locali come backup per i casi in cui il campionamento a raggi X non è disponibile o utilizzare esclusivamente regole locali.
**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
}
}
```
Questo esempio definisce una regola personalizzata e una regola predefinita. La regola personalizzata applica una frequenza di campionamento del cinque percento senza alcun numero minimo di richieste da tracciare per i percorsi. `/api/move/` La regola predefinita tiene traccia della prima richiesta ogni secondo e del 10% delle richieste aggiuntive.
Lo svantaggio della definizione locale delle regole è che l'obiettivo fisso viene applicato da ciascuna istanza del registratore in modo indipendente, anziché essere gestito dal servizio X-Ray. Man mano che si installano più host, la tariffa fissa si moltiplica, rendendo più difficile il controllo della quantità di dati registrati.
Sì AWS Lambda, non è possibile modificare la frequenza di campionamento. Se la funzione viene chiamata da un servizio strumentato, le chiamate che hanno generato richieste campionate da quel servizio verranno registrate da Lambda. Se il tracciamento attivo è abilitato e non è presente alcuna intestazione di tracciamento, Lambda prende la decisione di campionamento.
Per configurare le regole di campionamento di backup, chiamate`xray_recorder.configure`, come illustrato nell'esempio seguente, where *rules* è un dizionario di regole o il percorso assoluto di un file JSON contenente le regole di campionamento.
```
xray_recorder.configure(sampling_rules=rules)
```
Per utilizzare solo regole locali, configura un registratore con una `LocalSampler`.
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
Puoi anche configurare il registratore globale per disabilitare il campionamento e analizzare tutte le richieste in entrata.
**Example main.py — Disabilita il campionamento**
```
xray_recorder.configure(sampling=False)
```
## Registrazione dei log
L'SDK utilizza il `logging` modulo integrato di Python con un livello di registrazione predefinito`WARNING`. Ottieni un riferimento al logger per la classe `aws_xray_sdk` e chiama `setLevel` per configurare il livello di log differenti per la libreria e il resto dell'applicazione.
**Example app.py — Registrazione**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
Utilizza i log di debug per identificare i problemi, come ad esempio dei sottosegmenti non chiusi, quando [generi dei sottosegmenti manualmente](xray-sdk-python-subsegments.md).
## Configurazione del registratore nel codice
Impostazioni aggiuntive sono disponibili tramite il metodo `configure` su `xray_recorder`.
+ `context_missing`— Imposta per `LOG_ERROR` evitare di generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.
+ `daemon_address`— Imposta l'host e la porta del demone X-Ray.
+ `service`— Imposta un nome di servizio che l'SDK utilizza per i segmenti.
+ `plugins`— Registra informazioni sulle risorse dell'applicazione. AWS
+ `sampling`— Impostato per `False` disabilitare il campionamento.
+ `sampling_rules`— Imposta il percorso del file JSON contenente le regole di [campionamento](#xray-sdk-python-configuration-sampling).
**Example main.py — Disattiva le eccezioni mancanti nel contesto**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Configurazione del registratore con Django
Se utilizzi il framework Django, puoi utilizzare il file `settings.py` di Django per configurare le opzioni del registratore globale.
+ `AUTO_INSTRUMENT`(Solo Django) — Registra i sottosegmenti per le operazioni di rendering di database e modelli integrate.
+ `AWS_XRAY_CONTEXT_MISSING`— Imposta per `LOG_ERROR` evitare di generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.
+ `AWS_XRAY_DAEMON_ADDRESS`— Imposta l'host e la porta del demone X-Ray.
+ `AWS_XRAY_TRACING_NAME`— Imposta un nome di servizio che l'SDK utilizza per i segmenti.
+ `PLUGINS`— Registra informazioni sulle risorse dell'applicazione. AWS
+ `SAMPLING`— Impostato per `False` disabilitare il campionamento.
+ `SAMPLING_RULES`— Imposta il percorso del file JSON contenente le regole di [campionamento](#xray-sdk-python-configuration-sampling).
Per abilitare la configurazione del registratore in `settings.py`, aggiungi il middleware Django all'elenco delle applicazioni.
**Example settings.py — App installate**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
Configura le impostazioni disponibili in un dizionario denominato `XRAY_RECORDER`.
**Example settings.py — App installate**
```
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,
}
```
## Variabili di ambiente
È possibile utilizzare le variabili di ambiente per configurare l'SDK X-Ray per Python. L'SDK supporta le seguenti variabili:
+ `AWS_XRAY_TRACING_NAME`— Imposta un nome di servizio che l'SDK utilizza per i segmenti. Sostituisce il nome del servizio impostato a livello di programmazione.
+ `AWS_XRAY_SDK_ENABLED`— Se impostato su`false`, disabilita l'SDK. Per impostazione predefinita, l'SDK è abilitato solo se la variabile di ambiente è impostata su false.
+ Quando l'SDK è disabilitato, il registratore globale genera automaticamente segmenti o sottosegmenti fittizi che non vengono inviati al daemon e l'applicazione automatica di patch è disattivata. I middleware vengono scritti come wrapper per il registratore globale. Anche tutti i segmenti e sottosegmenti generati tramite il middleware diventano segmenti e sottosegmenti fittizi.
+ Imposta il valore di `AWS_XRAY_SDK_ENABLED` tramite la variabile di ambiente o l'interazione diretta con l'oggetto `global_sdk_config` dalla libreria `aws_xray_sdk`. Le impostazioni con la variabile di ambiente sostituiscono le interazioni.
+ `AWS_XRAY_DAEMON_ADDRESS`— Imposta l'host e la porta del demone X-Ray. Per impostazione predefinita, l'SDK utilizza `127.0.0.1:2000` sia i dati di traccia (UDP) che il campionamento (TCP). Utilizzate questa variabile se avete configurato il demone per l'[ascolto su una porta diversa](xray-daemon-configuration.md) o se è in esecuzione su un host diverso.
**Formato**
+ **Stessa porta** — `address:port`
+ **Porte diverse**: `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`— Imposta `RUNTIME_ERROR` per generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.
**Valori validi**
+ `RUNTIME_ERROR`— Genera un'eccezione di runtime.
+ `LOG_ERROR`— Registra un errore e continua (impostazione predefinita).
+ `IGNORE_ERROR`— Ignora l'errore e continua.
Gli errori relativi a segmenti o sottosegmenti mancanti possono verificarsi quando si tenta di utilizzare un client con strumenti nel codice di avvio che viene eseguito quando non è aperta alcuna richiesta o nel codice che genera un nuovo thread.
Le variabili di ambiente sostituiscono i valori impostati nel codice.
# Tracciamento delle richieste in arrivo con il middleware X-Ray SDK per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
Quando aggiungi il middleware all'applicazione e configuri il nome di un segmento, X-Ray SDK for Python crea un segmento per ogni richiesta campionata. Questo segmento include durata, metodo e conclusione della richiesta HTTP. Analisi ulteriori creano sottosegmenti associati a questo segmento.
L'X-Ray SDK per Python supporta il seguente middleware per strumentare le richieste HTTP in arrivo:
+ Django
+ Flask
+ Bottle
**Nota**
Per quanto riguarda AWS Lambda le funzioni, Lambda crea un segmento per ogni richiesta campionata. Per ulteriori informazioni, consulta [AWS Lambda e AWS X-Ray](xray-services-lambda.md).
Vedi un [Worker](scorekeep-lambda.md#scorekeep-lambda-worker) esempio di funzione Python strumentata in Lambda.
Per gli script o le applicazioni Python su altri framework, puoi [creare i segmenti manualmente](#xray-sdk-python-middleware-manual).
Ogni segmento ha un nome che identifica l'applicazione nella mappa dei servizi. Il segmento può essere denominato staticamente oppure è possibile configurare l'SDK per denominarlo dinamicamente in base all'intestazione dell'host nella richiesta in entrata. La denominazione dinamica consente di raggruppare le tracce in base al nome di dominio nella richiesta e di applicare un nome predefinito se il nome non corrisponde a uno schema previsto (ad esempio, se l'intestazione dell'host è falsificata).
**Richieste inoltrate**
Se un sistema di bilanciamento del carico o un altro intermediario inoltra una richiesta all'applicazione, X-Ray prende l'IP del client dall'`X-Forwarded-For`intestazione della richiesta anziché dall'IP di origine nel pacchetto IP. L'IP del client registrato per una richiesta inoltrata può essere falsificato, quindi non dovrebbe essere considerato attendibile.
Quando viene inoltrata una richiesta, l'SDK imposta un campo aggiuntivo nel segmento per indicarlo. Se il segmento contiene il campo `x_forwarded_for` impostato su`true`, l'IP del client è stato preso dall'`X-Forwarded-For`intestazione della richiesta HTTP.
Il middleware crea un segmento per ogni richiesta in entrata con un blocco `http` che contiene le informazioni riportate qui di seguito:
+ **Metodo HTTP**: GET, POST, PUT, DELETE, ecc.
+ **Indirizzo client**: l'indirizzo IP del client che ha inviato la richiesta.
+ **Codice di risposta**: il codice di risposta HTTP per la richiesta completata.
+ **Tempistica**: l'ora di inizio (quando è stata ricevuta la richiesta) e l'ora di fine (quando è stata inviata la risposta).
+ **Agente utente**: il `user-agent` codice della richiesta.
+ **Lunghezza del contenuto**: il `content-length` risultato della risposta.
**Topics**
+ [Aggiunta del middleware all'applicazione (Django)](#xray-sdk-python-adding-middleware-django)
+ [Aggiunta del middleware all'applicazione (flask)](#xray-sdk-python-adding-middleware-flask)
+ [Aggiunta del middleware all'applicazione (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Analisi manuale del codice Python](#xray-sdk-python-middleware-manual)
+ [Configurazione di una strategia di denominazione dei segmenti](#xray-sdk-python-middleware-naming)
## Aggiunta del middleware all'applicazione (Django)
Aggiungi il middleware all'elenco `MIDDLEWARE` nel tuo file `settings.py`. Il middleware X-Ray dovrebbe essere presente nella prima riga del tuo file `settings.py` per assicurarti che le richieste che non ricadano sotto il controllo di altri middleware quando vengono registrate.
**Example settings.py - X-Ray SDK per middleware 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'
]
```
Aggiungi l'app X-Ray SDK Django all'`INSTALLED_APPS`elenco del tuo file. `settings.py` Ciò consentirà di configurare il registratore X-Ray durante l'avvio dell'app.
**Example settings.py - X-Ray SDK per l'app 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',
]
```
Configurazione di un nome di segmento nel tuo [file `settings.py`](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py — Nome del segmento**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
Questo dice al registratore X-Ray di tracciare le richieste servite dall'applicazione Django con la frequenza di campionamento predefinita. Puoi [configurare il file delle impostazioni del registratore Django](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) affinché applichi le regole di campionatura personalizzate o modificare altre impostazioni.
**Nota**
Poiché `plugins` vengono passate come tupla, assicuratevi di includere un finale quando specificate un singolo plugin. `,` Ad esempio, `plugins = ('EC2Plugin',)`
## Aggiunta del middleware all'applicazione (flask)
Per analizzare la tua applicazione, prima di tutto configura un nome di segmento in `xray_recorder`. Quindi, utilizza la funzione `XRayMiddleware` per applicare una patch al codice dell'applicazione Flask.
**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)
```
Questo indica al registratore X-Ray di tracciare le richieste servite dall'applicazione Flask con la frequenza di campionamento predefinita. Puoi [configurare il registratore all'interno del codice](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) affinché applichi le regole di campionatura personalizzate o modificare altre impostazioni.
## Aggiunta del middleware all'applicazione (Bottle)
Per analizzare l'applicazione Bottle, prima di tutto configura un nome di segmento in `xray_recorder`. Quindi, utilizza la funzione `XRayMiddleware` per applicare una patch al codice dell'applicazione Bottle.
**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))
```
Questo indica al registratore X-Ray di tracciare le richieste servite dall'applicazione Bottle con la frequenza di campionamento predefinita. Puoi [configurare il registratore all'interno del codice](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) affinché applichi le regole di campionatura personalizzate o modificare altre impostazioni.
## Analisi manuale del codice Python
Se non utilizzi Django o Flask, puoi creare i segmenti manualmente. È possibile creare un segmento per ogni richiesta in arrivo o creare segmenti attorno ai client HTTP o AWS SDK con patch per fornire al registratore il contesto in cui aggiungere sottosegmenti.
**Example main.py — Strumentazione manuale**
```
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()
```
## Configurazione di una strategia di denominazione dei segmenti
AWS X-Ray utilizza un *nome di servizio* per identificare l'applicazione e distinguerla dalle altre applicazioni, database, AWS risorse esterne APIs e utilizzate dall'applicazione. [Quando X-Ray SDK genera segmenti per le richieste in entrata, registra il nome del servizio dell'applicazione nel campo del nome del segmento.](xray-api-segmentdocuments.md#api-segmentdocuments-fields)
L'X-Ray SDK può denominare i segmenti dopo il nome host nell'intestazione della richiesta HTTP. Tuttavia, questa intestazione può essere falsificata, il che potrebbe causare nodi imprevisti nella mappa dei servizi. Per evitare che l'SDK nomini i segmenti in modo errato a causa di richieste con intestazioni host contraffatte, è necessario specificare un nome predefinito per le richieste in entrata.
Se la tua applicazione soddisfa le richieste per più domini, puoi configurare l'SDK in modo che utilizzi una strategia di denominazione dinamica che rifletta questo aspetto nei nomi dei segmenti. Una strategia di denominazione dinamica consente all'SDK di utilizzare il nome host per le richieste che corrispondono a uno schema previsto e di applicare il nome predefinito alle richieste che non lo fanno.
Ad esempio, potresti avere una singola applicazione che serve le richieste a tre sottodomini:, e. `www.example.com` `api.example.com` `static.example.com` È possibile utilizzare una strategia di denominazione dinamica con lo schema `*.example.com` per identificare i segmenti per ogni sottodominio con un nome diverso, ottenendo tre nodi di servizio sulla mappa dei servizi. Se l'applicazione riceve richieste con un nome host che non corrisponde allo schema, sulla mappa dei servizi verrà visualizzato un quarto nodo con un nome di fallback specificato dall'utente.
Per utilizzare lo stesso nome per tutti i segmenti della richiesta, specifica il nome della tua applicazione quando configuri il registratore, come illustrato [nelle sezioni precedenti](#xray-sdk-python-adding-middleware-django).
Una strategia di denominazione dinamica definisce un modello al quale devono corrispondere i nomi degli host e un nome di default per l'utilizzo qualora il nome dell'host nella richiesta HTTP non corrisponda al modello. Per denominare in modo dinamico i segmenti in Django, aggiungere l'impostazione `DYNAMIC_NAMING` al tuo file [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py — Denominazione dinamica**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
Puoi utilizzare '\$1' nel modello per una corrispondenza con qualsiasi stringa o '?' per una corrispondenza con qualsiasi carattere singolo. Per Flask, [configura il registratore nel codice](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py — Nome del segmento**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**Nota**
È possibile sovrascrivere il nome di servizio predefinito definito nel codice con la [variabile di `AWS_XRAY_TRACING_NAME` ambiente](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars).
# Applicare le patch alle librerie per analizzare le chiamate a valle
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
Per strumentare le chiamate downstream, usa l'X-Ray SDK for Python per applicare patch alle librerie utilizzate dall'applicazione. L'X-Ray SDK per Python può applicare patch alle seguenti librerie.
**Librerie supportate**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — Client per strumenti. AWS SDK per Python (Boto)
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)`— La versione del client Amazon DynamoDB di Instrument PynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` — Versioni integrate di Instrument [Asyncio](https://docs.python.org/3/library/asyncio.html) di SDK per client Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` — Client HTTP di alto livello dello strumento.
+ `[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)— I client HTTP di basso livello dello strumento e le librerie di livello superiore che li utilizzano.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Client di strumenti.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`— Client MySQL di Instrument.
+ `[pg8000](https://pypi.org/project/pg8000/)`— Interfaccia PostgreSQL dello strumento Pure-Python.
+ `[psycopg2](https://pypi.org/project/psycopg2/)`— Adattatore per database PostgreSQL Instrument.
+ `[pymongo](https://pypi.org/project/pymongo/)`— Client Instrument MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Client basati su Instrument PyMy SQL per MySQL e MariaDB.
Quando si utilizza una libreria con patch, X-Ray SDK for Python crea un sottosegmento per la chiamata e registra le informazioni dalla richiesta e dalla risposta. Un segmento devono essere disponibili affinché l'SDK possa creare il sottosegmento, sia dal middleware dell'SDK che da AWS Lambda.
**Nota**
Se utilizzi SQLAlchemy ORM, puoi strumentare le tue query SQL importando la versione SDK delle classi di sessione e di query. SQLAlchemy Per istruzioni, consulta [ SQLAlchemyUse](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) ORM.
Per installare le patch disponibili per tutte le librerie, utilizza la funzione `patch_all` in `aws_xray_sdk.core`. Alcune librerie, ad esempio `httplib` e `urllib`, potrebbero dover abilitare l'applicazione di patch doppie chiamando `patch_all(double_patch=True)`.
**Example main.py: applica una patch a tutte le librerie supportate**
```
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()
```
Per applicare patch a una singola libreria, chiamare `patch` con una tupla del nome della libreria. Per raggiungere questo risultato, è necessario fornire un singolo elenco di elementi.
**Example main.py: applica patch a librerie specifiche**
```
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)
```
**Nota**
In alcuni casi, la chiave utilizzata per installare le patch di una libreria non corrisponde al nome della libreria. Alcune chiavi servono come alias per una o più librerie.
`httplib`: `[httplib](https://docs.python.org/2/library/httplib.html)` e [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)`
## Tracciamento del contesto per le attività asincrone
Per le librerie `asyncio` integrate o per [creare sottosegmenti per funzioni asincrone](xray-sdk-python-subsegments.md), devi anche configurare X-Ray SDK per Python con un contesto asincrono. Importate la `AsyncContext` classe e passatene un'istanza al registratore X-Ray.
**Nota**
Le librerie di supporto del framework Web, come AIOHTTP, non vengono gestite tramite il modulo `aws_xray_sdk.core.patcher`. Non sono presenti nel catalogo `patcher` delle librerie supportate.
**Example main.py — Patch 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)
```
# Tracciamento delle chiamate AWS SDK con X-Ray SDK per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
[Quando l'applicazione effettua chiamate per Servizi AWS archiviare dati, scrivere in una coda o inviare notifiche, X-Ray SDK for Python tiene traccia delle chiamate a valle in sottosegmenti.](xray-sdk-python-subsegments.md) Le risorse tracciate Servizi AWS e a cui accedi all'interno di tali servizi (ad esempio, un bucket Amazon S3 o una coda Amazon SQS) vengono visualizzate come nodi downstream sulla mappa di traccia nella console X-Ray.
[L'X-Ray SDK per Python strumenta automaticamente tutti i client AWS SDK quando applichi una patch alla libreria. `botocore`](xray-sdk-python-patching.md) Non puoi analizzare singoli client.
Per tutti i servizi, puoi vedere il nome dell'API richiamata nella console X-Ray. Per un sottoinsieme di servizi, l'SDK X-Ray aggiunge informazioni al segmento per fornire una maggiore granularità nella mappa dei servizi.
Ad esempio, quando si effettua una chiamata con un client DynamoDB con strumentazione, l'SDK aggiunge il nome della tabella al segmento per le chiamate destinate a una tabella. Nella console, ogni tabella appare come un nodo separato nella mappa dei servizi, con un nodo DynamoDB generico per le chiamate che non hanno come destinazione una tabella.
**Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento**
```
{
"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",
}
}
```
Quando si accede alle risorse con nome, le chiamate ai seguenti servizi creano ulteriori nodi della mappa del servizio. Le chiamate che non sono hanno come obiettivo risorse specifiche creano un nodo generico per il servizio.
+ **Amazon DynamoDB**: nome della tabella
+ **Amazon Simple Storage Service**: nome del bucket e della chiave
+ **Amazon Simple Queue Service**: nome della coda
# Tracciamento delle chiamate ai servizi Web HTTP downstream utilizzando l'SDK X-Ray per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
Quando l'applicazione effettua chiamate a microservizi o a HTTP pubblico APIs, è possibile utilizzare l'X-Ray SDK for Python per strumentare tali chiamate e aggiungere l'API al service graph come servizio downstream.
Per analizzare i client HTTP, [applica le patch alla libreria](xray-sdk-python-patching.md) che utilizzi per effettuare le chiamate in uscita. Se utilizzi `requests` o il client HTTP integrato in Python, questo è tutto ciò che devi fare. Per `aiohttp`, inoltre, configura il registratore con un [contesto async](xray-sdk-python-patching.md#xray-sdk-python-patching-async).
Se utilizzi le API del client `aiohttp` 3 devi anche configurare la `ClientSession` con un'istanza della configurazione di tracciamento fornita dall'SDK.
**Example [Client API `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()
```
Quando si effettua una chiamata a un'API Web downstream, l'SDK X-Ray per Python registra un sottosegmento che contiene informazioni sulla richiesta e sulla risposta HTTP. X-Ray utilizza il sottosegmento per generare un segmento dedotto per l'API remota.
**Example Sottosegmento per una chiamata HTTP a valle**
```
{
"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 Segmento dedotto per una chiamata HTTP a valle**
```
{
"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
}
```
# Generazione di sottosegmenti personalizzati con X-Ray SDK per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
I sottosegmenti estendono il [segmento](xray-concepts.md#xray-concepts-segments) di una traccia con dettagli sul lavoro svolto per soddisfare una richiesta. Ogni volta che si effettua una chiamata con un client dotato di strumentazione, l'X-Ray SDK registra le informazioni generate in un sottosegmento. È possibile creare sottosegmenti aggiuntivi per raggruppare altri sottosegmenti, misurare le prestazioni di una sezione di codice o registrare annotazioni e metadati.
Per gestire i sottosegmenti, utilizza i metodi `begin_subsegment` e `end_subsegment`.
**Example main.py — Sottosegmento personalizzato**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
Per creare un sottosegmento personalizzato per una funzione sincrona, utilizza il decoratore `@xray_recorder.capture`. Puoi passare un nome per il sottosegmento alla funzione di acquisizione o ometterlo per utilizzare il nome della funzione.
**Example main.py — Sottosegmento della funzione**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
Per una funzione asincrona, utilizza il decoratore `@xray_recorder.capture_async` e passa un contesto async al registratore.
**Example main.py — Sottosegmento di funzione asincrona**
```
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()
```
Quando create un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK for Python genera un ID per esso e registra l'ora di inizio e l'ora di fine.
**Example Sottosegmento con metadati**
```
"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"
}
},
```
# Aggiungi annotazioni e metadati ai segmenti con l'SDK X-Ray per Python
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
È possibile registrare informazioni aggiuntive sulle richieste, sull'ambiente o sull'applicazione con annotazioni e metadati. È possibile aggiungere annotazioni e metadati ai segmenti creati da X-Ray SDK o ai sottosegmenti personalizzati creati dall'utente.
**Le annotazioni sono coppie** chiave-valore con stringhe, numeri o valori booleani. [Le annotazioni sono indicizzate per essere utilizzate con le espressioni di filtro.](xray-console-filters.md) Utilizzale per registrare i dati che desideri utilizzare per raggruppare le tracce nella console oppure per chiamare l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
I **metadati** sono coppie chiave-valore che possono avere valori di qualsiasi tipo, inclusi oggetti ed elenchi, ma non sono indicizzati per essere utilizzati con le espressioni di filtro. Utilizzate i metadati per registrare dati aggiuntivi che desiderate archiviare nella traccia ma che non è necessario utilizzare con la ricerca.
Oltre ad annotazioni e metadati, sui segmenti puoi anche [registrare le stringhe degli ID utente](#xray-sdk-python-segment-userid). IDs Gli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati nella ricerca.
**Topics**
+ [Registrazione di annotazioni con X-Ray SDK per Python](#xray-sdk-python-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK per Python](#xray-sdk-python-segment-metadata)
+ [Utente che registra IDs con X-Ray SDK per Python](#xray-sdk-python-segment-userid)
## Registrazione di annotazioni con X-Ray SDK per Python
Utilizza le annotazioni per memorizzare le informazioni su segmenti o sottosegmenti che desideri siano indicizzate per la ricerca.
**Requisiti per le annotazioni**
+ **Chiavi**: la chiave per un'annotazione a raggi X può contenere fino a 500 caratteri alfanumerici. Non è possibile utilizzare spazi o simboli diversi da un punto o un punto (.)
+ **Valori**: il valore di un'annotazione X-Ray può contenere fino a 1.000 caratteri Unicode.
+ Il numero di **annotazioni**: è possibile utilizzare fino a 50 annotazioni per traccia.
**Per registrare le annotazioni**
1. Ottenere un riferimento al segmento o sottosegmento corrente da `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. Chiamare `put_annotation` con una chiave di tipo Stringa e un valore booleano, numerico o di tipo Stringa.
```
document.put_annotation("mykey", "my value");
```
L'esempio seguente mostra come effettuare una chiamata `putAnnotation` con una chiave String che include un punto e un valore booleano, numerico o stringa.
```
document.putAnnotation("testkey.test", "my value");
```
In alternativa, puoi utilizzare il metodo `put_annotation` sul `xray_recorder`. Questo metodo memorizza le annotazioni sul sottosegmento corrente oppure, se nessun sottosegmento è aperto, sul segmento.
```
xray_recorder.put_annotation("mykey", "my value");
```
L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `put_annotation` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto.
Per trovare tracciamenti con annotazioni contenenti valori specifici, utilizza la parola chiave `annotation[key]` in un'[espressione filtro](xray-console-filters.md).
## Registrazione di metadati con X-Ray SDK per Python
**avvertimento**
Non aggiungere oggetti con riferimenti circolari come valori di metadati in X-Ray SDK per Python. Questi oggetti non possono essere serializzati in JSON e possono creare loop infiniti nell'SDK. Inoltre, evita di aggiungere oggetti grandi e complessi come metadati per evitare problemi di prestazioni.
Utilizza i metadati per memorizzare le informazioni su segmenti o sottosegmenti che non è necessario che siano indicizzate per la ricerca. I valori dei metadati possono essere stringhe, numeri, valori booleani o qualsiasi oggetto che possa essere serializzato in un oggetto o in un vettore JSON.
**Per registrare i metadati**
1. Ottenere un riferimento al segmento o sottosegmento corrente da `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. Chiama `put_metadata` con una chiave di tipo Stringa, un valore booleano, numerico, di tipo Stringa o di tipo oggetto e un namespace di tipo stringa.
```
document.put_metadata("my key", "my value", "my namespace");
```
or
Invocare `put_metadata` semplicemente con una chiave e un valore.
```
document.put_metadata("my key", "my value");
```
In alternativa, puoi utilizzare il metodo `put_metadata` sul `xray_recorder`. Questo metodo memorizza i metadati sul sottosegmento corrente oppure, se nessun sottosegmento è aperto, sul segmento.
```
xray_recorder.put_metadata("my key", "my value");
```
Se non specifichi un namespace, l'SDK utilizza `default`. Se chiami `put_metadata` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto.
## Utente che registra IDs con X-Ray SDK per Python
Registra i segmenti dell'utente IDs su richiesta per identificare l'utente che ha inviato la richiesta.
**Per registrare l'utente IDs**
1. Ottenere un riferimento al segmento corrente da `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Chiamare `setUser` con una stringa che rappresenta l'ID dell'utente che ha inviato la richiesta.
```
document.set_user("U12345");
```
Puoi chiamare `set_user` nel tuo controller per registrare l'ID utente non appena l'applicazione inizia ad elaborare una richiesta.
Per trovare tracciamenti associati ad un ID utente, utilizza la parola chiave `user` in un'[espressione filtro](xray-console-filters.md).
# Analisi di framework Web distribuiti in ambienti serverless
**Nota**
Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry
L' AWS X-Ray SDK per Python supporta la strumentazione di framework web distribuiti in applicazioni serverless. Serverless è l'architettura nativa del cloud che consente di trasferire più responsabilità operative ad AWS, aumentando agilità e innovazione.
L'architettura serverless è un modello di applicazione software che consente di creare ed eseguire applicazioni e servizi senza pensare ai server. Elimina le attività di gestione delle infrastrutture come il provisioning del server o del cluster, l'applicazione di patch, la manutenzione del sistema operativo e il provisioning della capacità. Puoi creare soluzioni serverless per pressoché ogni tipo di applicazione o servizio di back-end e tutte le operazioni necessarie per l'esecuzione e la scalabilità dell'applicazione saranno gestite in automatico.
Questo tutorial mostra come utilizzare automaticamente la strumentazione AWS X-Ray su un framework web, come Flask o Django, distribuito in un ambiente serverless. La strumentazione X-Ray dell'applicazione ti consente di visualizzare tutte le chiamate downstream effettuate, a partire da Amazon API Gateway attraverso la tua AWS Lambda funzione, e le chiamate in uscita effettuate dall'applicazione.
L'X-Ray SDK per Python supporta i seguenti framework applicativi Python:
+ Flask 0.8 o versioni successive
+ Django 1.0 o versioni successive
Questo tutorial sviluppa un esempio di applicazione serverless che viene distribuita su Lambda e richiamata da API Gateway. Questo tutorial utilizza Zappa per distribuire automaticamente l'applicazione su Lambda e configurare l'endpoint API Gateway.
## Prerequisiti
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) — Versione 2.7 o 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)— Verifica che il tuo AWS CLI sia configurato con l'account e Regione AWS in cui distribuirai l'applicazione.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## Fase 1: creazione di un ambiente
In questa fase, crei un ambiente virtuale usando `virtualenv` per ospitare un'applicazione.
1. Utilizzando AWS CLI, create una directory per l'applicazione. Quindi, passare alla nuova directory.
```
mkdir serverless_application
cd serverless_application
```
1. Successivamente, creare un ambiente virtuale all'interno della nuova directory. Utilizzare il comando seguente per attivarlo.
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. Installa X-Ray, Flask, Zappa e la libreria Requests nel tuo ambiente.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. Aggiungere il codice dell'applicazione nella directory `serverless_application`. In questo caso, si utilizza l'esempio [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) di Flask.
Nella directory `serverless_application`, creare un file denominato `my_app.py`. Quindi utilizzare un editor di testo per aggiungere i seguenti comandi. Questa applicazione analizza la libreria delle richieste, applica le patch al middleware dell'applicazione Flask e apre l'endpoint `'/'`.
```
# 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
```
## Fase 2: creazione e distribuzione di un ambiente Zappa
In questo passaggio utilizzerai Zappa per configurare automaticamente un endpoint API Gateway e poi distribuirlo su Lambda.
1. Inizializzare Zappa dalla directory `serverless_application`. Per questo esempio vengono utilizzate le impostazioni predefinite, ma se si desidera personalizzare le preferenze, è possibile visualizzare le istruzioni di configurazione di Zappa.
```
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. Abilita X-Ray. Aprire il file `zappa_settings.json` e verificare che sia simile all'esempio.
```
{
"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. Aggiungere la voce `"xray_tracing": true` al file di configurazione.
```
{
"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. Distribuire l'applicazione. Questo configura automaticamente l'endpoint API Gateway e carica il codice su Lambda.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## Fase 3: Abilitare il tracciamento a raggi X per API Gateway
In questo passaggio interagirai con la console API Gateway per abilitare il tracciamento X-Ray.
1. Accedi Console di gestione AWS e apri la console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
1. Trovare l'API generata di recente. Deve avere un formato analogo a `serverless-exam-dev`.
1. Scegliere **Stages (Fasi)**.
1. Scegliere il nome della fase di distribuzione. Il valore predefinito è `dev`.
1. Nella scheda **Log/Tracciamento**, selezionare la casella **Enable X-Ray Tracing (Abilita tracciamento X-Ray)**.
1. Seleziona **Salva modifiche**.
1. Accedere all'endpoint nel browser. Se è stata utilizzata l'applicazione di esempio `Hello World`, viene visualizzato quanto segue.
```
"Hello, World: https://aws.amazon.com/"
```
## Fase 4: visualizzazione della traccia creata
In questo passaggio interagirai con la console X-Ray per visualizzare la traccia creata dall'applicazione di esempio. Per una spiegazione passo per passo sull'analisi di traccia, consulta [Visualizzazione della mappa del servizio](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
1. [Accedi a Console di gestione AWS e apri la console X-Ray a casahttps://console.aws.amazon.com/xray/.](https://console.aws.amazon.com/xray/home)
1. Visualizza i segmenti generati da API Gateway, dalla funzione Lambda e dal contenitore Lambda.
1. Nel segmento della funzione Lambda, visualizza un sottosegmento denominato. `My First Serverless App` È seguito da un secondo sottosegmento denominato `https://aws.amazon.com`.
1. Durante l'inizializzazione, Lambda potrebbe anche generare un terzo sottosegmento denominato. `initialization`
![\[Visualizzazione del segmento di tracciamento.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/serverless-traceView.png)
![\[Visualizzazione del grafico del servizio.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/serverless-serviceView.png)
## Fase 5: rimozione
Termina sempre le risorse che non usi più per evitare l'accumulo di costi imprevisti. Come dimostra questo tutorial, gli strumenti come Zappa semplificano la ridistribuzione serverless.
Per rimuovere l'applicazione da Lambda, API Gateway e Amazon S3, esegui il comando seguente nella directory del progetto utilizzando il. AWS CLI
```
zappa undeploy dev
```
## Fasi successive
Aggiungi altre funzionalità alla tua applicazione aggiungendo AWS client e strumentandoli con X-Ray. [Scopri di più sulle opzioni di elaborazione serverless su Serverless on. AWS](https://aws.amazon.com/serverless)