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 per X-Ray Node.js **Nota** X-Ray SDK/Daemon Avviso di manutenzione: il 25 febbraio 2026, AWS X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS verranno limitate le versioni di X-Ray SDK e Daemon per risolvere solo i 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, consulta [Migrazione da X-Ray strumentazione a strumentazione](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry È possibile registrare informazioni aggiuntive sulle richieste, sull'ambiente o sull'applicazione con annotazioni e metadati. Puoi aggiungere annotazioni e metadati ai segmenti creati dall' X-Ray SDK o ai sottosegmenti personalizzati che crei tu. **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 [`GetTraceSummaries`](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). Gli ID utente vengono memorizzati in un campo separato su segmenti e sono indicizzati per l'uso nelle ricerche. **Topics** + [Registrazione delle annotazioni con l'SDK per X-Ray Node.js](#xray-sdk-nodejs-segment-annotations) + [Registrazione dei metadati con l'SDK per X-Ray Node.js](#xray-sdk-nodejs-segment-metadata) + [Registrazione degli ID utente con l'SDK per X-Ray Node.js](#xray-sdk-nodejs-segment-userid) ## Registrazione delle annotazioni con l'SDK per X-Ray 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' X-Ray annotazione 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' X-Ray annotazione può contenere fino a 1.000 caratteri Unicode. + 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 `addAnnotation` con una chiave String che include un punto e un valore booleano, numerico o stringa. ``` document.addAnnotation("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 dei metadati con l'SDK per X-Ray 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. ## Registrazione degli ID utente con l'SDK per X-Ray Node.js Memorizza gli ID utente sui segmenti di 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 gli ID degli utenti** 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).