Możliwość obserwowania zestawu SDK usługi Azure Cosmos DB

Artykuł
03/01/2024

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 instrumentów 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 Szczegółowe informacje 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 = falseCosmosClientOptions.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.CosmosClientTelemetryOptions`pliku `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.

.NET
Java

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"
        }
    }
}

Oprócz pobierania dzienników diagnostycznych dla żądań zakończonych niepowodzeniem można skonfigurować różne warunki zbierania danych diagnostycznych z pomyślnych żądań. Warunki obejmują próg opóźnienia zarówno dla operacji punktów, jak i operacji innych niż punkt oraz próg dla żądań przekraczających liczbę jednostek RU. Te progi można ustawić w kliencie usługi 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();

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 Szczegółowe informacje

Istnieje wiele różnych sposobów konfigurowania Szczegółowe informacje aplikacji 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 Szczegółowe informacje. Pozyskiwanie danych do Szczegółowe informacje aplikacji może potrwać do kilku minut.

Uwaga

Użyj wersji >= 2.22.0-beta2 pakietu application Szczegółowe informacje dla docelowego środowiska .NET.

W poniższym przykładzie pokazano, jak skonfigurować aplikację Szczegółowe informacje 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 aplikacji Szczegółowe informacje 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.