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

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

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

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

Prerequisites

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

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

  Note

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

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

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

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

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

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

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

1. Создайте подключение между Application Insights и управлением API.

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

   Important

   В настоящее время на портале Управление API поддерживает только подключения к Application Insights с помощью ключа инструментирования Application Insights. Для повышения безопасности рекомендуется использовать строку подключения Application Insights с управляемым удостоверением API Management. Чтобы настроить строку подключения с учетными данными управляемого удостоверения, используйте REST API или связанные средства, как показано в более позднем разделе этой статьи. Дополнительные сведения см. в статье "Строки подключения" в Application Insights.

   Note

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

2. Включите ведение журнала с помощью Application Insights для вашего API или нескольких API.

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

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

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

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

2. В разделе "Мониторинг" в боковом меню выберите Application Insights.

3. Выберите + Добавить.
   

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

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

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

6. Нажмите кнопку "Создать".

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

   

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

Выполните следующие действия, чтобы использовать REST API, Bicep или шаблон ARM для создания логгера Application Insights для вашего экземпляра API Management. Вы можете настроить средство ведения журнала, использующее строку подключения с учетными данными управляемой идентичности (рекомендуется), или средство ведения журнала, использующее только строку подключения.

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

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

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

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

{
  "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"
    }
  }
}

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

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

{
  "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":"<client-ID>"
    }
  }
}

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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: '<client-ID>'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<client-ID>"
    }
  }
}

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

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

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
    },
  }
}

Включение журналирования с помощью Application Insights для вашего API

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

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

2. Выберите API-интерфейсы> в меню боковой панели.

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

   Tip

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

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

5. Прокрутите вниз до раздела журналов диагностики и установите флажок "Включить ".

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

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

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

   Warning

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

9. Нажмите кнопку "Сохранить".

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

Логгеры для одного API или всех API

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

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

Указание обоих:

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

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

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

Выдача пользовательских метрик

Вы можете отправлять настраиваемые метрики в Application Insights из экземпляра API Management. Управление API выдает пользовательские метрики с помощью политик, таких как emit-metric и llm-emit-token-metric. В следующем разделе в качестве примера используется политика emit-metric.

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

1. Включите пользовательские метрики (превью) с настраиваемыми измерениями в экземпляре Application Insights.

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

2. Добавьте свойство "metrics": true в диагностическую сущность applicationInsights, настроенную в управлении API. В настоящее время необходимо добавить это свойство с помощью REST API для управления API Diagnostic - Create or Update. Рассмотрим пример.

   PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights
   
   {
       [...]
       {
       "properties": {
           "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
           "metrics": true
           [...]
       }
     }
   }
   

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

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

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

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

• Region
• Идентификатор службы
• Имя службы
• Тип службы

Эти ограничения имеют следующие последствия для настройки пользовательских метрик в политике управления API, таких как emit-metric или azure-openai-emit-token-metric:

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

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

• Если вы настраиваете политику в нескольких экземплярах API Management, которые находятся в одном регионе в рамках подписки, все экземпляры могут вносить вклад в региональное ограничение активной временной серии.

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

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

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

• предназначена для использования в качестве системы аудита.
• Подходит для ведения журнала каждого отдельного запроса в API с высокой нагрузкой.

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

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

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

• Заголовки запросов и ответов
• Ведение журнала текста

Troubleshooting

Устранение проблемы потока данных телеметрии из управления API в Application Insights:

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

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

• Введение в Application Insights — наблюдаемость OpenTelemetry
• Как регистрировать события в Центрах событий Azure при использовании службы управления API Azure
• Мониторинг управления API