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 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
L'SDK X-Ray per Node.js è una libreria per le applicazioni Web Express e le funzioni Node.js Lambda 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 effettuate dall'applicazione ai servizi downstream utilizzando i client SDK o HTTP. AWS
**Nota**
L'X-Ray SDK per Node.js è un progetto open source supportato per le versioni 14.x e successive di Node.js. [Puoi seguire il progetto e inviare problemi e richieste pull su GitHub: github. com/aws/aws- xray-sdk-node](https://github.com/aws/aws-xray-sdk-node)
Se utilizzi Express, per tracciare le richieste in entrata inizia [aggiungendo l'SDK come middleware](xray-sdk-nodejs-middleware.md) sul tuo application server. 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 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).
Successivamente, utilizzate l'X-Ray SDK per Node.js per [strumentare il vostro AWS SDK](xray-sdk-nodejs-awssdkclients.md) nei client Node.js. JavaScript Ogni volta che effettui una chiamata a un downstream Servizio AWS o a una risorsa con un client dotato di strumenti, 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.
L'X-Ray SDK per Node.js fornisce anche la strumentazione per le chiamate downstream a query HTTP Web e SQL. APIs Per memorizzare le informazioni sulle chiamate HTTP in uscita [includi il client HTTP nel metodo di tracciamento dell'SDK](xray-sdk-nodejs-httpclients.md). Nel caso di client SQL, [utilizza il metodo di tracciamento per il tuo tipo di database](xray-sdk-nodejs-sqlclients.md).
Pr determinare quali richieste tracciare, il middleware applica le regole di campionamento alle richieste in entrata. È possibile [configurare X-Ray SDK per Node.js per](xray-sdk-nodejs-configuration.md) regolare il comportamento di campionamento o per registrare informazioni sulle risorse di AWS calcolo su cui viene eseguita l'applicazione.
Registra ulteriori informazioni sulle richieste e sull'attività svolta dalla tua applicazione in [annotazioni e metadati](xray-sdk-nodejs-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 matrici, 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-nodejs-subsegments.md). Puoi creare un sottosegmento personalizzato per un'intera funzione o qualsiasi porzione di codice, e memorizzare metadati e annotazioni sul sottosegmento invece di scrivere tutto all'interno del segmento padre.
Per la documentazione di riferimento sulle classi e i metodi dell'SDK, consulta l'[AWS X-Ray SDK for Node.js](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference) API Reference.
## Requisiti
L'X-Ray SDK per Node.js richiede Node.js e le seguenti librerie:
+ `atomic-batcher`— 1.0.2
+ `cls-hooked`— 4.2.2
+ `pkginfo`— 0.4.0
+ `semver`— 5.3.0
L'SDK preleva queste librerie durante la sua installazione con NPM.
Per tracciare i client AWS SDK, X-Ray SDK per Node.js richiede una versione minima AWS dell' JavaScript SDK per Node.js.
+ `aws-sdk`— 2.7.15
## Gestione delle dipendenze
L'X-Ray SDK per Node.js è disponibile presso NPM.
+ **Package** — [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
Per lo sviluppo in locale, installa l'SDK nella cartella del tuo progetto con npm.
```
~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
├─┬ aws-xray-sdk-core@3.3.3
│ ├── @aws-sdk/service-error-classification@3.15.0
│ ├── @aws-sdk/types@3.15.0
│ ├─┬ @types/cls-hooked@4.3.3
│ │ └── @types/node@15.3.0
│ ├── atomic-batcher@1.0.2
│ ├─┬ cls-hooked@4.2.2
│ │ ├─┬ async-hook-jl@1.7.6
│ │ │ └── stack-chain@1.3.7
│ │ └─┬ emitter-listener@1.1.2
│ │ └── shimmer@1.2.1
│ └── semver@5.7.1
├── aws-xray-sdk-express@3.3.3
├── aws-xray-sdk-mysql@3.3.3
└── aws-xray-sdk-postgres@3.3.3
```
Utilizza l'opzione `--save` per salvare l'SDK come dipendenza nel file `package.json` della tua applicazione.
```
~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3
```
Se l'applicazione presenta dipendenze le cui versioni sono in conflitto con le dipendenze dell'SDK X-Ray, verranno installate entrambe le versioni per garantire la compatibilità. Per maggiori dettagli, consulta la documentazione [ufficiale di NPM per la risoluzione](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html) delle dipendenze.
## Esempi di Node.js
Utilizza l' AWS X-Ray SDK per Node.js per avere una end-to-end visione delle richieste mentre viaggiano attraverso le tue applicazioni Node.js.
+ [Applicazione di esempio Node.js](https://github.com/aws-samples/aws-xray-sdk-node-sample) attiva. GitHub
# 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).
# Tracciamento delle richieste in arrivo con X-Ray SDK 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
Puoi utilizzare l'SDK X-Ray per Node.js per tracciare le richieste HTTP in entrata che le tue applicazioni Express e Restify servono su un'istanza EC2 in Amazon EC2 o Amazon ECS. AWS Elastic Beanstalk
L'X-Ray SDK per Node.js fornisce middleware per applicazioni che utilizzano i framework Express e Restify. Quando aggiungete il middleware X-Ray all'applicazione, l'SDK X-Ray per Node.js 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.
**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).
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 gestore dei messaggi 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**
+ [Tracciamento delle richieste in entrata con Express](#xray-sdk-nodejs-middleware-express)
+ [Tracciamento delle richieste in entrata con Restify](#xray-sdk-nodejs-middleware-restify)
+ [Configurazione di una strategia di denominazione dei segmenti](#xray-sdk-nodejs-middleware-naming)
## Tracciamento delle richieste in entrata con Express
Per usare il middleware Express, inizializzare il client SDK e utilizzare il middleware restituito dalla funzione `express.openSegment` prima di definire gli instradamenti.
**Example app.js - Express**
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
Dopo aver definito i percorsi, utilizzate l'output di `express.closeSegment` come mostrato per gestire eventuali errori restituiti da X-Ray SDK per Node.js.
## Tracciamento delle richieste in entrata con Restify
Per usare il middleware Restify, inizializzare il client SDK client e eseguire `enable`. Passare ad esso il server Restify e il nome del segmento.
**Example app.js - Restify**
```
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
server.get('/', function (req, res) {
res.render('index');
});
```
## 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, risorse esterne APIs e AWS risorse 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 inizializzi il middleware, come illustrato nelle sezioni precedenti.
**Nota**
[È possibile sovrascrivere il nome di servizio predefinito definito nel codice con la `AWS_XRAY_TRACING_NAME` variabile di ambiente.](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars)
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 i segmenti in modo dinamico, utilizza `AWSXRay.middleware.enableDynamicNaming`.
**Example app.js - Nomi dei segmenti dinamici**
Se il nome host nella richiesta corrispondente al modello `*.example.com`, utilizza il nome dell'host. In caso contrario, utilizzare `MyApp`.
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
# Tracciamento delle chiamate AWS SDK con X-Ray SDK 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
[Quando l'applicazione effettua chiamate per Servizi AWS archiviare dati, scrivere in una coda o inviare notifiche, X-Ray SDK per Node.js tiene traccia delle chiamate a valle in sottosegmenti.](xray-sdk-nodejs-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.
[https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html) Ogni versione AWS SDK offre metodi diversi per la strumentazione dei client SDK. AWS
**Nota**
Attualmente, l' AWS X-Ray SDK per Node.js restituisce meno informazioni sui segmenti durante la strumentazione dei client AWS SDK per JavaScript V3, rispetto alla strumentazione dei client V2. Ad esempio, i sottosegmenti che rappresentano le chiamate a DynamoDB non restituiranno il nome della tabella. Se hai bisogno di queste informazioni sui segmenti nelle tue tracce, prendi in considerazione l'utilizzo della versione V2. AWS SDK per JavaScript
------
#### [ AWS SDK per JavaScript V2 ]
Puoi utilizzare tutti i client AWS SDK V2 inserendo l'istruzione `aws-sdk` require in una chiamata a. `AWSXRay.captureAWS`
**Example app.js - Strumentazione SDK AWS**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
Per strumentare i singoli client, inserisci il tuo client AWS SDK in una chiamata a. `AWSXRay.captureAWSClient` Ad esempio, per analizzare un client `AmazonDynamoDB`:
**Example app.js - Strumentazione client DynamoDB**
```
const AWSXRay = require('aws-xray-sdk');
...
const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```
**avvertimento**
Non utilizzare `captureAWS` e `captureAWSClient` insieme. Ciò causerà sottosegmenti duplicati.
Se desideri utilizzarla [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)con i [ECMAScriptmoduli](https://nodejs.org/api/esm.html) (ESM) per caricare il JavaScript codice, usa l'esempio seguente per importare le librerie:
**Example app.js - strumentazione AWS SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Per strumentare tutti i AWS client con ESM, usa il seguente codice:
**Example app.js - Strumentazione AWS SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```
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
------
#### [ AWS SDK per JavaScript V3 ]
La AWS SDK per JavaScript V3 è modulare, quindi il codice carica solo i moduli necessari. Per questo motivo, non è possibile strumentare tutti i client AWS SDK poiché la V3 non supporta il metodo. `captureAWS`
Se desideri utilizzare TypeScript ECMAScript Modules (ESM) per caricare il JavaScript codice, puoi utilizzare il seguente esempio per importare le librerie:
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Strumenta ogni client AWS SDK utilizzando il `AWSXRay.captureAWSv3Client` metodo. Ad esempio, per analizzare un client `AmazonDynamoDB`:
**Example app.js - Strumentazione client DynamoDB che utilizza SDK per Javascript V3**
```
const AWSXRay = require('aws-xray-sdk');
const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));
```
Quando si utilizza AWS SDK per JavaScript V3, i metadati come il nome della tabella, il nome del bucket e della chiave o il nome della coda non vengono attualmente restituiti, pertanto la mappa di traccia non conterrà nodi discreti per ogni risorsa denominata, come accade quando si strumentano i client SDK utilizzando la V2. AWS AWS SDK per JavaScript
**Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento, quando si utilizza la V3 AWS SDK per JavaScript**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
------
# Tracciamento delle chiamate ai servizi Web HTTP downstream utilizzando l'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
Quando l'applicazione effettua chiamate a microservizi o HTTP pubblico APIs, è possibile utilizzare il client X-Ray SDK for Node.js per strumentare tali chiamate e aggiungere l'API al grafico dei servizi come servizio downstream.
Passa il tuo `http` `https` client al `captureHTTPs` metodo X-Ray SDK for Node.js per tracciare le chiamate in uscita.
**Nota**
Le chiamate che utilizzano librerie di richieste HTTP di terza parte, ad esempio Axios o Superagent, sono supportate tramite l'[API `captureHTTPsGlobal()`](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) e verranno comunque tracciate quando utilizzano il modulo `http` nativo.
**Example app.js - Client HTTP**
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
Per abilitare il tracciamento su tutti i client HTTP, chiama `captureHTTPsGlobal` prima di caricare `http`.
**Example app.js - Client HTTP (Globale)**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
Quando si effettua una chiamata a un'API Web downstream, l'SDK X-Ray per Node.js 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
}
```
# Tracciamento delle query SQL con X-Ray SDK 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
Strumenta le query del database SQL inserendo il client SQL nel metodo client X-Ray SDK for Node.js corrispondente.
+ **PostgreSQL** – `AWSXRay.capturePostgres()`
```
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();
```
+ **MySQL** – `AWSXRay.captureMySQL()`
```
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);
```
Quando utilizzi un client analizzato per eseguire query SQL, X-Ray SDK per Node.js memorizza le informazioni sulla connessione e sulla query in un sottosegmento
## Includere dati aggiuntivi nei sottosegmenti SQL
È possibile aggiungere informazioni aggiuntive ai sottosegmenti generati per le query SQL, purché siano mappate su un campo SQL consentito. Ad esempio, per registrare la stringa di query SQL sanificata in un sottosegmento, è possibile aggiungerla direttamente all'oggetto SQL del sottosegmento.
**Example Assegna SQL al sottosegmento**
```
const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);
// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;
if (subs & & subs.length > 0) {
var sqlSub = subs[subs.length - 1];
sqlSub.sql.sanitized_query = queryString;
}
```
*Per un elenco completo dei campi SQL consentiti, consulta [SQL Queries](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql) nella Developer Guide.AWS X-Ray *
# Generazione di sottosegmenti personalizzati con X-Ray SDK per Node.js
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.
## Sottosegmenti Express personalizzati
**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 creare un sottosegmento personalizzato per una funzione che effettua chiamate a servizi a valle, utilizza la funzione `captureAsyncFunc`.
**Example app.js - Sottosegmenti personalizzati Express**
```
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) {
sendRequest(host, function() {
console.log('rendering!');
res.render('index');
subsegment.close();
});
});
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) {
var options = {
host: host,
path: '/',
};
var callback = function(response) {
var str = '';
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
```
In questo esempio, l'applicazione crea un sottosegmento personalizzato denominato `send` per le chiamate alla funzione `sendRequest`. `captureAsyncFunc` trasferisce un sottosegmento che è necessario chiudere all'interno della funzione di callback quando le chiamate asincrone invocate vengono completate.
Per le funzioni sincrone, puoi utilizzare la funzione `captureFunc` che chiude il sottosegmento automaticamente non appena il blocco della funzione si conclude.
Quando si crea un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK per Node.js genera un ID per tale sottosegmento 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"
}
},
```
## Sottosegmenti Lambda personalizzati
L'SDK è configurato per creare automaticamente un segmento di facciata segnaposto quando rileva che è in esecuzione in Lambda. Per creare un sottosegmento di base, che creerà un singolo `AWS::Lambda::Function` nodo sulla mappa di tracciamento a raggi X, richiamate e riutilizzate il segmento di facciata. Se crei manualmente un nuovo segmento con un nuovo ID (mentre condividi l'ID di tracciamento, l'ID padre e la decisione di campionamento), sarai in grado di inviare un nuovo segmento.
**Example app.js - sottosegmenti personalizzati manualmente**
```
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically
```
# Aggiungi annotazioni e metadati ai segmenti con l'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 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-nodejs-segment-userid). IDs Gli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati nella ricerca.
**Topics**
+ [Registrazione delle annotazioni con X-Ray SDK per Node.js](#xray-sdk-nodejs-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK per Node.js](#xray-sdk-nodejs-segment-metadata)
+ [Utente che registra IDs con X-Ray SDK per Node.js](#xray-sdk-nodejs-segment-userid)
## Registrazione delle annotazioni con X-Ray SDK per Node.js
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.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chiamare `addAnnotation` con una chiave di tipo Stringa e un valore booleano, numerico o di tipo Stringa.
```
document.addAnnotation("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");
```
L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `addAnnotation` 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).
**Example app.js - Annotazioni**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var item = {
'email': {'S': req.body.email},
'name': {'S': req.body.name},
'preview': {'S': req.body.previewAccess},
'theme': {'S': req.body.theme}
};
var seg = AWSXRay.getSegment();
seg.addAnnotation('theme', req.body.theme);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
## Registrazione di metadati con X-Ray SDK per Node.js
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 altro oggetto che può essere serializzato in un oggetto o in un vettore JSON.
**Per registrare i metadati**
1. Ottenere un riferimento al segmento o sottosegmento corrente.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chiamare `addMetadata` con una chiave di tipo Stringa, un valore booleano, numerico, di tipo Stringa o di tipo oggetto e un namespace di tipo stringa.
```
document.addMetadata("my key", "my value", "my namespace");
```
or
Invocare `addMetadata` semplicemente con una chiave e un valore.
```
document.addMetadata("my key", "my value");
```
Se non specifichi un namespace, l'SDK utilizza `default`. Se chiami `addMetadata` 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 Node.js
Registra i segmenti dell'utente IDs su richiesta per identificare l'utente che ha inviato la richiesta. Questa operazione non è compatibile con AWS Lambda le funzioni perché i segmenti negli ambienti Lambda sono immutabili. La chiamata `setUser` può essere applicata solo ai segmenti, non ai sottosegmenti.
**Per registrare l'utente IDs**
1. Ottenere un riferimento al segmento o sottosegmento corrente.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chiamare `setUser()` con una stringa che rappresenta l'ID dell'utente che ha inviato la richiesta.
```
var user = 'john123';
AWSXRay.getSegment().setUser(user);
```
È possibile chiamare `setUser` per registrare l'ID utente non appena l'applicazione Express inizia l'elaborazione di una richiesta. Se usi il segmento per impostare l'ID utente, puoi concatenare le chiamate in un'unica riga.
**Example app.js - ID utente**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var userId = uuidv4();
var item = {
'userId': {'S': userId},
'email': {'S': req.body.email},
'name': {'S': req.body.name}
};
var seg = AWSXRay.getSegment().setUser(userId);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
Per trovare tracciamenti associati ad un ID utente, utilizza la parola chiave `user` in un'[espressione filtro](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html).