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

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

Предпосылки

• Существующий файл конфигурации DAB.
• Подписка Azure с разрешениями на создание ресурсов Log Analytics.
• Рабочая область Azure Log Analytics с помощью:
  • Настраиваемая таблица (заканчивается на _CL)
  • Правило сбора данных (DCR)
  • Конечная точка сбора данных (DCE)
• Управляемое удостоверение активировано на узле DAB (служба приложений Azure, приложения контейнеров, виртуальная машина и т. д.).
• CLI инструмента построения API данных. Установка интерфейса командной строки

Настройка ресурсов Azure Log Analytics

Перед настройкой DAB создайте необходимые ресурсы Azure.

Создание рабочей области Log Analytics

Портал Azure

1. Перейдите к порталу Azure>рабочим пространствам Log Analytics.
2. Нажмите кнопку +Создать.
3. Выберите подписку, группу ресурсов и регион.
4. Укажите имя рабочей области.
5. Выберите Просмотреть и создать>Создать.

Azure CLI

az monitor log-analytics workspace create \
  --resource-group my-rg \
  --workspace-name my-workspace \
  --location eastus

Создание настраиваемой таблицы

Пользовательские таблицы для API приема журналов должны заканчиваться _CL.

1. В рабочей области Log Analytics перейдите к таблицам.
2. Выберите и создайте>настраиваемый журнал (на основе DCR).
3. Введите имя таблицы (например, DabLogs_CL).
4. Определите схему со следующими столбцами:
   • Time (дата и время)
   • LogLevel (строка)
   • Message (строка)
   • Component (строка)
   • Identifier (строка)
5. Нажмите кнопку "Создать".

Создание конечной точки сбора данных (DCE)

Портал Azure

1. Перейдите в раздел "Мониторинг>конечных точек сбора данных".
2. Нажмите кнопку +Создать.
3. Выберите подписку, группу ресурсов и регион.
4. Укажите имя (например, my-dce).
5. Выберите Просмотреть и создать>Создать.
6. Скопируйте URL-адрес конечной точки приема журналов (например, https://my-dce.eastus-1.ingest.monitor.azure.com).

Azure CLI

az monitor data-collection endpoint create \
  --name my-dce \
  --resource-group my-rg \
  --location eastus \
  --public-network-access Enabled

Получите конечную точку:

az monitor data-collection endpoint show \
  --name my-dce \
  --resource-group my-rg \
  --query logsIngestion.endpoint -o tsv

Создание правила сбора данных (DCR)

1. Перейдите к разделу "Мониторинг>правил сбора данных".
2. Нажмите кнопку +Создать.
3. Выберите подписку, группу ресурсов, регион.
4. Укажите имя (например, my-dcr).
5. В источниках данных выберите настраиваемые текстовые журналы.
6. Настроить:
   • Конечная точка сбора данных: выберите DCE.
   • Назначение: рабочая область Log Analytics.
   • Таблица: настраиваемая таблица (DabLogs_CL).
7. Выберите Просмотреть и создать>Создать.
8. Скопируйте неизменяемый идентификатор (начинается с dcr-).

Настройка проверки подлинности

DAB использует управляемое удостоверение Azure для проверки подлинности в Log Analytics. Учетные данные не хранятся в конфигурации.

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

Служба приложений

az webapp identity assign \
  --name my-app \
  --resource-group my-rg

Контейнерные приложения

az containerapp identity assign \
  --name my-app \
  --resource-group my-rg \
  --system-assigned

Назначьте разрешения

Предоставьте роль издателя метрик мониторинга управляемому удостоверению в DCR.

# Get Managed Identity principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-app \
  --resource-group my-rg \
  --query principalId -o tsv)

# Get DCR resource ID
DCR_ID=$(az monitor data-collection rule show \
  --name my-dcr \
  --resource-group my-rg \
  --query id -o tsv)

# Assign role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Monitoring Metrics Publisher" \
  --scope $DCR_ID

Это важно

Без этого назначения роли DAB не может отправлять журналы в Log Analytics даже с правильной конфигурацией.

Настройка Log Analytics

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

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "my-dab-instance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Свойства конфигурации

Недвижимость	Description	По умолчанию	Constraints
enabled	Включение или отключение интеграции Log Analytics.	false	Boolean
dab-identifier	Уникальная строка для идентификации записей журнала из этого экземпляра DAB.	DabLogs	Любая строка.
flush-interval-seconds	Как часто (в секундах) журналы отправляются в Log Analytics.	5	Должно быть > 0
auth.custom-table-name	Имя настраиваемой таблицы в рабочей области Log Analytics.	(обязательно)	Должен заканчиваться с _CL
auth.dcr-immutable-id	Неизменяемый идентификатор правила сбора данных.	(обязательно)	Начинается с dcr-
auth.dce-endpoint	URL-адрес конечной точки сбора данных.	(обязательно)	URL-адрес HTTPS

Command-line

Настройка Log Analytics с помощью dab configure.

Включение Log Analytics

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.enabled true

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.enabled true

Установка идентификатора DAB

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

Установка интервала очистки

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

Задайте имя пользовательской таблицы

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

Установка неизменяемого идентификатора DCR

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Настройка конечной точки DCE

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

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

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

Запустить DAB

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

dab start

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

Azure Log Analytics is enabled.

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

Если log Analytics включен, DAB:

1. Выполняет проверку подлинности в Azure с помощью управляемого удостоверения узла.
2. Группирует записи журнала в пакеты на основе flush-interval-seconds.
3. Отправляет журналы в конечную точку сбора данных (DCE).
4. DCE направляет журналы через правило сбора данных (DCR) для преобразования.
5. DCR загружает журналы в вашу настраиваемую таблицу Log Analytics.

Поток данных

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
Log Analytics Logger Provider
    ↓
Managed Identity Authentication
    ↓
Data Collection Endpoint (DCE)
    ↓
Data Collection Rule (DCR)
    ↓
Log Analytics Workspace (Custom Table)

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

Тип телеметрии	Исходный материал	Примеры
Следы	ILogger звонки в DAB	Журналы запуска, журналы выполнения запросов, предупреждения
Errors	Обработка исключений	Ошибки среды выполнения, ошибки конфигурации, ошибки базы данных
Сведения о компоненте	Внутренние компоненты DAB	Какой модуль создал журнал
Идентификатор экземпляра	Конфигурация	dab-identifier значение для фильтрации

Структура журнала

Каждая запись журнала, отправленная в Log Analytics, содержит следующие поля:

Поле	Тип	Description	Example
Time	datetime	Метка времени (ISO 8601)	2026-01-27T14:30:00Z
LogLevel	струна	Степень серьезности логов	Information Warning Error
Message	струна	Журнал сообщений	Request completed successfully
Component	струна	Компонент DAB, создающий журнал	Azure.DataApiBuilder.Service.Startup
Identifier	струна	Значение из dab-identifier конфигурации	my-dab-instance

Замечание

Настраиваемые столбцы таблицы в Log Analytics добавляют суффиксы: _s для строк, _d для двойных _t , для дат и т. д.

Запрос журналов в Log Analytics

1. Откройте рабочую область Log Analytics на портале Azure.

2. Перейдите к журналам и запустите запрос KQL:

   DabLogs_CL
   | where Identifier_s == "my-dab-instance"
   | where LogLevel_s in ("Warning", "Error")
   | where TimeGenerated > ago(1h)
   | project TimeGenerated, LogLevel_s, Message_s, Component_s
   | order by TimeGenerated desc
   

Примеры запросов

Подсчет логов по уровню:

DabLogs_CL
| where TimeGenerated > ago(24h)
| summarize Count=count() by LogLevel_s

Поиск ошибок в определенном компоненте:

DabLogs_CL
| where Component_s contains "SqlQueryExecutor"
| where LogLevel_s == "Error"
| project TimeGenerated, Message_s

Рекомендации по производительности и затратам

Поведение пакетной обработки

DAB пакетирует журналы и отправляет их каждый flush-interval-seconds:

• 5 секунд (по умолчанию) — хороший баланс для большинства сценариев.
• 1–2 секунды: ведение журнала почти в режиме реального времени (более высокие вызовы API, более высокая стоимость).
• 10–60 секунд: сокращены вызовы API, но задержка в записи журналов.

Оптимизация затрат

Цены на Log Analytics основаны на:

1. Поглощение данных: за ГБ загруженного.
2. Хранение данных: за ГБ в месяц после бесплатного пакета.

Сокращение затрат:

• Увеличьте flush-interval-seconds, чтобы обрабатывать больше журналов одновременно.
• Используйте фильтры уровня логов для исключения подробных или избыточных логов. Для получения дополнительной информации см. раздел «Настройка детализации журнала».
• Задайте соответствующее хранение данных в рабочей области Log Analytics.

Пример: фильтрация для уменьшения объема

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Default": "Warning",
        "Microsoft": "Error"
      },
      "azure-log-analytics": {
        "enabled": true,
        "flush-interval-seconds": 30,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Это отправляет только журналы предупреждений и ошибок , значительно уменьшая объем.

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

Хранение данных Log Analytics настраивается для каждой рабочей области:

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

Настройка хранения: рабочая область Log Analytics → использование и предполагаемые затраты → хранения данных.

Подсказка

Для обеспечения соответствия требованиям рекомендуется архивировать старые журналы в службу хранилища Azure для долгосрочного хранения.

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

Журналы не отображаются в Log Analytics

Симптом: DAB запускается успешно, но журналы не отображаются в рабочей области Log Analytics.

Возможные причины:

• Неполная конфигурация: проверьте журналы запуска DAB для ошибок, таких как Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. убедитесь, что все обязательные свойства аутентификации: custom-table-name, dcr-immutable-id, dce-endpoint.

• Управляемое удостоверение не назначено: убедитесь, что управляемое удостоверение включено.az webapp identity show --name my-app --resource-group my-rg Проверьте распределение ролей с помощью az role assignment list --assignee <principal-id> --scope <dcr-id>.

• Неправильная конечная точка DCE или идентификатор DCR: проверьте формат https://<dce-name>.<region>-1.ingest.monitor.azure.comконечной точки DCE. Убедитесь, что неизменяемый идентификатор DCR начинается с dcr-.

• Пользовательская таблица не существует: Пользовательские таблицы должны заканчиваться на _CL. Схема таблицы должна соответствовать структуре журнала.

Ошибка: интервал "flush" должен быть положительным

Причина: flush-interval-seconds задано значение 0 или отрицательное значение.

Решение. Задайте flush-interval-seconds для положительного целого числа (минимум 1).

Журналы DAB отображают, что Azure Log Analytics является отключенным.

Причина: enabled отсутствует или false отсутствует в конфигурации.

Решение. Задайте enabled: true в конфигурации.

Log Analytics и Application Insights

Capability	Application Insights	Log Analytics
Фокус	Мониторинг производительности приложений (APM)	Централизованное агрегирование журналов
Язык запросов	KQL	KQL
Scope	Одно приложение	Приложения, виртуальные машины, контейнеры, ресурсы Azure
Сценарий использования	Производительность, исключения, трассировки	Соответствие, управление, межресурсная корреляция
Authentication	строка подключения	Управляемое удостоверение (через DCR/DCE)

Используйте Application Insights, если вам нужны функции APM, такие как отслеживание запросов, сопоставление зависимостей и профилирование производительности. Используйте Log Analytics, если требуется централизованное ведение журнала в нескольких ресурсах с требованиями к соответствию корпоративным требованиям.

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

• Использование Application Insights
• Использование OpenTelemetry
• Настройка детализации журнала
• Общие сведения о правилах сбора данных
• Управляемые удостоверения для ресурсов Azure