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 Node.js **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 configurare X-Ray SDK per Node.js con plug-in per includere informazioni sul servizio su cui viene eseguita l'applicazione, modificare il comportamento di campionamento predefinito o aggiungere regole di campionamento che si applicano alle richieste a percorsi specifici. **Topics** + [Plugin di servizio](#xray-sdk-nodejs-configuration-plugins) + [Regole di campionamento](#xray-sdk-nodejs-configuration-sampling) + [Registrazione dei log](#xray-sdk-nodejs-configuration-logging) + [Indirizzo del demone X-Ray](#xray-sdk-nodejs-configuration-daemon) + [Variabili di ambiente](#xray-sdk-nodejs-configuration-envvars) ## Plugin di servizio Utilizzatelo `plugins` 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. Per utilizzare un plug-in, configura il client X-Ray SDK per Node.js utilizzando il metodo. `config` **Example app.js - Plugin** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]); ``` 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 si utilizzano più plug-in, 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 backup, chiedi a X-Ray SDK per Node.js di caricare le regole di campionamento da un file con. `setSamplingRules` **Example app.js - regole di campionamento da un file** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.middleware.setSamplingRules('sampling-rules.json'); ``` Puoi anche definire le regole nel codice e passarle a `setSamplingRules` come oggetto. **Example app.js - Regole di campionamento da un oggetto** ``` var AWSXRay = require('aws-xray-sdk'); var rules = { "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }, "version": 1 } AWSXRay.middleware.setSamplingRules(rules); ``` Per utilizzare solo le regole locali, chiama `disableCentralizedSampling`. ``` AWSXRay.middleware.disableCentralizedSampling() ``` ## Registrazione dei log Per generare i log sull'output dell'SDK, chiama `AWSXRay.setLogger(logger)`, dove `logger` è un oggetto che fornisce i metodi di log standard (`warn`, `info`, ecc.). Per impostazione predefinita, l'SDK registrerà i messaggi di errore sulla console utilizzando i metodi standard sull'oggetto console. Il livello di registro del logger integrato può essere impostato utilizzando le variabili di `AWS_XRAY_LOG_LEVEL` ambiente `AWS_XRAY_DEBUG_MODE` o. Per un elenco di valori validi a livello di registro, vedete [Variabili di ambiente](#xray-sdk-nodejs-configuration-envvars). Se desideri fornire un formato o una destinazione diversi per i log, puoi fornire all'SDK la tua implementazione dell'interfaccia del logger come mostrato di seguito. È possibile utilizzare qualsiasi oggetto che implementa questa interfaccia. Ciò significa che molte librerie di registrazione, ad esempio Winston, possono essere utilizzate e passate direttamente all'SDK. **Example app.js - logging** ``` var AWSXRay = require('aws-xray-sdk'); // Create your own logger, or instantiate one using a library. var logger = { error: (message, meta) => { /* logging code */ }, warn: (message, meta) => { /* logging code */ }, info: (message, meta) => { /* logging code */ }, debug: (message, meta) => { /* logging code */ } } AWSXRay.setLogger(logger); AWSXRay.config([AWSXRay.plugins.EC2Plugin]); ``` Chiama `setLogger` prima di eseguire altri metodi di configurazione per assicurarti che l'acquisizione dell'output di tali operazioni funzioni. ## Indirizzo del demone X-Ray Se il demone X-Ray è in ascolto su una porta o su un host diverso`127.0.0.1:2000`, è possibile configurare X-Ray SDK per Node.js per inviare i dati di traccia a un indirizzo diverso. ``` AWSXRay.setDaemonAddress('host:port'); ``` È possibile specificare l'host per nome o per indirizzo. IPv4 **Example app.js - Indirizzo daemon** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('daemonhost:8082'); ``` Se hai configurato il daemon per ascoltare su diverse porte per TCP e UDP, puoi specificare entrambe nelle impostazioni dell'indirizzo del daemon. **Example app.js - Indirizzo del daemon su porte separate** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083'); ``` È inoltre possibile impostare l'indirizzo del demone utilizzando la variabile di `AWS_XRAY_DAEMON_ADDRESS` [ambiente.](#xray-sdk-nodejs-configuration-envvars) ## Variabili di ambiente È possibile utilizzare le variabili di ambiente per configurare l'SDK X-Ray per Node.js. L'SDK supporta le seguenti variabili. + `AWS_XRAY_CONTEXT_MISSING`— Imposta per `RUNTIME_ERROR` 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. + `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_DEBUG_MODE`— Imposta su `TRUE` per configurare l'SDK per inviare i log alla console, a livello`debug`. + `AWS_XRAY_LOG_LEVEL `— Imposta un livello di registro per il logger predefinito. I valori validi sono `debug`, `info`, `warn`, `error` e `silent`. Questo valore viene ignorato quando AWS\$1XRAY\$1DEBUG\$1MODE è impostato su. `TRUE` + `AWS_XRAY_TRACING_NAME`— Imposta un nome di servizio che l'SDK utilizza per i segmenti. Sovrascrive il nome del segmento [impostato sul middleware di Express](xray-sdk-nodejs-middleware.md).