你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
10/02/2024

适用于：所有 API 管理层级

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

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

注意

在 API 管理工作区中，工作区所有者可以独立集成 Application Insights，并为工作区的 API 启用 Application Insights 日志记录。将工作区与 Application Insights 集成的一般指导与针对 API 管理实例的指导类似；但是，配置范围限定于工作区。目前，必须通过配置连接字符串（推荐）或检测密钥将 Application Insights 集成到工作区中。

警告

使用自托管网关时，我们不能保证所有遥测数据都会被推送到 Azure Application Insights，因为它依赖于 Application Insights 的内存中缓冲。

先决条件

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

注意

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

方案概述

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

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

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

重要

目前，在门户中，API 管理仅支持使用 Application Insights 检测密钥连接到 Application Insights。为了增强安全性，建议使用具有 API 管理托管标识的 Application Insights 连接字符串。若要使用托管身份凭据配置连接字符串，请使用 REST API 或相关工具，如本文后面部分所示。详细了解 Application Insights 连接字符串。

注意

如果 Application Insights 资源位于其他租户中，则必须使用 REST API 或相关工具创建记录器，如本文后面部分所示。
然后，为 API 启用 Application Insights 日志记录。

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

使用 Azure 门户创建连接

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

注意

在可能的情况下，Microsoft 建议使用带有托管标识凭据的连接字符串来增强安全性。若要配置这些凭据，请使用 REST 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 模板为 API 管理实例创建 Application Insights 记录器。可以配置一个使用具有托管标识凭据的连接字符串的记录器（推荐），或者一个仅使用连接字符串的记录器。

使用具有托管标识凭据的连接字符串的记录器（推荐）

请参阅先决条件，了解如何使用 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"
    }
  }
}

在 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 管理记录器 - 创建或更新 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>"
    }
  }
}

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

仅具有连接字符串凭据的记录器

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/;..."    
    }
  }
}

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

如果要为工作区配置记录器，请改为创建 Microsoft.ApiManagement/service.workspace/loggers@2023-09-01-preview 资源。

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 代码片段。

如果要为工作区配置记录器，请创建 Microsoft.ApiManagement/service.workspace/loggers 资源并将 apiVersion 设置为 2023-09-01-preview。

{
  "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 启用 Application Insights 日志记录

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

在 Azure 门户中导航到自己的 Azure API 管理服务实例。
从左侧菜单中选择“API”>“API”。
选择一个 API，例如 Swagger Petstore。选择一个版本（如果已配置）。

提示

若要为所有 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 限制。

发出自定义指标

可以从 API 管理实例向 Application Insights 发出自定义指标。 API 管理使用 emit-metric 和 azure-openai-emit-token-metric 等策略发出自定义指标。以下部分使用 emit-metric 策略作为示例。

注意

自定义指标是 Azure Monitor 的预览功能，并受到限制。

若要发出自定义指标，请执行以下配置步骤。

在 Application Insights 实例中使用自定义维度启用自定义指标（预览）。
1. 在门户中导航到 Application Insights 实例。
2. 在左侧菜单中，选择使用情况和预估成本。
3. 选择自定义指标（预览）>带维度。
4. 选择“确定”。

将 "metrics": true 属性添加到在 API 管理中配置的 applicationInsights 诊断实体。目前必须使用 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
        [...]
    }
}

确保在要发出自定义指标（所有 API 或单个 API）的范围内配置 Application Insights 记录器。有关详细信息，请参阅本文前面的为 API 启用 Application Insights 日志记录。
在配置 Application Insights 日志记录（所有 API 或单个 API）并启用自定义指标的范围内配置 emit-metric 策略。有关策略详细信息，请参阅 emit-metric 策略参考。

自定义指标的限制

Azure Monitor 对可能影响从 API 管理发出指标能力的自定义指标实施使用限制。例如，Azure Monitor 当前为每个指标设置 10 个维度键的限制，并为订阅中每个区域设置 50,000 个总活动时序数的限制（期限为 12 小时）。

这些限制对在 API 管理策略（例如 emit-metric 或 azure-openai-emit-token-metric）中配置自定义指标具有以下影响：

每个策略最多可以配置 10 个自定义维度。
策略在 12 小时期限内生成的活动时序数是该期限内每个已配置维度的唯一值数的乘积。例如，如果在策略中配置了三个自定义维度，并且每个维度在该期限内有 10 个可能的值，则策略将生成 1,000 (10 x 10 x 10) 个活动时序。
如果在订阅的同一区域中的多个 API 管理实例中配置策略，则所有实例都可能导致区域活动时序限制。

详细了解 Azure Monitor 中自定义指标的设计限制和注意事项。

性能影响和日志采样

警告

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

根据内部负载测试，当请求速率超过每秒 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 托管 Grafana 可视化 Application Insights 中的数据

通过

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

先决条件

方案概述

使用 Azure 门户创建连接

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

使用具有托管标识凭据的连接字符串的记录器（推荐）

具有系统分配的托管标识的连接字符串

具有用户分配的托管标识的连接字符串

仅具有连接字符串凭据的记录器

为 API 启用 Application Insights 日志记录

单个 API 或所有 API 的记录器

将哪些数据添加到 Application Insights

发出自定义指标

自定义指标的限制

性能影响和日志采样

视频

故障排除

反馈

其他资源

通过

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

先决条件

方案概述

使用 Azure 门户创建连接

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

使用具有托管标识凭据的连接字符串的记录器（推荐）

具有系统分配的托管标识的连接字符串

具有用户分配的托管标识的连接字符串

仅具有连接字符串凭据的记录器

为 API 启用 Application Insights 日志记录

单个 API 或所有 API 的记录器

将哪些数据添加到 Application Insights

发出自定义指标

自定义指标的限制

性能影响和日志采样

视频

故障排除

相关内容

反馈

其他资源