如何将 Azure API 管理与 Azure Application Insights 集成How to integrate Azure API Management with Azure Application Insights

Azure API 管理可以轻松地与 Azure Application Insights 集成(一个可扩展的服务,可让 Web 开发人员在多个平台上生成和管理应用)。Azure API Management allows for easy integration with Azure Application Insights - an extensible service for web developers building and managing apps on multiple platforms. 本指南逐步讲解这种集成的每个步骤,并介绍可以采取哪些策略来降低对 API 管理服务实例的性能影响。This guide walks through every step of such integration and describes strategies for reducing performance impact on your API Management service instance.

先决条件Prerequisites

若要执行本指南中的步骤,需要一个 Azure API 管理实例。To follow this guide, you need to have an Azure API Management instance. 如果没有该实例,请先完成此教程If you don't have one, complete the tutorial first.

创建 Azure Application Insights 实例Create an Azure Application Insights instance

在使用 Azure Application Insights 之前,需要先创建一个服务实例。Before you can use Azure Application Insights, you first need to create an instance of the service.

  1. 打开 Azure 门户,导航到“Application Insights”。 Open the Azure portal and navigate to Application Insights.
    App Insights 创建App Insights create
  2. 单击“+ 添加”。 Click + Add.
    App Insights 创建App Insights create
  3. 填写窗体。Fill the form. 选择“常规”作为“应用程序类型”。 Select General as the Application Type.
  4. 单击创建Click Create.

在 Azure Application Insights 与 Azure API 管理服务实例之间创建连接Create a connection between Azure Application Insights and Azure API Management service instance

  1. Azure 门户中导航到自己的 Azure API 管理服务实例Navigate to your Azure API Management service instance in the Azure portal.
  2. 在左侧菜单中选择“Application Insights”。 Select Application Insights from the menu on the left.
  3. 单击“+ 添加”。 Click + Add.
    App Insights 记录器App Insights logger
  4. 选择前面创建的 Application Insights 实例并提供简短说明。Select the previously created Application Insights instance and provide a short description.
  5. 单击创建Click Create.
  6. 你刚刚创建了一个具有检测密钥的 Azure Application Insights 记录器。You have just created an Azure Application Insights logger with an instrumentation key. 该记录器现在应已显示在列表中。It should now appear in the list.
    App Insights 记录器

备注

在后台,将在 API 管理实例中创建了一个 Logger 实体,其中包含 Application Insights 实例的检测密钥。Behind the scene, a Logger entity is created in your API Management instance, containing the Instrumentation Key of the Application Insights instance.

为 API 启用 Application Insights 日志记录Enable Application Insights logging for your API

  1. Azure 门户中导航到自己的 Azure API 管理服务实例Navigate to your Azure API Management service instance in the Azure portal.
  2. 在左侧菜单中选择“API” 。Select APIs from the menu on the left.
  3. 单击你的 API(在本例中为“演示会议 API”)。 Click on your API, in this case Demo Conference API.
  4. 从顶部栏转到“设置”选项卡。 Go to the Settings tab from the top bar.
  5. 向下滚动到“诊断日志”部分。 Scroll down to the Diagnostics Logs section.
    App Insights 记录器App Insights logger
  6. 选中“启用”框。 Check the Enable box.
  7. 在“目标”下拉列表中选择附加的记录器。 Select your attached logger in the Destination dropdown.
  8. 输入 100 作为“采样率”,并勾选“始终记录错误”复选框。 Input 100 as Sampling (%) and tick the Always log errors checkbox.
  9. 单击“保存” 。Click Save.

警告

重写“正文的第一个字节”字段中的默认值“0”可能会显著降低 API 的性能 。Overriding the default value 0 in the First bytes of body field may significantly decrease the performance of your APIs.

备注

在后台,将在 API 级别创建一个名为“applicationinsights”的 Diagnostic 实体。Behind the scene, a Diagnostic entity named 'applicationinsights' is created at the API level.

设置名称Setting name 值类型Value type 说明Description
启用Enable booleanboolean 指定是否要启用此 API 的日志记录。Specifies whether logging of this API is enabled.
目标Destination Azure Application Insights 记录器Azure Application Insights logger 指定要使用的 Azure Application Insights 记录器Specifies Azure Application Insights logger to be used
采样率Sampling (%) decimaldecimal 值为 0 到 100(百分比)。Values from 0 to 100 (percent).
指定要将多少百分比的请求记录到 Azure Application Insights。Specifies what percentage of requests will be logged to Azure Application Insights. 0% 采样表示不记录任何请求,100% 采样表示记录所有请求。0% sampling means zero requests logged, while 100% sampling means all requests logged.
此设置用于降低将请求记录到 Azure Application Insights 时所造成的性能影响(请参阅以下部分)。This setting is used for reducing performance implications of logging requests to Azure Application Insights (see the section below).
始终记录错误Always log errors booleanboolean 如果选择此设置,则会将所有错误记录到 Azure Application Insights,不管“采样率”设置如何。 If this setting is selected, all failures will be logged to Azure Application Insights, regardless of the Sampling setting.
基本选项:头文件Basic Options: Headers listlist 指定要记录到 Azure Application Insights 的请求和响应标头。Specifies the headers that will be logged to Azure Application Insights for requests and responses. 默认值:不记录标头。Default: no headers are logged.
基本选项:正文的第一个字节Basic Options: First bytes of body integerinteger 指定要将请求和响应正文的最前面多少个字节记录到 Azure Application Insights。Specifies how many first bytes of the body are logged to Azure Application Insights for requests and responses. 默认值:不记录正文。Default: body is not logged.
高级选项:详细程度Advanced Options: Verbosity 指定详细程度。Specifies the verbosity level. 将仅记录具有较高严重性级别的自定义跟踪。Only custom traces with higher severity level will be logged. 默认值:信息。Default: Information.
高级选项:前端请求Advanced Options: Frontend Request 指定是否以及如何将前端请求记录到 Azure Application Insights。 Specifies whether and how frontend requests will be logged to Azure Application Insights. 前端请求是传入 Azure API 管理服务的请求。 Frontend request is a request incoming to the Azure API Management service.
高级选项:前端响应Advanced Options: Frontend Response 指定是否以及如何将前端响应记录到 Azure Application Insights。 Specifies whether and how frontend responses will be logged to Azure Application Insights. 前端响应是传出 Azure API 管理服务的响应。 Frontend response is a response outgoing from the Azure API Management service.
高级选项:后端请求Advanced Options: Backend Request 指定是否以及如何将后端请求记录到 Azure Application Insights。 Specifies whether and how backend requests will be logged to Azure Application Insights. 后端请求是传出 Azure API 管理服务的请求。 Backend request is a request outgoing from the Azure API Management service.
高级选项:后端响应Advanced Options: Backend Response 指定是否以及如何将后端响应记录到 Azure Application Insights。 Specifies whether and how backend responses will be logged to Azure Application Insights. 后端响应是传入 Azure API 管理服务的响应。 Backend response is a response incoming to the Azure API Management service.

备注

可以在不同的级别指定记录器 - 指定单个 API 记录器,或者对所有 API 使用一个记录器。You can specify loggers on different levels - single API logger or a logger for all APIs.

如果同时指定这两个选项:If you specify both:

  • 如果它们是不同的记录器,则会同时使用两者(多路复用日志);if they are different loggers, then both of them will be used (multiplexing logs),
  • 如果它们是相同的记录器但采用不同的设置,则单个 API 的记录器(粒度级更高)将替代所有 API 的记录器。if they are the same loggers but have different settings, then the one for single API (more granular level) will override the one for all APIs.

将哪些数据添加到 Azure Application InsightsWhat data is added to Azure Application Insights

Azure Application Insights 接收:Azure Application Insights receives:

  • 每个传入请求(前端请求、前端响应)的请求遥测项; Request telemetry item, for every incoming request (frontend request, frontend response),
  • 转发到后端服务的每个请求(后端请求、后端响应)的依赖项遥测项; Dependency telemetry item, for every request forwarded to a backend service (backend request, backend response),
  • 每个失败的请求的异常遥测项。 Exception telemetry item, for every failed request.

失败的请求是具有以下特征的请求:A failed request is a request, which:

  • 由于客户端连接关闭而失败,或failed because of a closed client connection, or
  • 触发了 API 策略的 on-error 节,或triggered an on-error section of the API policies, or
  • 具有与 4xx 或 5xx 匹配的响应 HTTP 状态代码。has a response HTTP status code matching 4xx or 5xx.

性能影响和日志采样Performance implications and log sampling

警告

记录所有事件可能会产生严重的性能影响,具体取决于传入请求的速率。Logging all events may have serious performance implications, depending on incoming requests rate.

根据内部负载测试,当请求速率超过每秒 1,000 个请求时,启用此功能会导致吞吐量下降 40%-50%。Based on internal load tests, enabling this feature caused a 40%-50% reduction in throughput when request rate exceeded 1,000 requests per second. Azure Application Insights 设计为使用统计分析来评估应用程序的性能。Azure Application Insights is designed to use statistical analysis for assessing application performances. 它并非旨在用作审核系统,并且不适合用于记录高流量 API 的每个请求。It is not intended to be an audit system and is not suited for logging each individual request for high-volume APIs.

可以通过调整“采样率”设置来操控所记录的请求数(参阅前面的步骤)。 You can manipulate the number of requests being logged by adjusting the Sampling setting (see the steps above). 值 100% 表示记录所有请求,0% 表示不记录任何请求。Value 100% means all requests are logged, while 0% reflects no logging at all. “采样率”有助于减少遥测量,可有效防止性能出现明显下降,同时仍可保持日志记录的优势 。Sampling helps to reduce volume of telemetry, effectively preventing from significant performance degradation, while still carrying the benefits of logging.

跳过请求和响应的标头与正文的日志记录也有利于缓解性能问题。Skipping logging of headers and body of requests and responses will also have positive impact on alleviating performance issues.

后续步骤Next steps