通过

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

  • 项目

适用于：所有 API 管理层级

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

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

警告

使用自托管网关时，我们不能保证所有遥测数据都会被推送到 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 工具。

方案概述

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

  1. 首先，在 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 或相关工具创建记录器，如本文后面部分所示。

  2. 然后，为 API 启用 Application Insights 日志记录。

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

使用 Azure 门户创建连接

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

注意

在可能的情况下，Microsoft 建议使用带有托管标识凭据的连接字符串来增强安全性。 若要配置这些凭据，请使用 REST API 或相关工具，如本文后面部分所示。

  1. 在 Azure 门户中导航到自己的 Azure API 管理服务实例。

  2. 在左侧菜单中选择“Application Insights”。

  3. 选择“+ 添加”。
    显示在何处添加新连接的屏幕截图

  4. 选择前面创建的 Application Insights 实例并提供一个简短的说明。

  5. 如要启用 Application Insights 中的 API 管理实例的可用性监视，请选择“添加可用性监视”复选框。

    • 此设置会定期验证 API 管理网关终结点是否正在响应。
    • 结果显示在 Application Insights 实例的“可用性”窗格中。

  6. 选择“创建”。

  7. 检查新 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"
    }
  }
}

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

使用包含以下请求正文的 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/;..."    
    }
  }
}

为 API 启用 Application Insights 日志记录

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

  1. 在 Azure 门户中导航到自己的 Azure API 管理服务实例。

  2. 在左侧菜单中选择“API” 。

  3. 单击你的 API（在本例中为“演示会议 API”）。 选择一个版本（如果已配置）。

    提示

    若要为所有 API 启用日志记录，请选择所有 API。

  4. 从顶部栏转到“设置”选项卡。

  5. 向下滚动到“诊断日志”部分。
    App Insights 记录器

  6. 选中“启用”框。

  7. 在“目标”下拉列表中选择附加的记录器。

  8. 输入 100 作为“采样率”，并选中“始终记录错误”复选框。

  9. 将其余设置保留不变。 有关设置的详细信息，请参阅诊断日志设置参考。

    警告

    替代“要记录的有效负载字节数”的默认值 0 可能会显著降低 API 的性能。

  10. 选择“保存”。

  11. 在后台，将在 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 资源，从而解决遥测数据传输问题。

相关内容