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à.
# AWS X-Ray SDK per.NET
**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
X-Ray SDK for .NET è una libreria per la strumentazione delle applicazioni Web C\$1 .NET, delle applicazioni Web.NET Core e delle funzioni.NET Core. AWS Lambda Fornisce classi e metodi per generare e inviare dati di traccia al demone [X-Ray](xray-daemon.md). Ciò include informazioni sulle richieste in entrata fornite dall'applicazione e sulle chiamate effettuate dall'applicazione ai database downstream Servizi AWS, HTTP Web APIs e SQL.
**Nota**
X-Ray SDK for .NET è un progetto open source. [Puoi seguire il progetto e inviare problemi e richieste pull su GitHub: github. com/aws/aws- xray-sdk-dotnet](https://github.com/aws/aws-xray-sdk-dotnet)
In caso di applicazioni web, per tracciare le richieste in entrata inizia [aggiungendo un gestore di messaggi nella configurazione web](xray-sdk-dotnet-messagehandler.md). Il gestore dei messaggi crea un [segmento](xray-concepts.md#xray-concepts-segments) per ogni richiesta tracciata e completa il segmento quando viene inviata la risposta. Fino a che il segmento è aperto puoi usare i metodi del client dell'SDK per aggiungere informazioni al segmento e creare sottosegmenti per tracciare le chiamate a valle. L'SDK, inoltre, registra automaticamente le eccezioni sollevate dall'applicazione per il tempo durante il quale il segmento è aperto.
Per le funzioni Lambda richiamate da un'applicazione o un servizio strumentato, Lambda legge l'intestazione di [tracciamento e traccia automaticamente le richieste campionate](xray-concepts.md#xray-concepts-tracingheader). Per altre funzioni, puoi [configurare Lambda](xray-services-lambda.md) per campionare e tracciare le richieste in arrivo. In entrambi i casi, Lambda crea il segmento e lo fornisce all'X-Ray SDK.
**Nota**
Su Lambda, l'SDK X-Ray è opzionale. Se non lo usi nella tua funzione, la mappa dei servizi includerà comunque un nodo per il servizio Lambda e uno per ogni funzione Lambda. Aggiungendo l'SDK, puoi utilizzare il codice della funzione per aggiungere sottosegmenti al segmento di funzione registrato da Lambda. Per ulteriori informazioni, consulta [AWS Lambda e AWS X-Ray](xray-services-lambda.md).
[Successivamente, usa l'X-Ray SDK for .NET per strumentare i tuoi clienti. AWS SDK per .NET](xray-sdk-dotnet-sdkclients.md) Ogni volta che effettui una chiamata a un downstream Servizio AWS o a una risorsa con un client dotato di strumentazione, l'SDK registra le informazioni sulla chiamata in un sottosegmento. AWS i servizi e le risorse a cui accedi all'interno dei servizi vengono visualizzati come nodi a valle sulla mappa di traccia per aiutarti a identificare errori e problemi di limitazione sulle singole connessioni.
[[L'X-Ray SDK for .NET fornisce anche la strumentazione per le chiamate downstream ai database HTTP Web e SQL. APIs](xray-sdk-dotnet-sqlqueries.md)](xray-sdk-dotnet-httpclients.md) Il metodo di estensione `GetResponseTraced` di `System.Net.HttpWebRequest` traccia le chiamate HTTP in uscita. È possibile utilizzare la versione X-Ray SDK for .NET di per `SqlCommand` strumentare le query SQL.
Dopo aver iniziato a utilizzare l'SDK, personalizzane il comportamento [configurando il registratore e il](xray-sdk-dotnet-configuration.md) gestore dei messaggi. Puoi aggiungere dei plugin per memorizzare i dati sulle risorse di elaborazione sulle quali è eseguita la tua applicazione, personalizzare il comportamento di campionamento definendo regole di campionatura e impostare il livello di log per visualizzare più o meno informazioni generate dall'SDK nei log dell'applicazione.
Registra ulteriori informazioni sulle richieste e sull'attività svolta dalla tua applicazione in [annotazioni e metadati](xray-sdk-dotnet-segment.md). Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con [espressioni filtro](xray-console-filters.md), in modo da poter cercare tracce che contengono dati specifici. Le immissioni di metadati sono meno restrittive e possono registrare interi oggetti e matrici, ovvero tutto ciò che può essere serializzato in JSON.
**Annotazioni e metadata**
Le annotazioni e i metadati sono testo arbitrario che aggiungi ai segmenti con X-Ray SDK. Le annotazioni vengono indicizzate per essere utilizzate con le espressioni di filtro. I metadati non sono indicizzati, ma possono essere visualizzati nel segmento non elaborato con la console X-Ray o l'API. Chiunque conceda l'accesso in lettura a X-Ray può visualizzare questi dati.
Quando disponi di una notevole quantità di client analizzati nel tuo codice, un singolo segmento per la richiesta può contenere un numero elevato di sottosegmenti, uno per ciascuna delle chiamate effettuate con un client analizzato. Puoi organizzare e raggruppare i sottosegmenti inglobando le chiamate del client [sottosegmenti personalizzati](xray-sdk-dotnet-subsegments.md). Puoi creare un sottosegmento personalizzato per un'intera funzione o qualsiasi porzione di codice, e memorizzare metadati e annotazioni sul sottosegmento invece di scrivere tutto all'interno del segmento padre.
Per la documentazione di riferimento sulle classi e sui metodi dell'SDK, consulta quanto indicato qui di seguito:
+ [AWS X-Ray Riferimento all'API SDK for .NET](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray Guida di riferimento all'API SDK for .NET Core](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)
Lo stesso pacchetto supporta sia .NET che .NET Core, ma le classi utilizzate sono diverse. Gli esempi in questo capitolo sono collegati alla guida di riferimento per le API .NET a meno che la classe non sia specifica per .NET Core.
## Requisiti
X-Ray SDK for .NET richiede .NET Framework 4.5 o versione successiva e. AWS SDK per .NET
In caso di applicazioni e funzioni .NET Core, l'SDK richiede .NET Core 2.0 o versioni successive.
## Aggiungere l'X-Ray SDK for .NET all'applicazione
NuGet Usalo per aggiungere l'X-Ray SDK for .NET alla tua applicazione.
**Per installare X-Ray SDK per .NET con il gestore di NuGet pacchetti in Visual Studio**
1. Scegli **Tools**, **NuGet Package Manager**, **Manage NuGet Packages for Solution**.
1. Cerca **AWSXRayRecorder.**
1. Scegliere il pacchetto e quindi scegliere **Install (Installa)**.
## Gestione delle dipendenze
[L'X-Ray SDK for .NET è disponibile presso Nuget.](https://www.nuget.org/packages/AWSXRayRecorder/) Installa l'SDK utilizzando il gestore di pacchetti:
```
Install-Package AWSXRayRecorder -Version 2.10.1
```
Il pacchetto `AWSXRayRecorder v2.10.1` nuget ha le seguenti dipendenze:
### NET Framework 4.5
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
|
|-- AWSXRayRecorder.Handlers.AspNet (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- EntityFramework (>= 6.2.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
### NET Framework 2.0
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
| |-- Microsoft.AspNetCore.Http (>= 2.0.0)
| |-- Microsoft.Extensions.Configuration (>= 2.0.0)
| |-- System.Net.Http (>= 4.3.4)
|
|-- AWSXRayRecorder.Handlers.AspNetCore (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.AspNetCore.Http.Extensions (>= 2.0.0)
| |-- Microsoft.AspNetCore.Mvc.Abstractions (>= 2.0.0)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.EntityFrameworkCore.Relational (>= 3.1.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- System.Data.SqlClient (>= 4.4.0)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
[Per ulteriori dettagli sulla gestione delle dipendenze, consulta la documentazione di Microsoft sulla dipendenza da [Nuget e sulla risoluzione delle dipendenze da Nuget](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies).](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution)
# Configurazione dell'X-Ray SDK per.NET
**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 configurare X-Ray SDK for .NET con plug-in per includere informazioni sul servizio su cui viene eseguita l'applicazione, modificare il comportamento di campionamento predefinito o aggiungere regole di campionamento che si applicano alle richieste a percorsi specifici.
Per le applicazioni web .NET, aggiungi le chiavi alla sezione `appSettings` del file `Web.config`.
**Example Web.config**
```
```
Per .NET Core, crea un file denominato `appsettings.json` con una chiave di primo livello denominata `XRay`.
**Example .NET appsettings.json**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin",
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
Quindi, nel codice dell'applicazione, create un oggetto di configurazione e utilizzatelo per inizializzare il registratore X-Ray. Esegui questa operazione prima di [inizializzare il registratore](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs).
**Example .NET Core Program.cs — Configurazione del registratore**
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```
Se stai analizzando un'applicazione web .NET Core, puoi anche inoltrare l'oggetto di configurazione al metodo `UseXRay` quando [configuri il gestore dei messaggi](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs). Per le funzioni Lambda, usa il `InitializeInstance` metodo illustrato sopra.
Per ulteriori informazioni sull'API di configurazione.NET Core, consulta [Configurare un'app ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration) su docs.microsoft.com.
**Topics**
+ [Plugin](#xray-sdk-dotnet-configuration-plugins)
+ [Regole di campionamento](#xray-sdk-dotnet-configuration-sampling)
+ [Logging (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [Logging (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [Variabili di ambiente](#xray-sdk-dotnet-configuration-envvars)
## Plugin
Utilizza i plug-in per aggiungere i dati sul servizio che ospita l'applicazione.
**Plugin**
+ Amazon EC2 : `EC2Plugin` aggiunge l'ID dell'istanza, la zona di disponibilità e il gruppo di CloudWatch log.
+ Elastic `ElasticBeanstalkPlugin` Beanstalk: aggiunge il nome dell'ambiente, l'etichetta della versione e l'ID di distribuzione.
+ Amazon ECS: `ECSPlugin` aggiunge l'ID del contenitore.
Per utilizzare un plug-in, configura il client X-Ray SDK for .NET aggiungendo l'impostazione. `AWSXRayPlugins` Se si applicano più plugin all'applicazione, specificarli tutti nella stessa impostazione, separati da virgole.
**Example Web.config - Plugin**
```
```
**Example .NET Core appsettings.json — Plugin**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
}
}
```
## Regole di campionamento
L'SDK utilizza le regole di campionamento definite nella console X-Ray per determinare quali richieste registrare. La regola predefinita tiene traccia della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive su tutti i servizi che inviano tracce a X-Ray. [Crea regole aggiuntive nella console X-Ray](xray-console-sampling.md) per personalizzare la quantità di dati registrati per ciascuna delle tue applicazioni.
L'SDK applica le regole personalizzate nell'ordine in cui sono definite. Se una richiesta corrisponde a più regole personalizzate, l'SDK applica solo la prima regola.
**Nota**
Se l'SDK non riesce a contattare X-Ray per ottenere le regole di campionamento, torna a una regola locale predefinita della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive per host. Ciò può verificarsi se l'host non dispone dell'autorizzazione per chiamare sampling APIs o non riesce a connettersi al demone X-Ray, che funge da proxy TCP per le chiamate API effettuate dall'SDK.
Puoi anche configurare l'SDK per caricare le regole di campionamento da un documento JSON. L'SDK può utilizzare le regole locali come backup per i casi in cui il campionamento a raggi X non è disponibile o utilizzare esclusivamente regole locali.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
Questo esempio definisce una regola personalizzata e una regola predefinita. La regola personalizzata applica una frequenza di campionamento del cinque percento senza alcun numero minimo di richieste da tracciare per i percorsi. `/api/move/` La regola predefinita tiene traccia della prima richiesta ogni secondo e del 10% delle richieste aggiuntive.
Lo svantaggio della definizione locale delle regole è che l'obiettivo fisso viene applicato da ciascuna istanza del registratore in modo indipendente, anziché essere gestito dal servizio X-Ray. Man mano che si installano più host, la tariffa fissa si moltiplica, rendendo più difficile il controllo della quantità di dati registrati.
Sì AWS Lambda, non è possibile modificare la frequenza di campionamento. Se la funzione viene chiamata da un servizio strumentato, le chiamate che hanno generato richieste campionate da quel servizio verranno registrate da Lambda. Se il tracciamento attivo è abilitato e non è presente alcuna intestazione di tracciamento, Lambda prende la decisione di campionamento.
Per configurare le regole di backup, chiedi a X-Ray SDK for .NET di caricare le regole di campionamento da un file con l'impostazione. `SamplingRuleManifest`
**Example .NET Web.config - regole di campionamento**
```
```
**Example .NET Core appsettings.json — Regole di campionamento**
```
{
"XRay": {
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
Per utilizzare solo regole locali, crea un registratore con una `LocalizedSamplingStrategy`. Se si dispone di regole di backup configurate, rimuovere tale configurazione.
**Example .NET global.asax: regole di campionamento locali**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
```
**Example .NET Core Program.cs: regole di campionamento locali**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);
```
## Logging (.NET)
L'X-Ray SDK for .NET utilizza lo stesso meccanismo di registrazione di. [AWS SDK per .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) Se hai già configurato l'applicazione per registrare l' AWS SDK per .NET output, la stessa configurazione si applica all'output di X-Ray SDK for .NET.
Per configurare il log, aggiungi una sezione di configurazione denominata `aws` al tuo file `App.config` o al tuo file `Web.config`.
**Example Web.config - Generazione dei log**
```
...
```
Per ulteriori informazioni, consulta [Configurazione dell'applicazione AWS SDK per .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) nella *Guida per gli sviluppatori di AWS SDK per .NET *.
## Logging (.NET Core)
X-Ray SDK for .NET utilizza le stesse opzioni di registrazione di. [AWS SDK per .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging) Per configurare la registrazione per le applicazioni.NET Core, passa l'opzione di registrazione al metodo. `AWSXRayRecorder.RegisterLogger`
Ad esempio, per utilizzare log4net, è necessario creare un file di configurazione che definisca il logger, formato di output e la posizione del file.
**Example .NET Core log4net.config**
```
```
Quindi creare il logger e applicare la configurazione al codice del programma.
**Example .NET Core Program.cs — Registrazione**
```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
class Program
{
private static ILog log;
static Program()
{
var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
log = LogManager.GetLogger(typeof(Program));
AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
}
static void Main(string[] args)
{
...
}
}
```
[Per ulteriori informazioni sulla configurazione di log4net, vedere Configurazione su logging.apache.org.](https://logging.apache.org/log4net/release/manual/configuration.html)
## Variabili di ambiente
È possibile utilizzare le variabili di ambiente per configurare l'X-Ray SDK for .NET. L'SDK supporta le seguenti variabili.
+ `AWS_XRAY_TRACING_NAME`— Imposta un nome di servizio che l'SDK utilizza per i segmenti. Sostituisce il nome del servizio impostato sulla [strategia di denominazione dei segmenti](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming) del filtro servlet.
+ `AWS_XRAY_DAEMON_ADDRESS`— Imposta l'host e la porta del demone X-Ray. Per impostazione predefinita, l'SDK utilizza `127.0.0.1:2000` sia i dati di traccia (UDP) che il campionamento (TCP). Utilizzate questa variabile se avete configurato il demone per l'[ascolto su una porta diversa](xray-daemon-configuration.md) o se è in esecuzione su un host diverso.
**Formato**
+ **Stessa porta** — `address:port`
+ **Porte diverse**: `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`— Imposta `RUNTIME_ERROR` per generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.
**Valori validi**
+ `RUNTIME_ERROR`— Genera un'eccezione di runtime.
+ `LOG_ERROR`— Registra un errore e continua (impostazione predefinita).
+ `IGNORE_ERROR`— Ignora l'errore e continua.
Gli errori relativi a segmenti o sottosegmenti mancanti possono verificarsi quando si tenta di utilizzare un client con strumenti nel codice di avvio che viene eseguito quando non è aperta alcuna richiesta o nel codice che genera un nuovo thread.
# Strumentazione delle richieste HTTP in entrata con l'X-Ray SDK for .NET
**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
Puoi utilizzare l'SDK X-Ray per tracciare le richieste HTTP in entrata che la tua applicazione serve su un'istanza EC2 in Amazon EC2 o Amazon ECS. AWS Elastic Beanstalk
Utilizza un gestore di messaggi per analizzare le richieste HTTP in ingresso. Quando aggiungete il gestore di messaggi X-Ray all'applicazione, l'X-Ray SDK for .NET crea un segmento per ogni richiesta campionata. Questo segmento include durata, metodo e conclusione della richiesta HTTP. Analisi ulteriori creano sottosegmenti associati a questo segmento.
**Nota**
Per quanto riguarda AWS Lambda le funzioni, Lambda crea un segmento per ogni richiesta campionata. Per ulteriori informazioni, consulta [AWS Lambda e AWS X-Ray](xray-services-lambda.md).
Ogni segmento ha un nome che identifica l'applicazione nella mappa dei servizi. Il segmento può essere denominato staticamente oppure è possibile configurare l'SDK per denominarlo dinamicamente in base all'intestazione dell'host nella richiesta in entrata. La denominazione dinamica consente di raggruppare le tracce in base al nome di dominio nella richiesta e di applicare un nome predefinito se il nome non corrisponde a uno schema previsto (ad esempio, se l'intestazione dell'host è falsificata).
**Richieste inoltrate**
Se un sistema di bilanciamento del carico o un altro intermediario inoltra una richiesta all'applicazione, X-Ray prende l'IP del client dall'`X-Forwarded-For`intestazione della richiesta anziché dall'IP di origine nel pacchetto IP. L'IP del client registrato per una richiesta inoltrata può essere falsificato, quindi non dovrebbe essere considerato attendibile.
Il gestore dei messaggi crea un segmento per ogni richiesta in entrata con un blocco `http` che contiene le informazioni riportate qui di seguito:
+ **Metodo HTTP**: GET, POST, PUT, DELETE, ecc.
+ **Indirizzo client**: l'indirizzo IP del client che ha inviato la richiesta.
+ **Codice di risposta**: il codice di risposta HTTP per la richiesta completata.
+ **Tempistica**: l'ora di inizio (quando è stata ricevuta la richiesta) e l'ora di fine (quando è stata inviata la risposta).
+ **Agente utente**: il `user-agent` codice della richiesta.
+ **Lunghezza del contenuto**: il `content-length` risultato della risposta.
**Topics**
+ [Analisi delle richieste in entrata (.NET)](#xray-sdk-dotnet-messagehandler-globalasax)
+ [Analisi delle richieste in entrata (.NET Core)](#xray-sdk-dotnet-messagehandler-startupcs)
+ [Configurazione di una strategia di denominazione dei segmenti](#xray-sdk-dotnet-messagehandler-naming)
## Analisi delle richieste in entrata (.NET)
Per analizzare le richieste elaborate dalla tua applicazione, chiama `RegisterXRay` nel metodo `Init` del tuo file `global.asax`.
**Example global.asax - Gestore messaggi**
```
using System.Web.Http;
using [Amazon.XRay.Recorder.Handlers.AspNet](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AspNet.htm);
namespace SampleEBWebApplication
{
public class MvcApplication : System.Web.HttpApplication
{
public override void Init()
{
base.Init();
AWSXRayASPNET.RegisterXRay(this, "MyApp");
}
}
}
```
## Analisi delle richieste in entrata (.NET Core)
Per le richieste di strumenti servite dalla tua applicazione, chiama `UseXRay` method prima di qualsiasi altro middleware nel `Configure` metodo della tua classe Startup, poiché idealmente il middleware X-Ray dovrebbe essere il primo middleware a elaborare la richiesta e l'ultimo middleware a elaborare la risposta nella pipeline.
**Nota**
Per .NET Core 2.0, se hai un `UseExceptionHandler` metodo nell'applicazione, assicurati di chiamare dopo metodo per assicurarti che le eccezioni vengano registrate. `UseXRay` `UseExceptionHandler`
**Example Startup.cs**
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseXRay("MyApp");
// additional middleware
...
}
```
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseExceptionHandler("/Error");
app.UseXRay("MyApp");
// additional middleware
...
}
```
Il metodo `UseXRay` può anche ricevere un [oggetto di configurazione](xray-sdk-dotnet-configuration.md) come secondo argomento.
```
app.UseXRay("MyApp", configuration);
```
## Configurazione di una strategia di denominazione dei segmenti
AWS X-Ray utilizza un *nome di servizio* per identificare l'applicazione e distinguerla dalle altre applicazioni, database, risorse esterne APIs e AWS risorse utilizzate dall'applicazione. [Quando X-Ray SDK genera segmenti per le richieste in entrata, registra il nome del servizio dell'applicazione nel campo del nome del segmento.](xray-api-segmentdocuments.md#api-segmentdocuments-fields)
L'X-Ray SDK può denominare i segmenti dopo il nome host nell'intestazione della richiesta HTTP. Tuttavia, questa intestazione può essere falsificata, il che potrebbe causare nodi imprevisti nella mappa dei servizi. Per evitare che l'SDK nomini i segmenti in modo errato a causa di richieste con intestazioni host contraffatte, è necessario specificare un nome predefinito per le richieste in entrata.
Se la tua applicazione soddisfa le richieste per più domini, puoi configurare l'SDK in modo che utilizzi una strategia di denominazione dinamica che rifletta questo aspetto nei nomi dei segmenti. Una strategia di denominazione dinamica consente all'SDK di utilizzare il nome host per le richieste che corrispondono a uno schema previsto e di applicare il nome predefinito alle richieste che non lo fanno.
Ad esempio, potresti avere una singola applicazione che serve le richieste a tre sottodomini:, e. `www.example.com` `api.example.com` `static.example.com` È possibile utilizzare una strategia di denominazione dinamica con lo schema `*.example.com` per identificare i segmenti per ogni sottodominio con un nome diverso, ottenendo tre nodi di servizio sulla mappa dei servizi. Se l'applicazione riceve richieste con un nome host che non corrisponde allo schema, sulla mappa dei servizi verrà visualizzato un quarto nodo con un nome di fallback specificato dall'utente.
Per utilizzare lo stesso nome per tutti i segmenti della richiesta, specifica il nome della tua applicazione quando inizializzi il gestore dei messaggi, come illustrato nella [sezione precedente](#xray-sdk-dotnet-messagehandler-globalasax). Ciò ha lo stesso effetto di creare una [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm) e passarla al metodo `RegisterXRay`.
```
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
```
**Nota**
[È possibile sovrascrivere il nome di servizio predefinito definito nel codice con la `AWS_XRAY_TRACING_NAME` variabile di ambiente.](xray-sdk-dotnet-configuration.md#xray-sdk-dotnet-configuration-envvars)
Una strategia di denominazione dinamica definisce un modello al quale devono corrispondere i nomi degli host e un nome di default per l'utilizzo qualora il nome dell'host nella richiesta HTTP non corrisponda al modello. Per denominare i segmenti in modo dinamico, è necessario creare una [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm) e passarla al metodo `RegisterXRay`.
```
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
```
# Tracciamento delle chiamate AWS SDK con X-Ray SDK for .NET
**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
[Quando l'applicazione effettua chiamate per Servizi AWS archiviare dati, scrivere in una coda o inviare notifiche, X-Ray SDK for .NET tiene traccia delle chiamate downstream in sottosegmenti.](xray-sdk-dotnet-subsegments.md) Le risorse tracciate Servizi AWS e a cui accedi all'interno di tali servizi (ad esempio, un bucket Amazon S3 o una coda Amazon SQS) vengono visualizzate come nodi downstream sulla mappa di traccia nella console X-Ray.
Puoi strumentare tutti i tuoi AWS SDK per .NET clienti chiamando prima di crearli. `RegisterXRayForAllServices`
**Example SampleController.cs - Strumentazione client DynamoDB**
```
using Amazon;
using Amazon.Util;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.AwsSdk](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AwsSdk.htm);
namespace SampleEBWebApplication.Controllers
{
public class SampleController : ApiController
{
AWSSDKHandler.RegisterXRayForAllServices();
private static readonly Lazy LazyDdbClient = new Lazy(() =>
{
var client = new AmazonDynamoDBClient(EC2InstanceMetadata.Region ?? RegionEndpoint.USEast1);
return client;
});
```
Per analizzare il client di alcuni servizi e non di altri, chiama `RegisterXRay` invece di `RegisterXRayForAllServices`. Sostituisci il testo evidenziato con il nome dell'interfaccia client del servizio.
```
AWSSDKHandler.RegisterXRay()
```
Per tutti i servizi, puoi vedere il nome dell'API richiamata nella console X-Ray. Per un sottoinsieme di servizi, l'SDK X-Ray aggiunge informazioni al segmento per fornire una maggiore granularità nella mappa dei servizi.
Ad esempio, quando si effettua una chiamata con un client DynamoDB con strumentazione, l'SDK aggiunge il nome della tabella al segmento per le chiamate destinate a una tabella. Nella console, ogni tabella appare come un nodo separato nella mappa dei servizi, con un nodo DynamoDB generico per le chiamate che non hanno come destinazione una tabella.
**Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Quando si accede alle risorse con nome, le chiamate ai seguenti servizi creano ulteriori nodi della mappa del servizio. Le chiamate che non sono hanno come obiettivo risorse specifiche creano un nodo generico per il servizio.
+ **Amazon DynamoDB**: nome della tabella
+ **Amazon Simple Storage Service**: nome del bucket e della chiave
+ **Amazon Simple Queue Service**: nome della coda
# Tracciamento delle chiamate ai servizi Web HTTP downstream con X-Ray SDK for .NET
**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
Quando l'applicazione effettua chiamate a microservizi o a HTTP pubblico APIs, è possibile utilizzare il metodo di estensione di X-Ray SDK for .NET `GetResponseTraced` `System.Net.HttpWebRequest` per strumentare tali chiamate e aggiungere l'API al grafico del servizio come servizio downstream.
**Example HttpWebRequest**
```
using System.Net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://names.example.com/api");
request.GetResponseTraced();
}
```
Per le chiamate asincrone, utilizza `GetAsyncResponseTraced`.
```
request.GetAsyncResponseTraced();
```
Se utilizzi [https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx](https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx), usa il gestore della delegazione `HttpClientXRayTracingHandler` per memorizzare le chiamate.
**Example HttpClient**
```
using System.Net.Http;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler()));
httpClient.GetAsync(URL);
}
```
Quando si effettua una chiamata a un'API Web downstream, l'X-Ray SDK for .NET registra un sottosegmento con informazioni sulla richiesta e sulla risposta HTTP. X-Ray utilizza il sottosegmento per generare un segmento dedotto per l'API.
**Example Sottosegmento per una chiamata HTTP a valle**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento dedotto per una chiamata HTTP a valle**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Tracciamento delle query SQL con X-Ray SDK for .NET
**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
L'X-Ray SDK for .NET fornisce una classe wrapper`System.Data.SqlClient.SqlCommand`, denominata`TraceableSqlCommand`, che è possibile utilizzare al posto di. `SqlCommand` Puoi inizializzare un comando SQL con la classe `TraceableSqlCommand`.
## Tracciamento di query SQL con metodi sincroni e asincroni
I seguenti esempi mostrano come utilizzare `TraceableSqlCommand` per tracciare automaticamente query SQL Server in modo sincrono e asincrono.
**Example `Controller.cs` - Analisi client SQL (sincrono)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
{
sqlCommand.Connection.Open();
sqlCommand.ExecuteNonQuery();
}
}
```
Puoi eseguire la query in modo asincrono utilizzando il metodo `ExecuteReaderAsync`.
**Example `Controller.cs` - Analisi client SQL (Asincrono)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
{
await sqlCommand.ExecuteReaderAsync();
}
}
```
## Raccolta di query SQL effettuate su SQL Server
Puoi abilitare l'acquisizione di `SqlCommand.CommandText` come parte del sottosegmento creato dalla query SQL. `SqlCommand.CommandText` viene visualizzato come il campo `sanitized_query` nel sottosegmento JSON. Per impostazione predefinita, questa caratteristica è disabilitata per motivi di sicurezza.
**Nota**
Non abilitare la caratteristica di raccolta se si includono informazioni sensibili come testo in chiaro nelle query SQL.
Puoi abilitare la raccolta di query SQL in due modi:
+ Imposta la proprietà `CollectSqlQueries` su `true` nella configurazione globale dell'applicazione.
+ Imposta il parametro `collectSqlQueries` nell'istanza `TraceableSqlCommand` su `true` per raccogliere le chiamate all'interno dell'istanza.
### Abilita la proprietà globale CollectSqlQueries
I seguenti esempi mostrano come abilitare la proprietà `CollectSqlQueries` per .NET e .NET Core.
------
#### [ .NET ]
Per impostare la proprietà `CollectSqlQueries` su `true` nella configurazione globale dell'applicazione in .NET, modifica la `appsettings` del file `Web.config` o `App.config`, come mostrato.
**Example `App.config`Oppure`Web.config`: abilita la raccolta di query SQL a livello globale**
```
```
------
#### [ .NET Core ]
Per impostare la `CollectSqlQueries` proprietà su `true` nella configurazione globale dell'applicazione in.NET Core, modifica il `appsettings.json` file con la chiave X-Ray, come illustrato.
**Example `appsettings.json`— Abilita la raccolta di query SQL a livello globale**
```
{
"XRay": {
"CollectSqlQueries":"true"
}
}
```
------
### Abilita il collectSqlQueries parametro
Puoi impostare il parametro `collectSqlQueries` nell'istanza `TraceableSqlCommand` su per `true` per raccogliere il testo della query SQL per le query SQL Server eseguite utilizzando tale istanza. L'impostazione del parametro su `false` disabilita la caratteristica `CollectSqlQuery` per l'istanza `TraceableSqlCommand`.
**Nota**
Il valore di `collectSqlQueries` nell'istanza `TraceableSqlCommand` sostituisce il valore impostato nella configurazione globale della proprietà `CollectSqlQueries`.
**Example Esempio`Controller.cs`: abilita la raccolta di query SQL per l'istanza**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var command = new TraceableSqlCommand("SELECT " + id, sqlConnection, collectSqlQueries: true))
{
command.ExecuteNonQuery();
}
}
```
# Creazione di sottosegmenti aggiuntivi
**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
I sottosegmenti estendono il [segmento](xray-concepts.md#xray-concepts-segments) di una traccia con dettagli sul lavoro svolto per soddisfare una richiesta. Ogni volta che si effettua una chiamata con un client dotato di strumentazione, l'X-Ray SDK registra le informazioni generate in un sottosegmento. È possibile creare sottosegmenti aggiuntivi per raggruppare altri sottosegmenti, misurare le prestazioni di una sezione di codice o registrare annotazioni e metadati.
Per gestire i sottosegmenti, utilizza i metodi `BeginSubsegment` e `EndSubsegment`. Esegui qualsiasi attività nel sottosegmento in un blocco `try` e utilizza `AddException` per tracciare le eccezioni. Chiama `EndSubsegment` in un blocco `finally` per assicurarti che il sottosegmento venga chiuso.
**Example Controller.cs — Sottosegmento personalizzato**
```
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
try
{
DoWork();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
Quando si crea un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK for .NET genera un ID per tale sottosegmento e registra l'ora di inizio e l'ora di fine.
**Example Sottosegmento con metadati**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Aggiungi annotazioni e metadati ai segmenti con X-Ray SDK for .NET
**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.
**Topics**
+ [Registrazione delle annotazioni con X-Ray SDK for .NET](#xray-sdk-dotnet-segment-annotations)
+ [Registrazione di metadati con X-Ray SDK for .NET](#xray-sdk-dotnet-segment-metadata)
## 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 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 annotazioni al di fuori di una funzione AWS Lambda**
1. Procurarsi un'istanza di `AWSXRayRecorder`.
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. Chiamare `addAnnotation` con una chiave di tipo Stringa e un valore booleano, Int32, Int64, Double o Stringa.
```
recorder.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");
```
**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.
1. Aggiungi l'annotazione al segmento o al sottosegmento.
1. 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'`addAnnotation`operazione due volte con la stessa chiave sovrascrive un valore registrato in precedenza sullo stesso segmento o sottosegmento.
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 .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 di`AWSXRayRecorder`, come mostrato nel seguente esempio di codice:
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. 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'`AddMetadata`operazione 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'`AddMetadata`operazione due volte con la stessa chiave sovrascrive un valore registrato in precedenza sullo stesso segmento o sottosegmento.