Możliwość obserwowania zestawu SDK usługi Azure Cosmos DB
DOTYCZY: 
NoSQL
Zestawy SDK platformy .NET i java usługi Azure Cosmos DB obsługują śledzenie rozproszone, aby ułatwić monitorowanie aplikacji. Śledzenie przepływu żądań jest przydatne podczas debugowania, analizowania opóźnienia i wydajności oraz zbierania danych diagnostycznych. Śledzenie instrumentacji dla aplikacji przy użyciu biblioteki OpenTelemetry, która jest neutralna dla dostawcy i ma zestaw konwencji semantycznych w celu zapewnienia standardowego formatu danych niezależnie od wybranego eksportera lub użycia zestawu SDK usługi Application Insights lub dystrybucji OpenTelemetry usługi Azure Monitor.
Rozpocznij
Śledzenie rozproszone jest dostępne w następujących zestawach SDK:
| SDK | Obsługiwana wersja | Uwagi |
|---|---|---|
| Zestaw SDK platformy .NET w wersji 3 | >= 3.36.0 |
Ta funkcja jest dostępna zarówno w wersji zapoznawczej, jak i w wersjach innych niż wersja zapoznawcza. W przypadku wersji innych niż wersja zapoznawcza jest ona domyślnie wyłączona. Śledzenie można włączyć, ustawiając wartość w pliku DisableDistributedTracing = false CosmosClientOptions.CosmosClientTelemetryOptions. |
| Zestaw SDK platformy .NET w wersji 3 (wersja zapoznawcza) | >= 3.33.0-preview |
Ta funkcja jest dostępna zarówno w wersji zapoznawczej, jak i w wersjach innych niż wersja zapoznawcza. W przypadku wersji zapoznawczych jest ona domyślnie włączona. Śledzenie można wyłączyć, ustawiając wartość w CosmosClientOptions.CosmosClientTelemetryOptionspliku DisableDistributedTracing = true . |
| Zestaw SDK języka Java w wersji 4 | >= 4.43.0 |
Atrybuty śledzenia
Ślady usługi Azure Cosmos DB są zgodne ze specyfikacją bazy danych OpenTelemetry, a także udostępniają kilka atrybutów niestandardowych. Można zobaczyć różne atrybuty w zależności od operacji żądania, a te atrybuty są podstawowymi atrybutami dla wszystkich żądań.
| Atrybut | Type | opis |
|---|---|---|
net.peer.name |
string | Nazwa hosta usługi Azure Cosmos DB. |
db.name |
string | Nazwa bazy danych usługi Azure Cosmos DB. |
db.system |
string | Identyfikator usługi bazy danych. Dotyczy cosmosdb wszystkich żądań. |
db.operation |
string | Nazwa operacji, np. CreateItemAsync. |
db.cosmosdb.container |
string | Nazwa kontenera usługi Azure Cosmos DB. |
db.cosmosdb.client_id |
string | Identyfikator reprezentujący unikatowe wystąpienie klienta. |
db.cosmosdb.operation_type |
string | Typ operacji, np. Create. |
db.cosmosdb.connection_mode |
string | Tryb połączenia klienta. direct lub gateway. |
db.cosmosdb.status_code |
int | Kod stanu żądania. |
db.cosmosdb.sub_status_code |
int | Kod stanu podrzędnego żądania. |
db.cosmosdb.request_charge |
double | Jednostki RU używane dla operacji. |
db.cosmosdb.regions_contacted |
string | Lista regionów, z których nawiązano kontakt w ramach konta usługi Azure Cosmos DB. |
user_agent.original |
string | Pełny ciąg agenta użytkownika wygenerowany przez zestaw SDK usługi Azure Cosmos DB. |
Zbieranie diagnostyki
Jeśli skonfigurowano dzienniki u dostawcy śledzenia, możesz automatycznie uzyskać diagnostykę żądań usługi Azure Cosmos DB, które zakończyły się niepowodzeniem lub miały duże opóźnienie. Te dzienniki mogą pomóc w diagnozowaniu niepoudanych i powolnych żądań bez konieczności przechwytywania ich przez żaden kod niestandardowy.
Oprócz pobierania dzienników diagnostycznych dla żądań zakończonych niepowodzeniem można skonfigurować różne progi opóźnienia dla tego, kiedy zbierać dane diagnostyczne z żądań zakończonych powodzeniem. Wartości domyślne to 100 ms dla operacji punktów i 500 ms dla operacji innych niż punkt. Te progi można dostosować za pomocą opcji klienta.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
Możesz skonfigurować poziom dziennika, aby kontrolować, które dzienniki diagnostyczne są odbierane.
| Poziom dziennika | opis |
|---|---|
| Błąd | Rejestruje tylko błędy. |
| Ostrzeżenie | Rejestruje błędy i żądania o wysokim opóźnieniu na podstawie skonfigurowanych progów. |
| Informacja | Nie ma żadnych określonych dzienników na poziomie informacji. Dzienniki na tym poziomie są takie same jak w przypadku używania ostrzeżenia. |
W zależności od środowiska aplikacji istnieją różne sposoby konfigurowania poziomu dziennika. Oto przykładowa konfiguracja w pliku appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Konfigurowanie biblioteki OpenTelemetry
Aby użyć biblioteki OpenTelemetry z zestawami SDK usługi Azure Cosmos DB, dodaj Azure.Cosmos.Operation źródło do dostawcy śledzenia. OpenTelemetry jest zgodny z wieloma eksporterami, którzy mogą pozyskiwać dane. W poniższym przykładzie użyto elementu Azure Monitor OpenTelemetry Exporter, ale można wybrać opcję skonfigurowania dowolnego eksportera. W zależności od wybranego eksportera może wystąpić opóźnienie pozyskiwania danych do kilku minut.
Napiwek
Jeśli używasz Azure.Monitor.OpenTelemetry.Exporter pakietu, upewnij się, że używasz wersji >= 1.0.0-beta.11.
Jeśli używasz ASP.NET Core i Azure Monitor, zalecamy użycie dystrybucji OpenTelemetry usługi Azure Monitor.
W tym przykładzie pokazano, jak skonfigurować metrykę OpenTelemetry dla aplikacji konsolowej platformy .NET. Zobacz kompletny przykład w witrynie 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();
Konfigurowanie zestawu SDK usługi Application Insights
Istnieje wiele różnych sposobów konfigurowania usługi Application Insights w zależności od języka, w jakim aplikacja jest napisana w środowisku obliczeniowym. Aby uzyskać więcej informacji, zobacz dokumentację usługi Application Insights. Pozyskiwanie danych do usługi Application Insights może potrwać do kilku minut.
Uwaga
Użyj wersji >= 2.22.0-beta2 pakietu usługi Application Insights dla docelowego środowiska .NET.
W poniższym przykładzie pokazano, jak skonfigurować usługę Application Insights dla aplikacji konsolowej platformy .NET. Zobacz kompletny przykład w witrynie GitHub.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
Po pozyskiwaniu danych śledzenia do usługi Application Insights można je wizualizować w witrynie Azure Portal, aby zrozumieć przepływ żądań w aplikacji. Oto przykład danych śledzenia z zapytania obejmującego wiele partycji w wyszukiwaniu transakcji w lewym obszarze nawigacji w witrynie Azure Portal.
