Osservabilità dell'SDK di Azure Cosmos DB

Articolo
03/25/2024

SI APPLICA A: NoSQL

Gli SDK .NET e Java di Azure Cosmos DB supportano la traccia distribuita per monitorare le applicazioni. La traccia del flusso delle richieste è utile per il debug, l'analisi della latenza e delle prestazioni e la raccolta della diagnostica. Instrumentare la traccia per le applicazioni usando OpenTelemetry, che è indipendente dal fornitore e dispone di un set di convenzioni semantiche per garantire un formato di dati standardizzato indipendentemente dall'utilità di esportazione scelta oppure usare Application Insights SDK o OpenTelemetry Distro di Monitoraggio di Azure.

Operazioni preliminari

La traccia distribuita è disponibile negli SDK seguenti:

SDK	Versione supportata	Note
.NET v3 SDK	>= `3.33.0-preview`	Questa funzionalità è attivata per impostazione predefinita se si usa una versione dell'SDK di anteprima supportata. È possibile disabilitare la traccia impostando `IsDistributedTracingEnabled = false` in `CosmosClientOptions`.
Java v4 SDK	>= `4.43.0`

Attributi di traccia

Le tracce di Azure Cosmos DB seguono la specifica del database OpenTelemetry e forniscono anche diversi attributi personalizzati. È possibile che vengano visualizzati attributi diversi a seconda del funzionamento della richiesta, che sono attributi di base per tutte le richieste.

Attributo	Tipo	Descrzione
`net.peer.name`	stringa	Nome host di Azure Cosmos DB.
`db.name`	string	Nome del database Azure Cosmos DB.
`db.system`	string	Identificatore per il servizio di database. È `cosmosdb` per tutte le richieste.
`db.operation`	string	Nome dell'operazione, ad es. `CreateItemAsync`.
`db.cosmosdb.container`	string	Nome del contenitore Azure Cosmos DB.
`db.cosmosdb.client_id`	string	Identificatore che rappresenta un'istanza client univoca.
`db.cosmosdb.operation_type`	string	Tipo di operazione, ad es. `Create`.
`db.cosmosdb.connection_mode`	string	Modalità di connessione client. `direct` o `gateway`.
`db.cosmosdb.status_code`	int	Codice di stato della richiesta.
`db.cosmosdb.sub_status_code`	int	Codice di stato secondario della richiesta.
`db.cosmosdb.request_charge`	double	UR utilizzate per l'operazione.
`db.cosmosdb.regions_contacted`	string	Elenco delle aree contattate nell'account Azure Cosmos DB.
`user_agent.original`	string	Stringa dell'agente utente completa generata da Azure Cosmos DB SDK.

Raccogliere informazioni di diagnostica

Se sono stati configurati i log nel provider di traccia, è possibile ottenere automaticamente la diagnostica per le richieste di Azure Cosmos DB non riuscite o con una latenza elevata. Questi log consentono di diagnosticare le richieste non riuscite e lente senza richiedere codice personalizzato per acquisirle.

.NET
Java

Oltre a ottenere i log di diagnostica per le richieste non riuscite, anche le operazioni sui punti che impiegano più di 100 ms e le operazioni di query che impiegano più di 500 ms generano diagnostica. È possibile configurare il livello di log per controllare i log di diagnostica ricevuti.

Livello di registrazione	Descrizione
Error	Log solo per gli errori.
Avviso	Log per gli errori e le richieste di latenza elevata.
Informazioni	Non sono presenti log specifici a livello di informazioni. I log in questo livello sono uguali all'uso dell'avviso.

A seconda dell'ambiente dell'applicazione, esistono diversi modi per configurare il livello di log. Ecco una configurazione di esempio in appSettings.json:

{ 
    "Logging": {
        "LogLevel": {
            "Azure-Cosmos-Operation-Request-Diagnostics": "Information"
        }
    }
}

Oltre a ottenere i log di diagnostica per le richieste non riuscite, è possibile configurare condizioni diverse per quando raccogliere la diagnostica dalle richieste riuscite. Le condizioni includono una soglia di latenza sia per le operazioni di punto che per le operazioni non di punto e una soglia per le richieste che superano un determinato numero di UR. Queste soglie possono essere impostate nel client Azure Cosmos DB.

    CosmosAsyncClient client = new CosmosClientBuilder()
            .endpoint("<Your account endpoint>")
            .key("<Your account key>")
            .clientTelemetryConfig(new CosmosClientTelemetryConfig()
                .diagnosticsThresholds(
                    new CosmosDiagnosticsThresholds()
                        .setPointOperationLatencyThreshold(Duration.ofMillis(100))
                        .setNonPointOperationLatencyThreshold(Duration.ofMillis(2000))
                        .setRequestChargeThreshold(100)))
            .buildAsyncClient();

Configurare OpenTelemetry

Per usare OpenTelemetry con gli SDK di Azure Cosmos DB, aggiungere l'origine Azure.Cosmos.Operation al provider di traccia. OpenTelemetry è compatibile con molti esportatori che possono inserire i dati. Nell'esempio seguente viene usato Azure Monitor OpenTelemetry Exporter, ma è possibile scegliere di configurare qualsiasi utilità di esportazione desiderata. A seconda dell'utilità di esportazione scelta, è possibile riscontrare un ritardo nell'inserimento dei dati fino a pochi minuti.

Suggerimento

Se si usa il pacchetto Azure.Monitor.OpenTelemetry.Exporter, assicurarsi di usare la versione >= 1.0.0-beta.11. Se si usano ASP.NET Core e Monitoraggio di Azure, è consigliabile usare invece la distribuzione OpenTelemetry di Monitoraggio di Azure.

Questo esempio illustra come configurare OpenTelemetry per un'app console .NET. Visualizzare l'esempio completo in GitHub.

ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
            serviceName: serviceName,
            serviceVersion: "1.0.0");

// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
    = LoggerFactory.Create(builder => builder
                                        .AddConfiguration(configuration.GetSection("Logging"))
                                        .AddOpenTelemetry(options =>
                                        {
                                            options.IncludeFormattedMessage = true;
                                            options.SetResourceBuilder(resource);
                                            options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
                                        }));
/*.AddFilter(level => level == LogLevel.Error) // Filter  is irrespective of event type or event name*/

AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();

// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
               "Azure.Cosmos.Request", // Cosmos DB source for DIRECT Mode network request level telemetry
               "Sample.Application") 
    .AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
    .AddHttpClientInstrumentation() // Added to capture HTTP telemetry
    .SetResourceBuilder(resource)
    .Build();

Configurare Application Insights SDK

Esistono molti modi diversi per configurare Application Insights a seconda del linguaggio in cui viene scritta l'applicazione e dell'ambiente di calcolo. Per altre informazioni, vedere la Documentazione di Application Insights. L'inserimento di dati in Application Insights può richiedere alcuni minuti.

Nota

Usare la versione >= 2.22.0-beta2 del pacchetto di Application Insights per l'ambiente .NET di destinazione.

L'esempio seguente illustra come configurare Application Insights per un'app console .NET. Visualizzare l'esempio completo in GitHub.

IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);

IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

Dopo aver inserito i dati di traccia in Application Insights, è possibile visualizzarli nel portale di Azure per comprendere il flusso di richiesta nell'applicazione. Di seguito è riportato un esempio di dati di traccia di una query tra partizioni nella ricerca delle transazioni nel riquadro di spostamento a sinistra del portale di Azure.

Share via