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