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'X-Ray SDK for Ruby
**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-ruby-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 for Ruby](#xray-sdk-ruby-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK for Ruby](#xray-sdk-ruby-segment-metadata)
+ [Utente che registra IDs con X-Ray SDK for Ruby](#xray-sdk-ruby-segment-userid)
## Registrazione delle annotazioni con X-Ray SDK for Ruby
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 da `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
or
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Chiama `update` con un valore hash.
```
my_annotations = { id: 12345 }
document.annotations.update my_annotations
```
Di seguito è riportato un esempio che mostra come effettuare una chiamata `update` con una chiave di annotazione che contiene un punto.
```
my_annotations = { testkey.test: 12345 }
document.annotations.update my_annotations
```
L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `add_annotations` 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).
## Registrazione di metadati con X-Ray SDK for Ruby
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 oggetto che possa essere serializzato in un oggetto o in un vettore JSON.
**Per registrare i metadati**
1. Ottenere un riferimento al segmento o sottosegmento corrente da `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
or
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Chiama `metadata` con una chiave di tipo Stringa, un valore booleano, numerico, di tipo Stringa o di tipo oggetto e un namespace di tipo stringa.
```
my_metadata = {
my_namespace: {
key: 'value'
}
}
subsegment.metadata my_metadata
```
Se chiami `metadata` 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 for Ruby
Registra i segmenti dell'utente IDs su richiesta per identificare l'utente che ha inviato la richiesta.
**Per registrare l'utente IDs**
1. Ottenere un riferimento al segmento corrente da `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
1. Imposta il campo utente sul segmento a un ID di tipo stringa dell'utente che ha inviato la richiesta.
```
segment.user = 'U12345'
```
Puoi impostare l'utente nei tuoi controller per registrare l'ID utente non appena l'applicazione inizia ad elaborare una richiesta.
Per trovare tracciamenti associati ad un ID utente, utilizza la parola chiave `user` in un'[espressione filtro](xray-console-filters.md).