Aggiungi annotazioni e metadati ai segmenti con X-Ray SDK for .NET

È possibile utilizzare annotazioni e metadati per registrare informazioni aggiuntive sulle richieste, sull'ambiente o sull'applicazione. È 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. Utilizzale per registrare i dati che desideri utilizzare per raggruppare le tracce nella console oppure per chiamare l'API GetTraceSummaries.

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.

Registrazione delle annotazioni con X-Ray SDK for .NET

Utilizza le annotazioni per memorizzare le informazioni su segmenti o sottosegmenti che desideri siano indicizzate per la ricerca.

Quanto segue è necessario per tutte le annotazioni in X-Ray:

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 dal simbolo di sottolineatura (_).

• 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 annotazioni al di fuori di una funzione AWS Lambda

1. Procurarsi un'istanza di AWSXRayRecorder.

   using Amazon.XRay.Recorder.Core;
   ...
   AWSXRayRecorder recorder = AWSXRayRecorder.Instance;

2. Chiamare addAnnotation con una chiave di tipo Stringa e un valore booleano, Int32, Int64, Double o Stringa.

   recorder.AddAnnotation("mykey", "my value");

Per registrare annotazioni all'interno di una funzione AWS Lambda

Sia i segmenti che i sottosegmenti all'interno di una funzione Lambda sono gestiti dall'ambiente di runtime Lambda. Se desideri aggiungere un'annotazione a un segmento o sottosegmento all'interno di una funzione Lambda, devi fare quanto segue:

1. Crea il segmento o il sottosegmento all'interno della funzione Lambda.

2. Aggiungi l'annotazione al segmento o al sottosegmento.

3. Termina il segmento o il sottosegmento.

Il seguente esempio di codice mostra come aggiungere un'annotazione a un sottosegmento all'interno di una funzione Lambda:

#Create the subsegment
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
#Add an annotation
AWSXRayRecorder.Instance.AddAnnotation("My", "Annotation");
try
{
  YourProcess(); #Your function
}
catch (Exception e)
{
  AWSXRayRecorder.Instance.AddException(e);
}
finally #End the subsegment
{
  AWSXRayRecorder.Instance.EndSubsegment();
}

L'X-Ray SDK registra le annotazioni come coppie chiave-valore in un annotations oggetto nel documento del segmento. La chiamata all'addAnnotationoperazione due volte con la stessa chiave sovrascrive un valore registrato in precedenza sullo stesso segmento o sottosegmento.

Per trovare tracce con annotazioni con valori specifici, utilizzate la annotations.key parola chiave in un'espressione di filtro. Per ulteriori informazioni, consulta Usa le espressioni di filtro.

Registrazione di metadati con X-Ray SDK for .NET

Usa i metadati per registrare informazioni su segmenti o sottosegmenti che non devi indicizzare per utilizzarli all'interno di una 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 array JSON.

Per registrare i metadati

1. Ottieni un'istanza diAWSXRayRecorder, come mostrato nel seguente esempio di codice:

   using Amazon.XRay.Recorder.Core;
   ...
   AWSXRayRecorder recorder = AWSXRayRecorder.Instance;

2. Chiama AddMetadata con uno spazio dei nomi di stringa, una chiave di stringa e un valore di oggetto, come illustrato nel seguente esempio di codice:

   recorder.AddMetadata("my namespace", "my key", "my value");

   È inoltre possibile chiamare l'AddMetadataoperazione utilizzando solo una coppia chiave/valore, come illustrato nel seguente esempio di codice:

   recorder.AddMetadata("my key", "my value");

Se non si specifica un valore per lo spazio dei nomi, viene utilizzato l'SDK X-Ray. default La chiamata all'AddMetadataoperazione due volte con la stessa chiave sovrascrive un valore registrato in precedenza sullo stesso segmento o sottosegmento.