Использование Azure Application Insights в построителе API данных

Azure Application Insights — это служба мониторинга производительности приложений (APM), которая автоматически записывает запросы, трассировки, исключения и метрики производительности. Интеграция с построителем API данных (DAB) помогает отслеживать поведение среды выполнения, диагностировать проблемы и оптимизировать производительность в рабочей среде.

Предупреждение

Интеграция Application Insights с DAB может иметь ограничения при размещении в веб-приложениях Службы приложений Azure из-за двойного инструментирования. Application Insights лучше всего работает с DAB при самостоятельном размещении в контейнерах, Azure Container Apps или службе Azure Kubernetes Service (AKS). Если необходимо использовать службу приложений, тщательно протестируйте или рассмотрите альтернативные подходы к мониторингу.

Предпосылки

• Существующий файл конфигурации DAB.
• Ресурс Azure Application Insights.
• Строка подключения Application Insights.
• CLI инструмента построения API данных. Установка интерфейса командной строки

Получение строки подключения

Перед настройкой DAB получите строку подключения Application Insights из Azure.

Портал Azure

1. Перейдите к ресурсу Application Insights на портале Azure.
2. Перейдите к обзору или свойствам.
3. Скопируйте строку подключения (а не ключ инструментирования).

Azure CLI (Интерфейс командной строки для Azure)

Bash

az monitor app-insights component show \
  --app my-app-insights \
  --resource-group my-rg \
  --query connectionString -o tsv

Командная строка

az monitor app-insights component show ^
  --app my-app-insights ^
  --resource-group my-rg ^
  --query connectionString -o tsv

Формат строки подключения

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/

Замечание

Используйте полную строку подключения (а не только ключ инструментирования) для региональных конечных точек и повышения производительности.

Настройка Application Insights

В вашем файле конфигурации добавьте раздел application-insights под runtime.telemetry.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

Эта конфигурация использует переменную среды для строки подключения. Определите это в файле .env.

app-insights-connection-string="InstrumentationKey=...;IngestionEndpoint=...;LiveEndpoint=..."

Предупреждение

Никогда не зафиксируйте строки подключения в системах управления версиями. Всегда используйте переменные среды или Azure Key Vault.

Command-line

Настройка Application Insights с помощью dab add-telemetry.

Вариант	Описание
--app-insights-enabled	Включение или отключение Application Insights (true или false).
--app-insights-conn-string	Строка подключения для Application Insights.

Включить Application Insights

Bash

dab add-telemetry \
  --app-insights-enabled true \
  --app-insights-conn-string "@env('app-insights-connection-string')"

Командная строка

dab add-telemetry ^
  --app-insights-enabled true ^
  --app-insights-conn-string "@env('app-insights-connection-string')"

Отключение Application Insights

Bash

dab add-telemetry \
  --app-insights-enabled false

Командная строка

dab add-telemetry ^
  --app-insights-enabled false

Замечание

Настройки Application Insights используют dab add-telemetry, а не dab configure.

Запустить DAB

Запустите DAB с файлом конфигурации:

dab start

Проверьте журналы запуска для подтверждения:

Application Insights telemetry is enabled with connection string from config.

Принцип работы

Если включены Application Insights, DAB:

1. Регистрирует пакет SDK Application Insights с помощью AddApplicationInsightsTelemetry().
2. Регистрирует настраиваемый инициализатор телеметрии для обогащения всех данных телеметрии с помощью свойств DAB.
3. Настраивает TelemetryClient с использованием строки подключения из файла конфигурации.
4. Интегрируется с ведением журнала ASP.NET Core для записи журналов консоли в виде трассировки.

Поток данных

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
ApplicationInsightsLoggerProvider
    ↓
AppInsightsTelemetryInitializer (adds custom properties)
    ↓
TelemetryClient
    ↓
Application Insights (Azure)

Что фиксируется

Тип телеметрии	Исходный материал	Примеры
Запросы	ПО промежуточного слоя ASP.NET Core	ЗАПРОСы REST/GraphQL, время отклика, коды состояния
Следы	ILogger звонки в DAB	Журналы запуска, журналы выполнения запросов, предупреждения
Exceptions	Необработанные исключения.	Ошибки среды выполнения, ошибки конфигурации, ошибки базы данных
Зависимости	Вызовы базы данных	Запросы SQL, операции Azure Cosmos DB, длительность
Счетчики производительности	Режим выполнения	Использование ЦП, потребление памяти, скорость запросов

Обогащение телеметрии

DAB автоматически дополняет все данные телеметрии Application Insights пользовательскими свойствами:

Недвижимость	Описание	Пример значения
ProductName	Идентификатор агента пользователя DAB	dab-1.2.3
UserAgent	Полная строка агента пользователя DAB	data-api-builder/1.2.3
Cloud.RoleName	Имя облачной роли DAB	DataApiBuilder
Component.Version	Версия DAB	1.2.3
Session.Id	Уникальный идентификатор сеанса	guid

Эти свойства помогают фильтровать и сопоставлять данные телеметрии, относящиеся к DAB, в Application Insights.

Запрос телеметрии в Azure

Трассировки (журналы)

traces
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, message, severityLevel

Сопоставление уровней логирования:

LogLevel	Степень серьезности	Ценность
Трассировка и отладка	Многословный	0
Информация	Информация	1
Предупреждение	Предупреждение	2
Ошибка	Ошибка	3
Критически важно	Критически важно	4

Запросы

requests
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, name, duration, resultCode, success

Exceptions

exceptions
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, type, outerMessage, details

Фильтрация по версии DAB

traces
| where customDimensions["Component.Version"] == "1.2.3"
| project timestamp, message, severityLevel

Поиск медленных запросов GraphQL

requests
| where name contains "/graphql"
| where duration > 1000
| project timestamp, name, duration, resultCode
| order by duration desc

Частота успешного выполнения запроса

requests
| where customDimensions["ProductName"] startswith "dab-"
| summarize 
    Total = count(),
    Success = countif(success == true),
    Failed = countif(success == false)
| extend SuccessRate = (Success * 100.0) / Total

Основные медленные операции базы данных

dependencies
| where type == "SQL" or type == "Azure Cosmos DB"
| top 10 by duration desc
| project timestamp, name, duration, target, data

Онлайновые метрики

Динамические метрики обеспечивают мониторинг в режиме реального времени с <задержкой в 1 секунду. Application Insights включает его автоматически при настройке.

Доступ к динамическим метрикам

1. Откройте ресурс Application Insights на портале Azure.
2. Перейдите к динамическим метрикам в меню слева.
3. Запустите приложение DAB.
4. В течение секунд отображаются данные в режиме реального времени.

Что вы видите

Единица измерения	Описание
Входящие запросы	Запросы REST/GraphQL в секунду
Исходящие запросы	Вызовы базы данных в секунду
Общее состояние здоровья	Частота успешного выполнения, сбои в секунду
Память / ЦП	Потребление ресурсов
Частота исключений	Исключения в секунду

Подсказка

Используйте динамические метрики во время разработки, чтобы просмотреть немедленные отзывы о запросах API и операциях базы данных.

Выборка и хранение данных

Адаптивная выборка

Пакет Application Insights SDK автоматически выполняет выборочную отправку телеметрии при высоком объеме, чтобы сократить затраты и оставаться в пределах лимитов частоты. Частота выборки показана в пользовательском интерфейсе Application Insights.

Поведение по умолчанию:

• Низкий трафик: все отправленные данные телеметрии (100%)
• Высокий трафик: выборка автоматически уменьшает объем
• Сохраняемые репрезентативные данные

Хранение данных

Plan	Хранение по умолчанию	Максимальное хранение
Free tier	90 дней	90 дней
Pay-as-you-go	90 дней	730 дней (два года)

Настройка периода хранения: Application Insights → Использование и предполагаемые затраты → Период хранения данных.

Вопросы, связанные с производительностью

Нагрузка телеметрии

Application Insights добавляет минимальные затраты:

• Память: ~10–50 МБ в зависимости от трафика
• ЦП: 1% при обычной нагрузке
• Задержка: <1 мс на запрос (асинхронный)

Лучшие практики

• Используйте переменные среды для строк подключения.
• Если не требуется, отключите в локальной среде разработки.
• Мониторинг частоты выборки в рабочей среде.
• Задайте соответствующее хранение данных для управления затратами.

Отключить в ходе разработки

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": false
      }
    }
  }
}

Экспорт и визуализация

Данные телеметрии экспортируются с помощью пакета SDK Application Insights. SDK группирует и периодически отправляет данные.

Замечание

SDK управляет временем экспорта. Поведение по умолчанию отправляет данные телеметрии в пакетах каждые несколько секунд.

Предупреждение

Эфемерные контейнеры, которые быстро отключаются, могут завершить работу до завершения процесса экспорта. Настройте окна корректного завершения работы и избегайте резкого прерывания, чтобы обеспечить ожидаемую отправку телеметрии.

Строка подключения и ключ инструментирования

Использование строк подключения (рекомендуется)

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=https://eastus.in.applicationinsights.azure.com/"
}

Преимущества:

• Конечные точки для конкретных регионов (низкая задержка)
• Поддержка суверенных облаков
• Защита на будущее (рекомендуемый Майкрософт подход)

Устаревший ключ инструментирования

Хотя они всё ещё поддерживаются, корпорация Майкрософт рекомендует использовать строки подключения для новых внедрений.

{
  "connection-string": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

Замечание

Если вы предоставляете только ключ инструментирования, Application Insights использует глобальную конечную точку приема, которая может иметь более высокую задержку.

Устранение неполадок

Ошибка: "Строка подключения Application Insights не может быть null или пуста, если включена"

Причина: enabled задано значение true , но connection-string отсутствует или пуст.

Решение: Укажите допустимую строку подключения при включении Application Insights или задайте для enabled нее значение false.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

DAB запускается, но телеметрия не отображается

Проверьте журналы запуска для следующих сообщений:

Bash

dab start --LogLevel Information

Командная строка

dab start --LogLevel Information

Сообщение об успешном выполнении:

Application Insights telemetry is enabled with connection string from config.

Предупреждения:

Logs won't be sent to Application Insights because an Application Insights connection string is not available in the runtime config.

Application Insights are disabled.

Сообщение об ошибке

Telemetry client is not initialized.

Проверка переменной среды

Bash

echo $app-insights-connection-string

Командная строка

echo %app-insights-connection-string%

Тест с прямой строкой подключения

Временно используйте строку прямого подключения (а не переменную среды) для проверки допустимости строки:

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=..."
}

Если этот тест работает, проблема связана с загрузкой переменной среды.

Связанный контент

• dab add-telemetry Справочник по CLI
• Использование Azure Log Analytics
• Использование OpenTelemetry
• Настройка детализации журнала
• Общие сведения об Application Insights
• Application Insights для ASP.NET Core