Наблюдаемость пакета SDK для Azure Cosmos DB
ОБЛАСТЬ ПРИМЕНЕНИЯ: 
NoSQL
Пакеты SDK для .NET и Java для Azure Cosmos DB поддерживают распределенную трассировку для мониторинга приложений. Трассировка потока запросов полезна при отладке, анализе задержки и производительности и сборе диагностика. Трассировка инструментов для приложений с помощью OpenTelemetry, которая является нейтральной поставщиком и имеет набор семантических соглашений, чтобы обеспечить стандартизованный формат данных независимо от выбранного экспортера, или использовать пакет SDK Application Insights или дистрибутив OpenTelemetry Azure Monitor.
Начало работы
Распределенная трассировка доступна в следующих пакетах SDK:
| SDK | Поддерживаемая версия | Примечания. |
|---|---|---|
| Пакет SDK версии 3 для .NET | >= 3.36.0 |
Эта функция доступна как в предварительной версии, так и в версиях, отличных от предварительной версии. Для версий, отличных от предварительной версии, она отключена по умолчанию. Вы можете включить трассировку, задав параметр DisableDistributedTracing = false CosmosClientOptions.CosmosClientTelemetryOptions. |
| Предварительная версия пакета SDK для .NET версии 3 | >= 3.33.0-preview |
Эта функция доступна как в предварительной версии, так и в версиях, отличных от предварительной версии. Для предварительных версий он включен по умолчанию. Трассировку можно отключить, задав параметр DisableDistributedTracing = true CosmosClientOptions.CosmosClientTelemetryOptions. |
| Пакет SDK для Java версии 4 | >= 4.43.0 |
Атрибуты трассировки
Трассировки Azure Cosmos DB соответствуют спецификации базы данных OpenTelemetry, а также предоставляют несколько настраиваемых атрибутов. Вы можете видеть различные атрибуты в зависимости от операции запроса, и эти атрибуты являются основными атрибутами для всех запросов.
| Атрибут | Тип | Описание: |
|---|---|---|
net.peer.name |
строка | Имя узла Azure Cosmos DB. |
db.name |
строка | Имя базы данных Azure Cosmos DB. |
db.system |
строка | Идентификатор службы базы данных. Предназначен cosmosdb для всех запросов. |
db.operation |
строка | Имя операции, например. CreateItemAsync. |
db.cosmosdb.container |
строка | Имя контейнера Azure Cosmos DB. |
db.cosmosdb.client_id |
строка | Идентификатор, представляющий уникальный экземпляр клиента. |
db.cosmosdb.operation_type |
строка | Тип операции, например. Create. |
db.cosmosdb.connection_mode |
строка | Режим подключения клиента. direct или gateway. |
db.cosmosdb.status_code |
INT | Код состояния запроса. |
db.cosmosdb.sub_status_code |
INT | Код состояния вложенных данных для запроса. |
db.cosmosdb.request_charge |
двойной точности | Ез, потребляемые для операции. |
db.cosmosdb.regions_contacted |
строка | Список регионов, связаемых с учетной записью Azure Cosmos DB. |
user_agent.original |
строка | Полная строка агента пользователя, созданная пакетом SDK Для Azure Cosmos DB. |
Сбор диагностика
Если вы настроили журналы в поставщике трассировки, вы можете автоматически получить диагностика для запросов Azure Cosmos DB, которые завершились сбоем или имели высокую задержку. Эти журналы помогают диагностировать неудачные и медленные запросы, не требуя их записи пользовательского кода.
Помимо получения журналов диагностики для неудачных запросов, можно настроить различные пороговые значения задержки для сбора диагностика из успешных запросов. Значения по умолчанию — 100 мс для операций с точками и 500 мс для операций, не являющихся точками. Эти пороговые значения можно настроить с помощью параметров клиента.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
Вы можете настроить уровень журнала для управления тем, какие диагностика журналы вы получаете.
| Уровень журнала | Description |
|---|---|
| Ошибка | Журналы только для ошибок. |
| Предупреждение | Журналы ошибок и запросов с высокой задержкой на основе настроенных пороговых значений. |
| Информация | Журналы определенного уровня информации отсутствуют. Журналы на этом уровне совпадают с использованием предупреждения. |
В зависимости от среды приложения существуют различные способы настройки уровня журнала. Ниже приведен пример конфигурации в appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Настройка OpenTelemetry
Чтобы использовать OpenTelemetry с пакетами SDK Для Azure Cosmos DB, добавьте источник в Azure.Cosmos.Operation поставщик трассировки. OpenTelemetry совместим с многими экспортерами, которые могут получать данные. В следующем примере используется, Azure Monitor OpenTelemetry Exporterно вы можете настроить любой нужный экспортер. В зависимости от выбранного экспортера может появиться задержка приема данных до нескольких минут.
Совет
Если вы используете Azure.Monitor.OpenTelemetry.Exporter пакет, убедитесь, что вы используете версию >= 1.0.0-beta.11.
Если вы используете ASP.NET Core и Azure Monitor, рекомендуется использовать дистрибутив Azure Monitor OpenTelemetry.
В этом примере показано, как настроить 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 может занять до нескольких минут.
Примечание.
Используйте версию >= 2.22.0-beta2 пакета Application Insights для целевой среды .NET.
В следующем примере показано, как настроить 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.
