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

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

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

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

先决条件

需要一个 Azure API 管理实例。 首先创建一个实例

创建 Application Insights 实例

若要使用 Application Insights,请创建 Application Insights 服务实例。 若要使用 Azure 门户创建实例,请参阅基于工作区的 Application Insights 资源

在 Application Insights 和 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 管理实例中创建一个 Logger 实体,其中包含 Application Insights 实例的检测密钥。

为 API 启用 Application Insights 日志记录

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

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

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

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

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

  6. 选中“启用”框。

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

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

  9. 将其余设置保留不变。

    警告

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

  10. 选择“保存”。

  11. 在后台,将在 API 级别创建一个名为 Diagnostic 实体。

注意

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

设置名称 值类型 说明
启用 boolean 指定是否要启用此 API 的日志记录。
目标 Azure Application Insights 记录器 指定要使用的 Azure Application Insights 记录器。
采样率 decimal 值为 0 到 100(百分比)。
指定要记录到 Application Insights 的请求数百分比。 0% 采样表示不记录任何请求,100% 采样表示记录所有请求。
使用此设置可以降低将请求记录到 Application Insights 时对性能造成的影响。 请参阅性能影响和日志采样
始终记录错误 boolean 如果选择此设置,则会将所有错误记录到 Application Insights,不管“采样率”设置如何。
记录客户端 IP 地址 如果选择此设置,则会将 API 请求的客户端 IP 地址记录到 Application Insights。
详细程度 指定详细程度。 将仅记录具有较高严重性级别的自定义跟踪。 默认值:信息。
关联协议 选择用于关联多个组件发送的遥测数据的协议。 默认值:旧版
有关信息,请参阅 Application Insights 中的遥测关联
基本选项:要记录的头 list 指定要记录到 Application Insights 的请求和响应头。 默认值:不记录标头。
基本选项:要记录的有效负载字节数 整型 指定要将请求和响应正文的最前面多少个字节记录到 Application Insights。 默认值:0。
高级选项:前端请求 指定是否以及如何将前端请求记录到 Application Insights。 前端请求是传入 Azure API 管理服务的请求。
高级选项:前端响应 指定是否以及如何将前端响应记录到 Application Insights。 前端响应是传出 Azure API 管理服务的响应。
高级选项:后端请求 指定是否以及如何将后端请求记录到 Application Insights。 后端请求是传出 Azure API 管理服务的请求。
高级选项:后端响应 指定是否以及如何将后端响应记录到 Application Insights。 后端响应是传入 Azure API 管理服务的响应。

注意

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

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

同时指定:

  • 如果它们是不同的记录器,则会同时使用两者(多路复用日志)。
  • 如果它们是相同的记录器但采用不同的设置,则单个 API 记录器(粒度级更高)将替代所有 API 的记录器。

将哪些数据添加到 Application Insights

Application Insights 接收:

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

发出自定义指标

可以通过配置 emit-metric 策略来发出自定义指标。

若要使 Application Insights 预先聚合指标在 API 管理中可用,需要在服务中手动启用自定义指标。

  1. emit-metric 策略用于emit-metric
  2. "metrics":true 添加到有效负载以及任何其他属性。

注意

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

性能影响和日志采样

警告

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

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

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

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

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

若要改进性能问题,请跳过:

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

视频

后续步骤