為 ASP.NET Core 應用程式啟用 Application Insights

本文說明如何為部署為 Azure Web 應用程式的 ASP.NET Core 應用程式啟用 Application Insights。 此實作採用 SDK 型方法,此外也可使用自動檢測方法

Application Insights 可以從 ASP.NET Core 應用程式收集下列遙測:

  • Requests
  • 相依性
  • 例外狀況
  • 效能計數器
  • 活動訊號
  • 記錄

我們將使用以 net6.0 為目標的 ASP.NET Core MVC 應用程式範例。 您可以將這些指示套用至所有 ASP.NET Core 應用程式。 如果您正在使用背景工作服務,請使用 這裡的指示。

注意

預覽 OpenTelemetry 型 .NET 供應項目可供使用。 深入了解

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。 檢測金鑰擷取將會繼續運作,但我們將不再提供該功能的更新或支援。 轉換至連接字串以利用新功能

支援的案例

ASP.NET Core 的 Application Insights SDK 可以監視應用程式,無論其執行位置或方式為何。 如果您的應用程式正在執行且具有 Azure 的網路連線能力,則可以收集遙測。 支援 .NET Core 的位置都支援 Application Insights 監視。 支援涵蓋下列案例:

  • 作業系統:Windows、Linux 或 Mac
  • 裝載方法:同處理序或跨處理序
  • 部署方法:架構相依或獨立式
  • 網頁伺服器:IIS (Internet Information Server) 或 Kestrel
  • 裝載平台:Azure App Service、Azure VM、Docker、Azure Kubernetes Service (AKS) 等的 Web Apps 功能
  • .NET Core 版本:所有正式支援的 .NET Core 版本都未處於預覽狀態
  • IDE:Visual Studio、Visual Studio Code 或命令列

先決條件

如果您想要依照本文的指引操作,必須符合特定必要條件。

  • Visual Studio 2022
  • Visual Studio 工作負載:ASP.NET 和 Web 開發、資料儲存體和處理,以及 Azure 開發
  • .NET 6.0
  • Azure 訂用帳戶和使用者帳戶 (具備建立和刪除資源的能力)

部署 Azure 資源

請依照指引,從 GitHub 存放庫部署範例應用程式。

為了替某些資源提供全域唯一的名稱,已指派了 5 字元的尾碼。 請記下此尾碼,以供本文後續使用。

顯示已部署的 Azure 資源清單,並醒目提示了 5 字元的尾碼。

建立 Application Insights 資源

  1. Azure 入口網站中,找出並選取 application-insights-azure-café 資源群組。

  2. 在頂端工具列功能表中,選取 [+ 建立]。

    顯示資源群組 application-insights-azure-cafe,並醒目提示了工具列功能表上的 [+ 建立] 按鈕。

  3. 在 [建立資源] 畫面上,從 Marketplace 搜尋文字方塊中搜尋並選取 Application Insights

    顯示 [建立資源] 畫面,其中已在搜尋方塊中輸入 Application Insights,並且在搜尋結果中醒目提示了 Application Insights。

  4. 在 Application Insights 資源概觀畫面上,選取 [建立]。

    顯示 Application Insights 概觀畫面,並醒目提示了 [建立] 按鈕。

  5. 在 Application Insights 畫面的 [基本] 索引標籤上,依照下列方式完成表單,然後選取 [檢閱 + 建立] 按鈕。 未指定於下表中的欄位可保留其預設值。

    欄位
    名稱 輸入 azure-cafe-application-insights-{SUFFIX},將 {SUFFIX} 取代為先前記錄的適當尾碼值。
    區域 選取在部署文章資源時選擇的相同區域。
    Log Analytics 工作區 選取 azure-cafe-log-analytics-workspace,或者,也可在此處建立新的 Log Analytics 工作區。

    顯示已在表單中填入上述值的 Application Insights [基本] 索引標籤。

  6. 在驗證通過後,選取 [建立] 以部署資源。

    顯示 Application Insights 驗證畫面,其中指出驗證已通過,並醒目提示了 [建立] 按鈕。

  7. 在部署完成後,返回 application-insights-azure-cafe 資源群組,然後選取已部署的 Application Insights 資源。

    顯示 Azure Cafe 資源群組,並醒目提示了 Application Insights 資源。

  8. 在 Application Insights 資源的 [概觀] 畫面上,複製 [連接字串] 值以供本文的下一節使用。

    顯示 Application Insights 的 [概觀] 畫面,並醒目提示了連接字串值,且已選取 [複製] 按鈕。

在 Web App Service 中設定 Application Insights 連接字串應用程式設定

  1. 返回 application-insights-azure-cafe 資源群組,找出 azure-café-web-{SUFFIX} App Service 資源,並加以開啟。

    顯示 Azure Cafe 資源群組,並醒目提示了 azure-cafe-web-{SUFFIX} 資源。

  2. 從左側功能表的 [設定] 標頭底下,選取 [設定]。 然後,在 [應用程式設定] 索引標籤的 [應用程式設定] 底下,選取 [+ 新增應用程式設定]。

    顯示 App Service 資源畫面,其中已從左側功能表中選取了 [設定項目],並醒目提示了 [+ 新增應用程式設定] 工具列按鈕。

  3. 在 [新增/編輯應用程式設定] 刀鋒視窗中,依照下列方式完成表單,然後選取 [確定]。

    欄位
    名称 APPLICATIONINSIGHTS_CONNECTION_STRING
    貼上在上一節取得的 Application Insights 連接字串。

    顯示已填入上述值的 [新增/編輯應用程式設定] 刀鋒視窗。

  4. 在 [App Service 設定] 畫面上,從工具列功能表中選取 [儲存] 按鈕。 在系統提示您儲存變更時,選取 [繼續]。

    顯示 App Service 的 [設定] 畫面,並醒目提示了工具列功能表上的 [儲存] 按鈕。。

安裝 Application Insights NuGet 套件

我們需要設定 ASP.NET Core MVC Web 應用程式以傳送遙測。 此作業可使用適用於 ASP.NET Core Web 應用程式的 Application Insights NuGet 套件來完成。

  1. 使用 Visual Studio 開啟 1 - Starter Application\src\AzureCafe.sln

  2. 在 [方案總管] 畫面中,以滑鼠右鍵按一下 AzureCafe 專案檔,然後選取 [管理 NuGet 套件]。

    顯示已從操作功能表中選取 [管理 NuGet 套件] 的方案總管。

  3. 選取 [瀏覽] 索引標籤,然後搜尋 Microsoft.ApplicationInsights.AspNetCore 並加以選取。 選取 [安裝] 並接受授權條款。 建議使用最新的穩定版本。 在開放原始碼 GitHub 存放庫上尋找 SDK 的完整版本資訊。

    顯示 NuGet 索引標籤,其中已選取了 [瀏覽] 索引標籤,並且在搜尋方塊中輸入了 Microsoft.ApplicationInsights.AspNetCore。從結果清單中選取了 Microsoft.ApplicationInsights.AspNetCore 套件。在右側窗格中,從下拉式清單中選取最新的穩定版本,且 [安裝] 按鈕已醒目提示。

  4. 讓 Visual Studio 保持開啟,以供本文的下一節使用。

啟用 Application Insights 伺服器端遙測

適用於 ASP.NET Core Web 應用程式的 Application Insights NuGet 套件中封裝的功能,可將伺服器端遙測傳送至 Azure 中的 Application Insights 資源。

  1. 在 Visual Studio 方案總管中,找出並開啟 Program.cs 檔案。

    顯示 Visual Studio 方案總管,並醒目提示了 Program.cs。

  2. builder.Services.AddControllersWithViews() 陳述式前面插入下列程式碼。 此程式碼會自動從設定中讀取 Application Insights 連接字串值。 AddApplicationInsightsTelemetry 方法會將 ApplicationInsightsLoggerProvider 註冊到內建的相依性插入容器,然後該容器就會用來實現 ILoggerILogger<TCategoryName> 實作要求。

    builder.Services.AddApplicationInsightsTelemetry();
    

    顯示程式碼視窗,並醒目提示了上述程式碼片段。

    秘訣

    深入了解 ASP.NET Core 中的設定選項

啟用 Web 應用程式的用戶端遙測

上述步驟足以協助您開始收集伺服器端遙測。 此應用程式具有用戶端元件,請依照後續步驟開始收集使用量遙測

  1. 在 Visual Studio 方案總管中,找出 \Views\_ViewImports.cshtml 並加以開啟。 在現有檔案的結尾新增下列程式碼。

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    

    顯示 _ViewImports.cshtml 檔案,並醒目提示了上述程式碼行。

  2. 若要正確啟用應用程式的用戶端監視,則 JavaScript 程式碼片段必須出您要監視的應用程式各個頁面上的 <head> 區段中。 在 Visual Studio 方案總管中,找出 \Views\Shared\_Layout.cshtml 並加以開啟,然後在結尾 <\head> 標籤前面插入下列程式碼。

    @Html.Raw(JavaScriptSnippet.FullScript)
    

    顯示 _Layout.cshtml 檔案,並在頁面的 head 區段內醒目提示了上述程式碼行。

    秘訣

    作為使用 FullScript 的替代方案,也可以使用 ScriptBody。 如果您需要控制 <script> 標籤以設定內容安全性原則,請使用 ScriptBody

    <script> // apply custom changes to this script tag.
        @Html.Raw(JavaScriptSnippet.ScriptBody)
    </script>
    

注意

JavaScript 插入提供預設的設定體驗。 如果您需要設定連接字串以外的設定,您必須依照上述說明移除自動插入,並手動新增 JavaScript SDK

啟用資料庫查詢的監視

調查效能降低的原因時,請務必將資料庫呼叫的深入解析納入考量。 透過相依性模組的設定來啟用監視。 依預設會啟用相依性監視,包括 SQL。 依照下列步驟可擷取完整的 SQL 查詢文字。

注意

SQL 文字可能包含敏感性資料,例如密碼和 PII。 啟用此功能時請多加留意。

  1. 在 Visual Studio 方案總管中,找出並開啟 Program.cs 檔案。

  2. 在檔案頂端新增下列 using 陳述式。

    using Microsoft.ApplicationInsights.DependencyCollector;
    
  3. 緊接在 builder.Services.AddApplicationInsightsTelemetry() 程式碼之後,插入下列內容以啟用 SQL 命令文字檢測。

    builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
    

    顯示程式碼視窗,並醒目提示了上述程式碼。

執行 Azure Cafe Web 應用程式

部署 Web 應用程式程式碼後,遙測將會流向 Application Insights。 Application Insights SDK 會自動收集傳入至應用程式的 Web 要求。

  1. 在 [方案總管] 中以滑鼠右鍵按一下 AzureCafe 專案,然後從操作功能表中選取 [發佈]。

    顯示 Visual Studio 方案總管,其中已選取了 Azure Cafe 專案,並醒目提示了 [發佈] 操作功能表項目。

  2. 選取 [發佈],將新程式碼升階至 Azure App Service。

    顯示 AzureCafe 發佈設定檔,並醒目提示了 [發佈] 按鈕。

  3. 發佈成功後,就會開啟新的瀏覽器視窗以顯示 Azure Cafe Web 應用程式。

    顯示 Azure Cafe Web 應用程式。

  4. 在 Web 應用程式中執行各種活動,以產生一些遙測。

    1. 選取 Cafe 旁的 [詳細資料],以檢視其菜單和評價。

      顯示 Azure Cafe 清單的一部分,並醒目提示了 [詳細資料] 按鈕。

    2. 在 Cafe 畫面上選取 [評價] 索引標籤,以檢視和新增評價。 選取 [新增評價] 按鈕,以新增評價。

      顯示 Cafe 詳細資料畫面,並醒目提示了 [新增評價] 按鈕。

    3. 在 [建立評價] 對話方塊中,為評價輸入名稱、評等、評論,並上傳相片。 在作業完成後,選取 [新增評價]。

      顯示 [建立評價] 對話方塊。

    4. 視需要重複新增評價的步驟,以產生其他遙測。

即時計量

即時計量可用於快速驗證 Application Insights 監視是否設定正確。 遙測可能需要幾分鐘的時間才會出現在入口網站和分析中,但即時計量會以近乎即時的方式,顯示執行中處理序的 CPU 使用率。 即時計量也可以顯示其他遙測,例如要求、相依性、追蹤等。

應用程式對應

範例應用程式會呼叫多項 Azure 資源,包括 Azure SQL、Azure Blob 儲存體和 Azure 語言服務 (用以評價情感分析)。

顯示 Azure Cafe 範例應用程式架構。

Application Insights 會檢查傳入的遙測資料,並且能夠為偵測到的系統整合產生視覺化對應。

  1. 存取並登入 Azure 入口網站

  2. 開啟範例應用程式資源群組 application-insights-azure-cafe

  3. 從資源清單中,選取 azure-cafe-insights-{SUFFIX} Application Insights 資源。

  4. 在左側功能表的 [調查] 標題底下,選取 [應用程式對應]。 觀察產生的應用程式對應。

    顯示 Application Insights 應用程式對應。

檢視 HTTP 呼叫和資料庫 SQL 命令文字

  1. 在 Azure 入口網站中開啟 Application Insights 資源。

  2. 在左側功能表的 [調查] 標頭底下,選取 [效能]。

  3. [作業] 索引標籤包含應用程式所接收之 HTTP 呼叫的詳細資料。 您也可以在資料的伺服器與瀏覽器 (用戶端) 檢視之間切換。

    顯示 Application Insights 的 [效能] 畫面,並醒目提示了伺服器與瀏覽器之間的切換開關,以及應用程式所收到的 HTTP 呼叫清單。

  4. 從資料表中選取 [作業],然後選擇鑽研至要求的範例。

    顯示已選取 POST 作業的 [效能] 畫面,並醒目提示了 [鑽研至範例] 按鈕,且已從建議的清單中選取範例。

  5. 所選要求的端對端交易隨即顯示。 在此案例中,建立了包含影像的評價,因此其中包含對 Azure 儲存體、語言服務 (進行情感分析) 的呼叫,以及對 SQL Azure 的資料庫呼叫 (用以保存評價)。 在此範例中,第一個選取的事件會顯示與 HTTP POST 呼叫相關的資訊。

    顯示已選取 HTTP POST 呼叫的端對端交易。

  6. 選取 SQL 項目以檢閱對資料庫發出的 SQL 命令文字。

    顯示端對端交易以及 SQL 命令詳細資料。

  7. 選擇性地選取對 Azure 儲存體或語言服務的相依性 (傳出) 要求。

  8. 返回 [效能] 畫面,然後選取 [相依性] 索引標籤,以調查對外部資源的呼叫。 請注意,作業資料表包含對情感分析、Blob 儲存體和 Azure SQL 的呼叫。

    顯示已選取 [相依性] 索引標籤並醒目提示了 [作業] 資料表的 [效能] 畫面。

使用 Application Insights 進行應用程式記錄

記錄概觀

Application Insights 是一種記錄提供者,在已安裝 ASP.NET Core 的 Application Insights NuGet 套件,且已啟用伺服器端遙測收集時,可供 ASP.NET Core 應用程式使用。 提醒您,Program.cs 中的下列程式碼會將 ApplicationInsightsLoggerProvider 註冊至內建的相依性插入容器。

builder.Services.AddApplicationInsightsTelemetry();

ApplicationInsightsLoggerProvider 註冊為記錄提供者後,應用程式即可使用建構函式插入搭配 ILogger 或泛型類型替代 ILogger<TCategoryName> 來登入 Application Insights。

注意

使用預設設定時,記錄提供者會設為自動擷取嚴重性為 LogLevel.Warning 或更高的記錄事件。

下列範例控制器示範使用註冊至相依性插入容器的 ApplicationInsightsLoggerProvider 進行解析的 ILogger 插入,請加以考量。 觀察記錄了資訊、警告和錯誤訊息的 Get 方法。

注意

依預設不會記錄資訊層級追蹤。 只會擷取警告和更高層級的訊息。

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInfo("An example of an Info trace..")
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

如需詳細資訊,請參閱 ASP.NET Core 中的記錄

在 Application Insights 中檢視記錄

上述 ValuesController 是以範例應用程式部署的,位於專案的 Controllers 資料夾中。

  1. 使用網際網路瀏覽器,開啟範例應用程式。 在位址列中附加 /api/Values,然後按 Enter 鍵。

    顯示在位址列中將 /api/Values 附加至 URL 的瀏覽器視窗。

  2. 稍候片刻,然後返回 Azure 入口網站中的 Application Insights 資源。

    顯示資源群組,並醒目提示了 Application Insights 資源。

  3. 在 Application Insights 資源的左側功能表中,從 [監視] 區段下方選取 [記錄]。 在 [資料表] 窗格中,按兩下位於 Application Insights 樹狀目錄下的追蹤資料表。 依照下列方式修改查詢以擷取 [值] 控制器的追蹤,然後選取 [執行] 以篩選結果。

    traces 
    | where operation_Name == "GET Values/Get"
    
  4. 觀察結果會顯示控制器中存在的記錄訊息。 記錄嚴重性為 2 表示警告層級,記錄嚴重性為 3 則表示錯誤層級。

  5. 或者,也可撰寫查詢以根據記錄的類別擷取結果。 根據預設,類別是插入 ILogger 之類別的完整名稱,在此案例中為 ValuesController (如果有與類別相關聯的命名空間,則名稱前面會加上該命名空間)。 重新寫入並執行下列查詢,以根據類別擷取結果。

    traces 
    | where customDimensions.CategoryName == "ValuesController"
    

控制傳送至 Application Insights 的記錄層級

ILogger 實作有內建機制可套用記錄篩選。 此篩選可讓您控制傳送給每個已註冊提供者的記錄,包括 Application Insights 提供者。 您可以在設定 (使用 appsettings.json 檔案) 或程式碼中使用篩選。 如需記錄層級的詳細資訊和適當用途的指引,請參閱記錄層級文件。

下列範例說明如何將篩選規則套用至 ApplicationInsightsLoggerProvider,以控制傳送至 Application Insights 的記錄層級。

透過設定建立篩選規則

ApplicationInsightsLoggerProvider 在設定中會具有別名 ApplicationInsightsappsettings.json 檔案的下列區段會將所有提供者的預設記錄層級設定為 LogLevel.Warning。 以 "ValuesController" 開頭的類別專用的 ApplicationInsights 提供者設定,會將此預設值覆寫為 LogLevel.Error 或更高。

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

使用 appsettings.json 中的上述程式碼部署範例應用程式,只會產生在與 ValuesController 互動時傳送至 Application Insights 的錯誤追蹤。 這是因為 ValuesController 類別的 LogLevel 設定為 [錯誤],因此會隱藏 [警告] 追蹤。

關閉 Application Insights 的記錄

若要使用設定停用記錄,請將所有 LogLevel 值設定為 [無]。

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

同樣地,在程式碼中,將 ApplicationInsightsLoggerProvider 的預設層級和任何後續的記錄層級設定為 [無]。

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

開放原始碼 SDK

如需最新的更新和 Bug 修正,請參閱版本資訊

後續步驟