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