Наблюдаемость пакета SDK для Azure Cosmos DB

Пакеты SDK для .NET и Java для Azure Cosmos DB поддерживают распределенную трассировку для мониторинга приложений. Трассировка потока запросов полезна при отладке, анализе задержки и производительности и сборе диагностики. Трассировка инструментов для приложений с помощью OpenTelemetry, которая является нейтральной поставщиком и имеет набор семантических соглашений, чтобы обеспечить стандартизованный формат данных независимо от выбранного экспортера, или использовать пакет SDK Application Insights или дистрибутив OpenTelemetry Azure Monitor.

Начало работы

Распределенная трассировка доступна в следующих пакетах SDK:

Атрибуты трассировки

Трассировки Azure Cosmos DB соответствуют спецификации базы данных OpenTelemetry , а также предоставляют несколько настраиваемых атрибутов. Вы можете видеть различные атрибуты в зависимости от операции запроса, и эти атрибуты являются основными атрибутами для всех запросов.

Сбор диагностических данных

Если вы настроили журналы в поставщике трассировки, вы можете автоматически получить диагностику для запросов Azure Cosmos DB, которые завершились сбоем или имели высокую задержку. Эти журналы помогают диагностировать неудачные и медленные запросы, не требуя написания пользовательского кода для их фиксации.

CosmosClientOptions options = new CosmosClientOptions()
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
    {
        DisableDistributedTracing = false,
        CosmosThresholdOptions = new CosmosThresholdOptions()
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
            NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
        }
    },
};

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

    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();

Настройка OpenTelemetry

Чтобы использовать OpenTelemetry с SDK Azure Cosmos DB, добавьте источник Azure.Cosmos.Operation в поставщик трассировки. OpenTelemetry совместим со многими экспортерами, которые позволяют получать данные. В следующем примере используется Azure Monitor OpenTelemetry Exporter, но вы можете настроить любой экспортер, который вам нужен. В зависимости от выбранного экспортера может появиться задержка приема данных до нескольких минут.

В этом примере показано, как настроить OpenTelemetry для консольного приложения .NET. Полный пример см. на сайте 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();

Настройте SDK для Application Insights

Существует множество различных способов настройки Application Insights в зависимости от языка, в который записывается приложение, и в вычислительной среде. Дополнительные сведения см. в документации по Application Insights. Прием данных в Application Insights может занять до нескольких минут.

В следующем примере показано, как настроить Application Insights для консольного приложения .NET. Полный пример см. на сайте GitHub.

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

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

После приема данных трассировки в Application Insights его можно визуализировать на портале Azure, чтобы понять поток запросов в приложении. Ниже приведен пример данных трассировки из межсекционного запроса в поиске транзакций в левой области навигации портала Azure.

Дальнейшие шаги

• Начало работы с пакетом SDK для .NET
• Приступая к работе с пакетом SDK для Java
• Мониторинг Azure Cosmos DB