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 Python
**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-python-segment-userid). IDs Gli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati nella ricerca.
**Topics**
+ [Registrazione di annotazioni con X-Ray SDK per Python](#xray-sdk-python-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK per Python](#xray-sdk-python-segment-metadata)
+ [Utente che registra IDs con X-Ray SDK per Python](#xray-sdk-python-segment-userid)
## Registrazione di annotazioni con X-Ray SDK per Python
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
or
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Chiamare `put_annotation` con una chiave di tipo Stringa e un valore booleano, numerico o di tipo Stringa.
```
document.put_annotation("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");
```
In alternativa, puoi utilizzare il metodo `put_annotation` sul `xray_recorder`. Questo metodo memorizza le annotazioni sul sottosegmento corrente oppure, se nessun sottosegmento è aperto, sul segmento.
```
xray_recorder.put_annotation("mykey", "my value");
```
L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `put_annotation` 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 per Python
**avvertimento**
Non aggiungere oggetti con riferimenti circolari come valori di metadati in X-Ray SDK per Python. Questi oggetti non possono essere serializzati in JSON e possono creare loop infiniti nell'SDK. Inoltre, evita di aggiungere oggetti grandi e complessi come metadati per evitare problemi di prestazioni.
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
or
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Chiama `put_metadata` con una chiave di tipo Stringa, un valore booleano, numerico, di tipo Stringa o di tipo oggetto e un namespace di tipo stringa.
```
document.put_metadata("my key", "my value", "my namespace");
```
or
Invocare `put_metadata` semplicemente con una chiave e un valore.
```
document.put_metadata("my key", "my value");
```
In alternativa, puoi utilizzare il metodo `put_metadata` sul `xray_recorder`. Questo metodo memorizza i metadati sul sottosegmento corrente oppure, se nessun sottosegmento è aperto, sul segmento.
```
xray_recorder.put_metadata("my key", "my value");
```
Se non specifichi un namespace, l'SDK utilizza `default`. Se chiami `put_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 per Python
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`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Chiamare `setUser` con una stringa che rappresenta l'ID dell'utente che ha inviato la richiesta.
```
document.set_user("U12345");
```
Puoi chiamare `set_user` nel tuo 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).