Osservabilità dell'SDK di Azure Cosmos DB
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.36.0 |
Questa funzionalità è disponibile sia nelle versioni di anteprima che non in anteprima. Per le versioni non di anteprima, è disattivata per impostazione predefinita. È possibile abilitare la traccia impostando DisableDistributedTracing = false in CosmosClientOptions.CosmosClientTelemetryOptions. |
| Anteprima di .NET v3 SDK | >= 3.33.0-preview |
Questa funzionalità è disponibile sia nelle versioni di anteprima che non in anteprima. Per le versioni di anteprima, è attivato per impostazione predefinita. È possibile disabilitare la traccia impostando DisableDistributedTracing = true in CosmosClientOptions.CosmosClientTelemetryOptions. |
| 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 visualizzare attributi diversi a seconda del funzionamento della richiesta e questi attributi sono attributi di base per tutte le richieste.
| Attributo | Tipo | Descrizione |
|---|---|---|
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.
Oltre a ottenere i log di diagnostica per le richieste non riuscite, è possibile configurare soglie di latenza diverse per quando raccogliere la diagnostica da richieste riuscite. I valori predefiniti sono 100 ms per le operazioni punto e 500 ms per le operazioni non di punto. Queste soglie possono essere modificate tramite le opzioni client.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
È possibile configurare il livello di log per controllare i log di diagnostica ricevuti.
| Livello di registrazione | Descrizione |
|---|---|
| Error | Log solo per gli errori. |
| Avviso | Registra gli errori e le richieste di latenza elevata in base alle soglie configurate. |
| 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"
}
}
}
Configurare OpenTelemetry
Questa sezione descrive la configurazione necessaria per Azure Cosmos DB Java SDK e .NET SDK.
Per usare OpenTelemetry con Azure Cosmos DB .NET SDK, 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 che venga visualizzato 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
"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 fino a pochi 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.
