Интеграция управления API Azure в Azure Application Insights
ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API
Вы можете легко интегрировать Azure Application Insights в службу "Управление API Azure". Azure Application Insights — это расширяемая служба для веб-разработчиков, создающих приложения и управляющих ими на нескольких платформах. В руководстве описаны следующие действия:
- Пошаговое руководство по интеграции Application Insights с Управление API.
- Стратегии по уменьшению влияния на производительность экземпляра службы "Управление API".
Примечание.
В рабочей области Управление API владелец рабочей области может независимо интегрировать Application Insights и включить ведение журнала Application Insights для API рабочей области. Общие рекомендации по интеграции рабочей области с Application Insights аналогичны рекомендациям для экземпляра Управление API, однако конфигурация распространяется только на рабочую область. В настоящее время необходимо интегрировать Application Insights в рабочую область, настроив строка подключения (рекомендуется) или ключ инструментирования.
Предупреждение
При использовании локального шлюза мы не гарантируем, что все данные телеметрии будут отправлены в приложение Azure Insights, учитывая, что он использует буферизацию Application Insights в памяти.
Необходимые компоненты
Вам понадобится экземпляр службы "Управление API Azure". Создайте его.
Чтобы использовать Application Insights, создайте экземпляр службы Application Insights. Инструкции по созданию экземпляра с помощью портала Azure см. в статье Ресурсы рабочей области Application Insights.
Примечание.
Ресурс Application Insights может находиться в другой подписке или даже в другом клиенте, отличном от ресурса Управления API.
Если вы планируете настроить учетные данные управляемого удостоверения для использования с Application Insights, выполните следующие действия.
Включите управляемое удостоверение, назначаемое системой или назначаемое пользователем, для Управление API.
- Если вы включаете управляемое удостоверение, назначаемое пользователем, запишите идентификатор клиента удостоверения.
Назначьте удостоверение роли издателя метрик мониторинга, заданное ресурсу Application Insights. Для назначения этой роли можно использовать портал Azure или другие инструменты Azure.
Обзор сценария
Ниже приведены шаги высокого уровня для этого сценария.
Сначала создайте подключение между Application Insights и Управление API
Вы можете создать подключение между Application Insights и Управление API с помощью портал Azure, REST API или связанных средств Azure. Управление API настраивает ресурс средства ведения журнала для подключения.
Внимание
В настоящее время на портале Управление API поддерживает только подключения к Application Insights с помощью ключа инструментирования Application Insights. Для повышения безопасности рекомендуется использовать строка подключения Application Insights с управляемым удостоверением Управление API. Чтобы настроить строка подключения с учетными данными управляемого удостоверения, используйте REST API или связанные средства, как показано в следующем разделе этой статьи. Дополнительные сведения о строка подключения Application Insights.
Примечание.
Если ресурс Application Insights находится в другом клиенте, необходимо создать средство ведения журнала с помощью REST API или связанных средств, как показано в следующем разделе этой статьи.
Во-вторых, включите ведение журнала Application Insights для API или API.
В этой статье описано, как включить ведение журнала Application Insights для API с помощью портал Azure. Управление API настраивает диагностический ресурс для API.
Создание подключения с помощью портал Azure
Выполните следующие действия, чтобы использовать портал Azure для создания подключения между Application Insights и Управление API.
Примечание.
По возможности корпорация Майкрософт рекомендует использовать строка подключения с учетными данными управляемого удостоверения для повышения безопасности. Чтобы настроить эти учетные данные, используйте REST API или связанные средства, как показано в следующем разделе этой статьи.
На портале Azure перейдите к экземпляру службы управления API Azure.
Выберите Application Insights в меню слева.
Выберите Добавить.
Выберите ранее созданный экземпляр Application Insights и укажите краткое описание.
Чтобы включить отслеживание доступности экземпляра управления API в Application Insights, установите флажок Добавить монитор доступности.
- Этот параметр регулярно проверяет, отвечает ли конечная точка шлюза Управления API.
- Результаты отображаются на панели Доступность в экземпляре Application Insights.
Нажмите кнопку создания.
Убедитесь, что в списке появится новый средство ведения журнала Application Insights.
Примечание.
За кулисами в экземпляре Управление API создается сущность средства ведения журнала, содержащая ключ инструментирования экземпляра Application Insights.
Совет
Если необходимо обновить ключ инструментирования, настроенный в средстве ведения журнала Application Insights, выберите строку средства ведения журнала в списке (а не имя средства ведения журнала). Введите ключ инструментирования и нажмите кнопку "Сохранить".
Создание подключения с помощью шаблона REST API, Bicep или ARM
Выполните следующие действия, чтобы использовать REST API, Bicep или шаблон ARM для создания средства ведения журнала Application Insights для вашего экземпляра Управление API. Вы можете настроить средство ведения журнала, использующее строка подключения с учетными данными управляемого удостоверения (рекомендуется), или средство ведения журнала, использующее только строка подключения.
Средство ведения журнала с помощью строка подключения с учетными данными управляемого удостоверения (рекомендуется)
Ознакомьтесь с предварительными условиями использования управляемого удостоверения Управление API.
Строка подключения Application Insights отображается в разделе "Обзор" ресурса Application Insights.
Строка подключения с управляемым удостоверением, назначаемого системой
Используйте средство ведения журнала Управление API — создание или обновление REST API со следующим текстом запроса.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with system-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"SystemAssigned"
}
}
}
Строка подключения с назначаемого пользователем управляемого удостоверения
Используйте средство ведения журнала Управление API — создание или обновление REST API со следующим текстом запроса.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with user-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"<ClientID>"
}
}
}
Средство ведения журнала только с учетными данными строка подключения
Строка подключения Application Insights отображается в разделе "Обзор" ресурса Application Insights.
Используйте средство ведения журнала Управление API — создание или обновление REST API со следующим текстом запроса.
Если вы настраиваете средство ведения журнала для рабочей области, используйте средство ведения журнала рабочей области — создание или обновление REST API.
{
"properties": {
"loggerType": "applicationInsights",
"description": "Application Insights logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
Включение ведения Application Insights для вашего API
Выполните следующие действия, чтобы включить ведение журнала Application Insights для API. Вы также можете включить ведение журнала Application Insights для всех API.
На портале Azure перейдите к экземпляру службы управления API Azure.
Выберите API в меню слева.
Выберите свой API, в данном случае Demo Conference API. Если выполнена соответствующая настройка, выберите версию.
Совет
Чтобы включить ведение журнала для всех API, выберите все API.
Перейдите на вкладку Параметры на верхней панели.
Прокрутите содержимое вкладки вниз до раздела Журналы диагностики.
Установите флажок Включить.
Выберите подключенное средство ведения журнала в раскрывающемся списке Назначение.
Укажите значение 100 в поле Выборка (%) и установите флажок Всегда записывать ошибки в журнал.
Остальные параметры не меняйте. Дополнительные сведения о параметрах см . в справочнике по параметрам журналов диагностики.
Предупреждение
Переопределение значения по умолчанию 0 для параметра Количество байтов полезных данных для регистрации может значительно снизить производительность API.
Выберите Сохранить.
Фактически сущность Диагностика с именем
applicationinsightsсоздается на уровне API.
Примечание.
Запросы успешно выполняются после того, как Управление API отправляет клиенту весь ответ.
Средства ведения журнала для одного API или всех API
Вы можете указать средства ведения журнала на разных уровнях:
- Один средство ведения журнала API
- Средство ведения журнала для всех API
Указать оба варианта:
- По умолчанию один средство ведения журнала API (более подробный уровень) переопределяет один для всех API.
- Если средства ведения журнала, настроенные на двух уровнях, отличаются, и вам нужны оба средства ведения журнала для получения телеметрии (мультиплексирование), обратитесь к служба поддержки Майкрософт. Обратите внимание, что мультиплексирование не поддерживается, если вы используете один и тот же средство ведения журнала (назначение Application Insights) на уровне "Все API" и один уровень API. Чтобы мультиплексирование работало правильно, необходимо настроить различные средства ведения журнала на уровне "Все API" и отдельный уровень API и запросить помощь от поддержки Майкрософт, чтобы включить мультиплексирование для службы.
Какие данные добавляются в Application Insights
Application Insights получает следующие данные:
| Элемент телеметрии | Description |
|---|---|
| Запросить | Для каждого входящего запроса:
|
| Зависимость | Для каждого запроса, пересылаемого в серверную службу:
|
| Исключение | Для каждого неудачного запроса:
|
| Трассировка | Если вы настроили политику трассировки. Параметр severity в политике trace должен быть больше или равен параметру verbosity в журнале Application Insights. |
Примечание.
Сведения о максимальном размере и количестве метрик и событий для каждого экземпляра Application Insights см. в разделе Границы Application Insights.
Создание пользовательских метрик
Вы можете отправлять пользовательские метрики в Application Insights из экземпляра Управление API. Управление API выдает пользовательские метрики с помощью политик, таких как emit-metric и azure-openai-emit-token-metric. В следующем разделе в качестве примера используется emit-metric политика.
Примечание.
Пользовательские метрики — это предварительная версия функции Azure Monitor, которая имеет ограничения.
Чтобы вывести пользовательские метрики, выполните следующие действия по настройке.
Включите пользовательские метрики (предварительная версия) с пользовательскими измерениями в экземпляре Application Insights.
- Перейдите к экземпляру Application Insights на портале.
- В меню слева выберите "Использование" и "Предполагаемые затраты".
- Выберите пользовательские метрики (предварительная версия)>С измерениями.
- Нажмите ОК.
Добавьте свойство в
"metrics": trueapplicationInsightsсущность диагностики, настроенную в Управление API. В настоящее время необходимо добавить это свойство с помощью диагностики Управление API — создания или обновления REST API. Например:PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights { [...] { "properties": { "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}", "metrics": true [...] } }Убедитесь, что средство ведения журнала Application Insights настроено в области, которую вы планируете выдавать пользовательские метрики (все API или один API). Дополнительные сведения см. в статье "Включение ведения журнала Application Insights для API" ранее в этой статье.
emit-metricНастройте политику в области, в которой настроено ведение журнала Application Insights (все API или один API) и включена для пользовательских метрик. Дополнительные сведения о политике см. в справочнике по политикеemit-metric.
Ограничения для пользовательских метрик
Azure Monitor накладывает ограничения на использование пользовательских метрик, которые могут повлиять на возможность отправки метрик из Управление API. Например, Azure Monitor в настоящее время задает ограничение в 10 ключей измерений на метрики и ограничение в 50 000 активных временных рядов в каждом регионе в подписке (в течение 12 часов).
Эти ограничения имеют следующие последствия для настройки пользовательских метрик в политике Управление API, напримерemit-metric:azure-openai-emit-token-metric
Можно настроить не более 10 пользовательских измерений для каждой политики.
Число активных временных рядов, создаваемых политикой в течение 12 часов, является продуктом числа уникальных значений каждого настроенного измерения в течение периода. Например, если в политике настроены три пользовательских измерения, а каждое измерение имеет 10 возможных значений в течение периода, политика будет способствовать 1000 (10 x 10 x 10) активных временных рядов.
Если вы настраиваете политику в нескольких экземплярах Управление API, которые находятся в одном регионе в подписке, все экземпляры могут способствовать ограничению активных временных рядов региона.
Дополнительные сведения об ограничениях проектирования и рекомендациях по пользовательским метрикам в Azure Monitor.
Влияние выборок журналов на производительность
Предупреждение
Запись всех событий может привести к серьезному снижению производительности в зависимости от частоты входящих запросов.
По результатам внутренних нагрузочных тестов включение этой функции ведения журнала приводит к снижению пропускной способности на 40–50 %, если частота запросов превышает 1000 запросов в секунду. Служба Application Insights применяет статистический анализ для оценки производительности приложения. Для чего она не предназначена:
- не предназначена к использованию в качестве системы аудита;
- не подходит для ведения журнала каждого отдельного запроса для API с большими объемами.
Количество запросов, записываемых в журналы, можно изменить с помощью параметра Выборка. Значение 100 % показывает, что регистрируются все запросы, а 0 % — что запросы не регистрируются.
Параметр Выборка позволяет сократить объем данных телеметрии, избежать существенного снижения производительности, при этом сохраняя преимущества ведения журналов.
Чтобы повысить производительность, пропустите следующее:
- заголовки запросов и ответов;
- регистрацию текста запросов.
Видео
Устранение неполадок
Устранение проблемы потока данных телеметрии из Управление API в Application Insights:
- Проверьте, существует ли связанный ресурс Azure Monitor Приватный канал Scope (AMPLS) в виртуальной сети, где подключен Управление API ресурс. Ресурсы AMPLS имеют глобальную область в подписках и отвечают за управление запросами данных и приемом всех ресурсов Azure Monitor. Возможно, AMPLS настроен с режимом доступа только для частного доступа, специально для приема данных. В таких случаях включите ресурс Application Insights и связанный с ним ресурс Log Analytics в AMPLS. После добавления этого Управление API данные будут успешно приняты в ресурс Application Insights, разрешая проблему передачи данных телеметрии.
Связанный контент
- Дополнительные сведения об Azure Application Insights.
- См. раздел ведение журналов с помощью Центров событий Azure.
- Сведения о визуализации данных из Application Insights с помощью Управляемой Grafana Azure