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

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

Пакеты 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