如何整合 Azure API 管理與 Azure Application Insights
適用於：所有 API 管理 層
您可以輕鬆整合 Azure Application Insights 與 Azure API 管理。 Azure Application Insights 是可延伸的服務，可供 Web 開發人員在多個平台上建置和管理應用程式。 在本指南中，您將會：
- 逐步解說 Application Insights 與 APIM 的整合。
- 了解在 API 管理服務執行個體上降低效能影響的策略。
必要條件
您需要 Azure API 管理執行個體。 請先建立一個。
若要使用 Application Insights，請建立 Application Insights 服務的執行個體。 若要使用 Azure 入口網站建立執行個體，請參閱以工作區為基礎的 Application Insights 資源。
注意
Application Insights 資源可以在不同的訂閱中，甚至位於與 API 管理資源不同的租用戶中。
如果您打算為 APIM 設定受控識別以搭配 Application Insights 使用，則需要完成下列步驟：
在 API 管理執行個體中，啟用系統指派或使用者指派之適用於 API 管理的受控識別。
- 如果您啟用使用者指派的受控識別，請記下身分識別的用戶端識別碼。
為此身分識別指派監視計量發行者角色，且範圍設定為 Application Insights 資源。 若要指派角色，請使用 Azure 入口網站或其他 Azure 工具。
案例概觀
以下是此案例的高階步驟。
首先，在 Application Insights 與 APIM 之間建立連線
您可以使用 Azure 入口網站、REST API 或相關的 Azure 工具，在 Application Insights 與 APIM 之間建立連線。 APIM 會為連線設定「記錄器」資源。
注意
如果您的 Application Insights 資源位於不同的租用戶中，則您必須使用 REST API 來建立記錄器。
重要
目前，在入口網站中，APIM 僅支援使用 Application Insights 檢測金鑰連線到 Application Insights。 若要使用 Application Insights 連接字串或 APIM 受控識別，請使用 REST API、Bicep 或 ARM 範本來建立記錄器。 深入了解 Application Insights 連接字串。
接著，為您的一或多個 API 啟用 Application Insights 記錄功能。
在本文中，您會使用 Azure 入口網站，為 API 啟用 Application Insights 記錄功能。 APIM 會為 API 設定「診斷」資源。
使用 Azure 入口網站建立連線
遵循這些步驟，使用 Azure 入口網站來建立 Application Insights 與 APIM 之間的連線。
在「Azure 入口網站」中，瀏覽至您的「Azure API 管理服務執行個體」。
從左側功能表中，選取 [Application Insights]。
選取 + 新增。
選取先前建立的 Application Insights 執行個體，然後提供簡短描述。
若要在 Application Insights 中啟用 API 管理執行個體的可用性監視，請選取 [新增可用性監視] 核取方塊。
- 此設定會定期驗證 API 管理閘道端點是否回應。
- 結果會出現在 Application Insights 執行個體的 [可用性] 窗格中。
選取 建立。
檢查新的 Application Insights 記錄器現在出現在清單中。
注意
在幕後，記錄器實體會建立於 APIM 執行個體，其中包含 Application Insights 執行個體的檢測金鑰。
提示
如果您需要更新 Application Insights 記錄器中設定的檢測金鑰，則在清單中選取該記錄器的資料列 (而非記錄器的名稱)。 輸入檢測金鑰，然後選取 [儲存]。
使用 REST API、Bicep 或 ARM 範本建立連線
遵循這些步驟，使用 REST API、Bicep 或 ARM 範本來建立 Application Insights 與 APIM 之間的連線。 您可以設定記錄器，使用連接字串、系統指派的受控識別或使用者指派的受控識別。
具有連接字串認證的記錄器
Application Insights 連接字串會出現在 Application Insights 資源的 [概觀] 區段中。
搭配下列要求本文使用 APIM REST API。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
具有系統指派受控識別認證的記錄器
請參閱使用 APIM 受控識別的必要條件。
搭配下列要求本文使用 APIM REST API。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with system-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"SystemAssigned"
}
}
}
具有使用者指派受控識別認證的記錄器
請參閱使用 APIM 受控識別的必要條件。
搭配下列要求本文使用 APIM REST API。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with user-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"<ClientID>"
}
}
}
為您的 API 啟用 Application Insights 記錄功能
使用下列步驟，為 API 啟用 Application Insights 記錄功能。 您也可以為所有 API 啟用 Application Insights 記錄功能。
在「Azure 入口網站」中，瀏覽至您的「Azure API 管理服務執行個體」。
從左側功能表中選取 [API]。
按一下您的 API，在此案例中為 [Demo Conference API]。 如果已設定，請選取版本。
提示
若要為所有 API 啟用記錄功能，請選取 [所有 API]。
從頂端列移至 [設定] 索引標籤。
向下捲動至 [診斷記錄] 區段。
選取 [啟用] 方塊。
從 [目的地] 下拉式清單中，選取已連結的記錄器。
輸入 100 作為 [取樣 (%)]，然後選取 [一律記錄錯誤] 核取方塊。
讓其餘設定保持原狀。 如需設定的詳細資訊，請參閱診斷記錄設定參考。
警告
覆寫預設的承載位元組數目以記錄 值 0，可能會大幅降低 API 的效能。
選取 [儲存]。
在幕後作業中，名為
applicationinsights的診斷實體會建立於 API 層級。
注意
一旦 API 管理將整個回應傳送至用戶端，要求即成功。
適用於單一 API 或所有 API 的記錄器
您可以指定不同層級的記錄器：
- 單一 API 記錄器
- 適用於所有 API 的記錄器
同時指定「兩者」：
- 根據預設，單一 API 記錄器 (更細微的層級) 會覆寫適用於所有 API 的記錄器。
- 如果兩個層級設定的記錄器不同，而且您需要這兩個記錄器接收遙測 (多工處理)，請連絡 Microsoft 支援服務。 請注意，如果您在「所有 API」層級和單一 API 層級上使用相同的記錄器 (Application Insights 目的地)，則不支援多工。 若要讓多工正常運作，您必須在「所有 API」和個別 API 層級上設定不同的記錄器，並向 Microsoft 支援服務要求協助，來為您的服務啟用多工。
哪些資料會新增至 Application Insights
Application Insights 會接收：
| 遙測項目 | 描述 |
|---|---|
| 要求 | 對於每個傳入要求：
|
| 相依性 | 對於每個轉送至後端服務的要求：
|
| 例外狀況 | 對於每個失敗的要求：
|
| 追蹤 | 如果您設定追蹤原則。 trace 原則中的 severity 設定必須等於或大於 Application Insights 記錄中的 verbosity 設定。 |
注意
如需每個 Application Insights 執行個體的計量和事件大小和數目上限的相關資訊，請參閱 Application Insights 限制。
發出自訂計量
您可以從 APIM 執行個體發出自訂計量到 Application Insights。 APIM 會使用 emit-metric 原則來發出自訂計量。
若要發出自訂計量，請執行下列設定步驟。
使用 Application Insights 執行個體中的自訂維度，啟用 [自訂計量 (預覽)]。
- 在入口網站中，瀏覽到您的 Application Insights 執行個體。
- 在左側功能表中，選取 [使用量和估計成本]。
- 選取 [自訂計量 (預覽)]>[具有維度]。
- 選取 [確定]。
將
"metrics": true屬性新增至 APIM 中設定的applicationInsights診斷實體。 您目前必須使用 APIM 診斷 - 建立或更新 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 監視器會針對自訂計量施加使用量限制，其可能會對您從 APIM 發出計量的能力產生影響。 例如，Azure 監視器目前會為每個計量設定 10 個維度索引鍵的限制，以及為訂用帳戶中的每個區域設定總計 50,000 個使用中時間序列的限制 (在 12 小時內)。
這些限制對於在 APIM 中設定自訂計量有下列影響：
您可以在每個
emit-metric原則中最多設定 10 個自訂維度。emit-metric原則在 12 小時內所產生的使用中時間序列數目，是在該期間內每個已設定維度之唯一值數目的乘積。 例如，如果在原則中設定了三個自訂維度，而且每個維度在該期間內都有 10 個可能的值，則emit-metric原則會提供 1,000 (10 x 10 x 10) 個使用中時間序列。如果您在位於訂用帳戶相同區域內的多個 APIM 執行個體中設定
emit-metric原則，則所有執行個體可能都會影響區域使用中時間序列限制。
效能影響與記錄取樣
警告
視連入要求速率而定，記錄所有事件可能會帶來嚴重的效能影響。
根據內部負載測試，當要求比率超過每秒 1,000 個要求時，啟用此記錄功能會造成輸送量降低 40%-50%。 Application Insights 的設計目的是使用統計分析來評估應用程式效能。 這不是：
- 目的為稽核系統。
- 適用於記錄大量 API 的每個個別要求。
您可以透過調整 [取樣] 設定，來操控要記錄的要求數目。 值為 100% 時，表示會記錄所有要求，值為 0% 時，則表示不進行記錄。
取樣有助於減少遙測量，可有效地防止嚴重的效能衰退，同時仍享有記錄功能的優點。
若要改善效能問題，請略過：
- 要求和回應標頭。
- 本文記錄。
影片
疑難排解
解決從 APIM 到 Application Insights 的遙測資料流程問題：
- 調查連結的 Azure 監視器私人連結範圍 (AMPLS) 資源是否存在於連線 APIM 資源的 VNet 內。 AMPLS 資源具有跨訂用帳戶的全域範圍，並負責管理所有 Azure 監視器資源的資料查詢和擷取。 AMPLS 可能已特別針對資料擷取使用僅限私人存取模式進行設定。 在這種情況下，請在 AMPLS 中包含 Application Insights 資源及其相關聯的 Log Analytics 資源。 新增之後，APIM 資料將成功內嵌至 Application Insights 資源，以解決遙測資料傳輸問題。
下一步
- 深入了解 Azure Application Insights。
- 考慮使用 Azure 事件中樞來進行記錄。
- 了解如何使用 Azure 受控 Grafana 從 Application Insights 將資料視覺化