如何将 Azure API 管理与 Azure Application Insights 集成

项目
10/09/2023

可以轻松地将 Azure Application Insights 与 Azure API 管理集成。 Azure Application Insights 是一项可扩展的服务，可让 Web 开发人员在多个平台上生成和管理应用。在本指南中，你将：

完成 Application Insights 到 API 管理的集成演练。
了解可用于降低对 API 管理服务实例的性能影响的策略。

先决条件

需要一个 Azure API 管理实例。首先创建一个实例。
若要使用 Application Insights，请创建 Application Insights 服务实例。若要使用 Azure 门户创建实例，请参阅基于工作区的 Application Insights 资源。

注意

Application Insights 资源可以位于不同的订阅中，甚至可以位于不同于 API 管理资源的租户。
如果计划配置托管标识，以便 API 管理将该标识与 Application Insights 搭配使用，则需要完成以下步骤：
1. 在 API 管理实例中为 API 管理启用系统分配的托管标识或用户分配的托管标识。
  - 如果启用用户分配的托管标识，请记下该标识的“客户端 ID”。
2. 为标识分配监视指标发布者角色，范围限定为 Application Insights 资源。若要分配角色，请使用 Azure 门户或其他 Azure 工具。

方案概述

下面是此方案的高级步骤。

首先，在 Application Insights 和 API 管理之间创建连接

可以使用 Azure 门户、REST API 或相关的 Azure 工具在 Application Insights 与 API 管理之间建立连接。 API 管理为连接配置记录器资源。

注意

如果 Application Insights 资源位于不同的租户中，则你必须使用 REST API 创建记录器。

重要

目前，在门户中，API 管理仅支持使用 Application Insights 检测密钥连接到 Application Insights。若要使用 Application Insights 连接字符串或 API 管理托管标识，请使用 REST API、Bicep 或 ARM 模板创建记录器。详细了解 Application Insights 连接字符串。
然后，为 API 启用 Application Insights 日志记录。

在本文中，将使用 Azure 门户为 API 启用 Application Insights 日志记录。 API 管理会为 API 配置诊断资源。

使用 Azure 门户创建连接

按照以下步骤使用 Azure 门户在 Application Insights 和 API 管理之间创建连接。

在 Azure 门户中导航到自己的 Azure API 管理服务实例。
在左侧菜单中选择“Application Insights”。
选择“+ 添加”。
选择前面创建的 Application Insights 实例并提供一个简短的说明。
如要启用 Application Insights 中的 API 管理实例的可用性监视，请选择“添加可用性监视”复选框。
- 此设置会定期验证 API 管理网关终结点是否正在响应。
- 结果显示在 Application Insights 实例的“可用性”窗格中。
选择“创建”。
检查新 Application Insights 记录器现在是否显示在列表中。

注意

在后台，将在 API 管理实例中创建一个记录器实体，其中包含 Application Insights 实例的检测密钥。

提示

如果需要更新 Application Insights 记录器中配置的检测密钥，请在列表中选择记录器行（而不是记录器的名称）。输入检测密钥，然后选择“保存”。

使用 REST API、Bicep 或 ARM 模板创建连接

按照以下步骤使用 REST API、Bicep 或 ARM 模板在 Application Insights 和 API 管理之间创建连接。可以配置使用连接字符串、系统分配的托管标识或用户分配的托管标识的记录器。

包含连接字符串凭据的记录器

Application Insights 连接字符串显示在 Application Insights 资源的“概述”部分。

将 API 管理 REST 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/;..."    
    }
  }
}

在 Bicep 模板中包含类似于以下内容的代码片段。

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

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

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

包含系统分配的托管标识凭据的记录器

请参阅先决条件，了解如何使用 API 管理托管标识。

将 API 管理 REST 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"
    }
  }
}

在 Bicep 模板中包含类似于以下内容的代码片段。

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

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

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

包含用户分配的托管标识凭据的记录器

请参阅先决条件，了解如何使用 API 管理托管标识。

将 API 管理 REST 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>"
    }
  }
}

在 Bicep 模板中包含类似于以下内容的代码片段。

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

在 Azure 资源管理器模板中包含类似于以下内容的 JSON 代码片段。

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

为 API 启用 Application Insights 日志记录

使用以下步骤为 API 启用 Application Insights 日志记录。还可以为所有 API 启用 Application Insights 日志记录。

在 Azure 门户中导航到自己的 Azure API 管理服务实例。
在左侧菜单中选择“API” 。
单击你的 API（在本例中为“演示会议 API”）。选择一个版本（如果已配置）。

提示

若要为所有 API 启用日志记录，请选择所有 API。
从顶部栏转到“设置”选项卡。
向下滚动到“诊断日志”部分。
选中“启用”框。
在“目标”下拉列表中选择附加的记录器。
输入 100 作为“采样率”，并选中“始终记录错误”复选框。
将其余设置保留不变。有关设置的详细信息，请参阅诊断日志设置参考。

警告

替代“要记录的有效负载字节数”的默认值 0 可能会显著降低 API 的性能。
选择“保存”。
在后台，将在 API 级别创建一个名为 applicationinsights 的 Diagnostic 实体。

注意

一旦 API 管理将整个响应发送到客户端，请求将成功。

单个 API 或所有 API 的记录器

可以在不同的级别指定记录器：

单个 API 的记录器
所有 API 的记录器

同时指定：

默认情况下，单个 API 记录器（粒度级更高）替代所有 API 的记录器。
如果在两个级别配置的记录器不同，而你需要两个记录器来接收遥测（多路复用），请联系 Microsoft 支持部门。请注意，如果在“所有 API”级别和单个 API 级别使用相同的记录器（Application Insights 目标），则不支持多路复用。若要使多路复用正常工作，必须在“所有 API”和单个 API 级别配置不同的记录器，并请求 Microsoft 支持人员的帮助，以便为服务启用多路复用。

将哪些数据添加到 Application Insights

Application Insights 接收：

遥测项	说明
请求	对于每个传入请求：前端请求前端响应
依赖项	对于每个转发到后端服务的请求：后端请求后端响应
Exception	对于每个失败的请求：由于客户端连接关闭而失败触发了 API 策略的 on-error 节具有匹配 4xx 或 5xx 的响应 HTTP 状态代码
Trace	如果配置跟踪策略。 `trace` 策略中的设置 `severity` 必须等于或大于 Application Insights 日志记录中的 `verbosity` 设置。

注意

有关每个 Application Insights 实例的指标和事件的最大大小与数量的信息，请参阅 Application Insights 限制。

性能影响和日志采样

警告

记录所有事件可能会产生严重的性能影响，具体取决于传入请求的速率。

根据内部负载测试，当请求速率超过每秒 1,000 个请求时，启用日志记录功能会导致吞吐量下降 40%-50%。 Application Insights 旨在使用统计分析来评估应用程序性能。而不是：

旨在成为审核系统。
适用于记录大量 API 的各个请求。

可以通过调整“采样率”设置来操控所记录的请求数。值 100% 表示记录所有请求，0% 表示不进行日志记录。

“采样率”有助于减少遥测量，可有效防止性能出现明显下降，同时仍可保持日志记录的优势。

若要改进性能问题，请跳过：

请求和响应头。
正文日志记录。

故障排除

解决从 API Management 到 Application Insights 的遥测数据流问题：

调查连接 API Management 资源的 VNet 中是否存在链接的 Azure Monitor 专用链接范围 (AMPLS) 资源。 AMPLS 资源具有跨订阅的全局范围，并负责管理所有 Azure Monitor 资源的数据查询和引入。可能已为 AMPLS 配置了专用于数据引入的专用访问模式。在这种情况下，请将 Application Insights 资源及其关联的 Log Analytics 资源包含在 AMPLS 中。添加此内容后，API Management 数据将成功引入 Application Insights 资源，从而解决遥测数据传输问题。

后续步骤

详细了解 Azure Application Insights。
考虑使用 Azure 事件中心进行日志记录。

如何将 Azure API 管理与 Azure Application Insights 集成

先决条件

方案概述

使用 Azure 门户创建连接

使用 REST API、Bicep 或 ARM 模板创建连接

包含连接字符串凭据的记录器

包含系统分配的托管标识凭据的记录器

包含用户分配的托管标识凭据的记录器

为 API 启用 Application Insights 日志记录

单个 API 或所有 API 的记录器

将哪些数据添加到 Application Insights

性能影响和日志采样

故障排除

后续步骤

其他资源