Интеграция управления API Azure в Azure Application Insights

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Вы можете легко интегрировать Azure Application Insights в службу "Управление API Azure". Azure Application Insights — это расширяемая служба для веб-разработчиков, создающих приложения и управляющих ими на нескольких платформах. В руководстве описаны следующие действия:

  • Ознакомьтесь с интеграцией приложений Аналитика с Управление API.
  • Стратегии по уменьшению влияния на производительность экземпляра службы "Управление API".

Необходимые компоненты

  • Вам понадобится экземпляр службы "Управление API Azure". Создайте его.

  • Чтобы использовать Application Insights, создайте экземпляр службы Application Insights. Инструкции по созданию экземпляра с помощью портала Azure см. в статье Ресурсы рабочей области Application Insights.

    Примечание.

    Ресурс Application Insights может находиться в другой подписке или даже в другом клиенте, отличном от ресурса Управления API.

  • Если вы планируете настроить управляемое удостоверение для Управление API использования с приложением Аналитика, выполните следующие действия.

    1. Включите назначаемое системой или назначаемое пользователем управляемое удостоверение для Управления API в экземпляре Управления API.

      • Если вы включаете управляемое удостоверение, назначаемое пользователем, запишите идентификатор клиента удостоверения.

    2. Назначьте удостоверение роли издателя метрик мониторинга, область в ресурс приложения Аналитика. Для назначения этой роли можно использовать портал Azure или другие инструменты Azure.

Обзор сценария

Ниже приведены шаги высокого уровня для этого сценария.

  1. Сначала необходимо создать подключение между приложением Аналитика и Управление API

    Вы можете создать подключение между приложением Аналитика и Управление API с помощью портал Azure, REST API или связанных средств Azure. Управление API настраивает ресурс средства ведения журнала для подключения.

    Примечание.

    Если ресурс приложения Аналитика находится в другом клиенте, необходимо создать средство ведения журнала с помощью REST API.

    Внимание

    В настоящее время на портале Управление API поддерживает только подключения к Приложению Аналитика с помощью ключа инструментирования приложения Аналитика. Чтобы использовать приложение Аналитика строка подключения или управляемое удостоверение Управление API, используйте REST API, Bicep или шаблон ARM для создания средства ведения журнала. Дополнительные сведения о приложениях Аналитика строка подключения.

  2. Во-вторых, вы включите ведение журнала приложений Аналитика для API или API.

    В этой статье описано, как включить ведение журнала приложений Аналитика для API с помощью портал Azure. Управление API настраивает диагностический ресурс для API.

Создание подключения с помощью портал Azure

Выполните следующие действия, чтобы использовать портал Azure для создания соединения между приложением Аналитика и Управление API.

  1. На портале Azure перейдите к экземпляру службы управления API Azure.

  2. Выберите Application Insights в меню слева.

  3. Выберите Добавить.
    Снимок экрана, на котором показано, куда следует добавить новое подключение

  4. Выберите ранее созданный экземпляр Application Insights и укажите краткое описание.

  5. Чтобы включить отслеживание доступности экземпляра управления API в Application Insights, установите флажок Добавить монитор доступности.

    • Этот параметр регулярно проверяет, отвечает ли конечная точка шлюза Управления API.
    • Результаты отображаются на панели Доступность в экземпляре Application Insights.

  6. Нажмите кнопку создания.

  7. Убедитесь, что в списке появится новый средство ведения журнала приложений Аналитика.

    Снимок экрана, на котором показано, где можно просмотреть только что созданное приложение Аналитика ведения журнала.

Примечание.

За кулисами в экземпляре Управление API создается сущность средства ведения журнала, содержащая ключ инструментирования экземпляра Приложения Аналитика.

Совет

Если необходимо обновить ключ инструментирования, настроенный в средстве ведения журнала приложений Аналитика, выберите строку средства ведения журнала в списке (а не имя средства ведения журнала). Введите ключ инструментирования и нажмите кнопку "Сохранить".

Создание подключения с помощью шаблона REST API, Bicep или ARM

Выполните следующие действия, чтобы использовать REST API, Bicep или шаблон ARM для создания соединения между приложением Аналитика и Управление API. Вы можете настроить средство ведения журнала, использующее строка подключения, назначаемое системой управляемое удостоверение или управляемое удостоверение, назначаемое пользователем.

Средство ведения журнала с помощью учетных данных строка подключения

Приложение Аналитика строка подключения отображается в разделе "Обзор" ресурса Аналитика приложения.

Используйте REST API Управление API со следующим текстом запроса.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Средство ведения журнала с учетными данными управляемого удостоверения, назначаемого системой

Ознакомьтесь с предварительными условиями использования управляемого удостоверения Управление API.

Используйте REST API Управление API со следующим текстом запроса.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new 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 Управление API со следующим текстом запроса.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Включение ведения Application Insights для вашего API

Выполните следующие действия, чтобы включить ведение журнала приложений Аналитика для API. Вы также можете включить ведение журнала приложений Аналитика для всех API.

  1. На портале Azure перейдите к экземпляру службы управления API Azure.

  2. Выберите API в меню слева.

  3. Выберите свой API, в данном случае Demo Conference API. Если выполнена соответствующая настройка, выберите версию.

    Совет

    Чтобы включить ведение журнала для всех API, выберите все API.

  4. Перейдите на вкладку Параметры на верхней панели.

  5. Прокрутите содержимое вкладки вниз до раздела Журналы диагностики.
    Средство ведения журнала App Insights

  6. Установите флажок Включить.

  7. Выберите подключенное средство ведения журнала в раскрывающемся списке Назначение.

  8. Укажите значение 100 в поле Выборка (%) и установите флажок Всегда записывать ошибки в журнал.

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

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

    Переопределение значения по умолчанию 0 для параметра Количество байтов полезных данных для регистрации может значительно снизить производительность API.

  10. Выберите Сохранить.

  11. Фактически сущность Диагностика с именем applicationinsights создается на уровне API.

Примечание.

Запросы успешно выполняются после того, как Управление API отправляет клиенту весь ответ.

Средства ведения журнала для одного API или всех API

Вы можете указать средства ведения журнала на разных уровнях:

  • Один средство ведения журнала API
  • Средство ведения журнала для всех API

Указать оба варианта:

  • По умолчанию один средство ведения журнала API (более подробный уровень) переопределяет один для всех API.
  • Если средства ведения журнала, настроенные на двух уровнях, отличаются, и вам нужны оба средства ведения журнала для получения телеметрии (мультиплексирование), обратитесь к служба поддержки Майкрософт. Обратите внимание, что мультиплексирование не поддерживается, если вы используете один и тот же средство ведения журнала (приложение Аналитика назначение) на уровне "Все API" и один уровень API. Чтобы мультиплексирование работало правильно, необходимо настроить различные средства ведения журнала на уровне "Все API" и отдельный уровень API и запросить помощь от поддержки Майкрософт, чтобы включить мультиплексирование для службы.

Какие данные добавляются в Application Insights

Application Insights получает следующие данные:

Элемент телеметрии Description
Запросить Для каждого входящего запроса:
  • запрос к интерфейсу
  • ответ интерфейса
Зависимость Для каждого запроса, пересылаемого в серверную службу:
  • запрос к серверу
  • ответ сервера
Исключение Для каждого неудачного запроса:
  • сбой из-за закрытия подключения клиента;
  • активация раздела on-error из политик API;
  • содержит ответный код состояния HTTP, соответствующий 4xx или 5xx.
Трассировка Если вы настроили политику трассировки.
Параметр severity в политике trace должен быть больше или равен параметру verbosity в журнале Application Insights.

Примечание.

Сведения о максимальном размере и количестве метрик и событий для каждого экземпляра Application Insights см. в разделе Границы Application Insights.

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

Вы можете выдавать пользовательские метрики приложению Аналитика из экземпляра Управление API. Управление API выдает пользовательские метрики с помощью политики выдачи метрик.

Примечание.

Пользовательские метрики — это предварительная версия функции Azure Monitor, которая имеет ограничения.

Чтобы вывести пользовательские метрики, выполните следующие действия по настройке.

  1. Включите пользовательские метрики (предварительная версия) с пользовательскими измерениями в экземпляре Приложения Аналитика.

    1. Перейдите к экземпляру приложения Аналитика на портале.
    2. В меню слева выберите "Использование" и "Предполагаемые затраты".
    3. Выберите пользовательские метрики (предварительная версия)>С измерениями.
    4. Нажмите ОК.

  2. Добавьте свойство в "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
        [...]
    }
}

  3. Убедитесь, что средство ведения журнала приложений Аналитика настроено на область, который планируется выдавать пользовательские метрики (все API или один API). Дополнительные сведения см. в разделе "Включение ведения журнала приложений Аналитика для API" ранее в этой статье.

  4. emit-metric Настройте политику в область, где настроено ведение журнала приложений Аналитика (все API или один API) и включено для пользовательских метрик. Дополнительные сведения о политике см. в справочнике по политике emit-metric .

Ограничения для пользовательских метрик

Azure Monitor накладывает ограничения на использование пользовательских метрик, которые могут повлиять на возможность отправки метрик из Управление API. Например, Azure Monitor в настоящее время задает ограничение в 10 ключей измерений на метрики и ограничение в 50 000 активных временных рядов в каждом регионе в подписке (в течение 12 часов).

Эти ограничения имеют следующие последствия для настройки пользовательских метрик в Управление API:

  • Можно настроить не более 10 пользовательских измерений для emit-metric каждой политики.

  • Число активных временных рядов, создаваемых emit-metric политикой в течение 12 часов, является продуктом числа уникальных значений каждого настроенного измерения в течение периода. Например, если в политике настроены три пользовательских измерения, а каждое измерение имеет 10 возможных значений в течение периода, emit-metric политика будет способствовать 1000 (10 x 10 x 10) активных временных рядов.

  • Если настроить emit-metric политику в нескольких экземплярах Управление API, которые находятся в одном регионе в подписке, все экземпляры могут способствовать ограничению активных временных рядов региона.

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

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

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

По результатам внутренних нагрузочных тестов включение этой функции ведения журнала приводит к снижению пропускной способности на 40–50 %, если частота запросов превышает 1000 запросов в секунду. Служба Application Insights применяет статистический анализ для оценки производительности приложения. Для чего она не предназначена:

  • не предназначена к использованию в качестве системы аудита;
  • не подходит для ведения журнала каждого отдельного запроса для API с большими объемами.

Количество запросов, записываемых в журналы, можно изменить с помощью параметра Выборка. Значение 100 % показывает, что регистрируются все запросы, а 0 % — что запросы не регистрируются.

Параметр Выборка позволяет сократить объем данных телеметрии, избежать существенного снижения производительности, при этом сохраняя преимущества ведения журналов.

Чтобы повысить производительность, пропустите следующее:

  • заголовки запросов и ответов;
  • регистрацию текста запросов.

Видео

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

Устранение проблемы потока данных телеметрии из Управление API в приложение Аналитика:

  • Проверьте, существует ли связанный ресурс Azure Monitor Приватный канал Scope (AMPLS) в виртуальной сети, где подключен Управление API ресурс. Ресурсы AMPLS имеют глобальную область между подписками и отвечают за управление запросами данных и приемом всех ресурсов Azure Monitor. Возможно, AMPLS настроен с режимом доступа только для частного доступа, специально для приема данных. В таких случаях включите ресурс Application Аналитика и связанный с ним ресурс Log Analytics в AMPLS. После добавления этого Управление API данные будут успешно приняты в ресурс Application Аналитика, разрешая проблему передачи данных телеметрии.

Следующие шаги