Compartir a través de

如何将 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 服务的实例。 若要使用 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":"<client-ID>"
    }
  }
}

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

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>API 。

  3. 选择一个 API，例如 Swagger Petstore。 选择一个版本（如果已配置）。

    提示

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

  4. 选择顶部栏上的 “设置” 选项卡。

  5. 向下滚动到 “诊断日志 ”部分，然后选中“ 启用 ”框。 门户中的诊断日志配置的屏幕截图。

  6. 在“目标”下拉列表中选择已连接的日志记录器。

  7. 输入 100 作为 采样 (%)，并选中 始终记录错误 复选框。

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

    警告

    重写用于记录值 0 的默认有效负载字节数可能会显著降低 API 的性能。

  9. 选择“保存”。

  10. 在幕后，将在 API 级别创建一个名为 applicationinsights 的 Diagnostic 实体。

注意

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

单个 API 或所有 API 的记录器

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

  • 单一 API 记录器
  • 所有 API 的记录器

指定两者：

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

将哪些数据添加到 Application Insights

Application Insights 接收：

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

注意

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

性能影响和日志采样

警告

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

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

  • 目标是成为一个审核系统。
  • 适用于记录高流量 API 的每个请求。

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

“采样”有助于减少遥测数据量，可有效防止性能显著下降，同时仍然具备日志记录的优势。

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

  • 请求和响应标头
  • 主体日志记录

故障排除

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

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

相关内容

  • Last updated on