AWS X-Ray SDK per.NET

X-Ray SDK for .NET è una libreria per la strumentazione delle applicazioni Web C# .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. Ciò include informazioni sulle richieste in entrata fornite dall'applicazione e sulle chiamate che l'applicazione effettua a valle AWS servizi, alle API Web HTTP e ai database SQL.

Nota

X-Ray SDK for .NET è un progetto open source. Puoi seguire il progetto e inviare problemi e richieste di pull su GitHub: 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. Il gestore dei messaggi crea un segmento 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. Per altre funzioni, puoi configurare Lambda 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.

Successivamente, usa l'X-Ray SDK for .NET per strumentare i tuoi clienti. AWS SDK for .NET Ogni volta che effettui una chiamata a un downstream AWS servizio 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 alle API Web HTTP e ai database SQL. 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 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. Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con espressioni filtro, 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. 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 Guida di riferimento all'API SDK for .NET

• AWS X-Ray Guida di riferimento all'API SDK for .NET Core

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 for .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.

2. Cercare AWSXRayRecorder.

3. Scegliere il pacchetto e quindi scegliere Install (Installa).

Gestione delle dipendenze

L'X-Ray SDK for .NET è disponibile presso Nuget. 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.