Application Insights 的相依性追蹤

發行項
10/15/2024

注意

下列文件以 Application Insights 傳統 API 為依據。 Application Insights 的長期計劃是使用 OpenTelemetry 收集資料。如需詳細資訊，請參閱啟用適用於 .NET、Node.js、Python 和 JAVA 應用程式的 Azure 監視器 OpenTelemetry 和我們的 OpenTelemetry 藍圖。移轉指導適用於 .NET、Node.js 和 Python。

「相依性」是由您應用程式呼叫的元件。其通常是使用 HTTP 呼叫的服務、資料庫或檔案系統。 Application Insights 會測量相依性呼叫的持續時間，以及呼叫是否失敗，還提供相依性名稱之類的資訊。您可以調查特定的相依性呼叫，然後將其與要求和例外狀況相互關聯。

自動追蹤的相依性

適用於 .NET 和 .NET Core 的 Application Insights SDK 隨附 DependencyTrackingTelemetryModule，這是會自動收集相依性的遙測模組。當根據連結的官方文件進行設定時，會自動為 ASP.NET 和 ASP.NET Core 應用程式啟用此相依性集合。模組 DependencyTrackingTelemetryModule 隨附為 Microsoft.ApplicationInsights.DependencyCollector NuGet 套件。使用 Microsoft.ApplicationInsights.Web NuGet 套件或 Microsoft.ApplicationInsights.AspNetCore NuGet 套件時，即會自動將其帶入。

目前，DependencyTrackingTelemetryModule 會自動追蹤下列相依性：

相依性	詳細資料
HTTP/HTTPS	本機或遠端 HTTP/HTTPS 呼叫。
WCF 呼叫	只有在使用 HTTP 型繫結時，才會自動追蹤。
SQL	使用 `SqlClient` 發出的呼叫。如需擷取 SQL 查詢，請參閱透過進階 SQL 追蹤取得完整的 SQL 查詢一節。
Azure Blob 儲存體、資料表儲存體或佇列儲存體	使用 Azure 儲存體用戶端發出的呼叫。
Azure 事件中樞用戶端 SDK	使用最新的套件：https://nuget.org/packages/Azure.Messaging.EventHubs。
Azure 服務匯流排用戶端 SDK	使用最新的套件：https://nuget.org/packages/Azure.Messaging.ServiceBus。
Azure Cosmos DB	如果使用 HTTP/HTTPS，則會自動追蹤。直接模式中使用 TCP 的追蹤作業也會使用預覽套件 >= 3.33.0-preview 自動擷取。如需詳細資訊，請造訪文件。

如果缺少相依性，或使用不同的 SDK，請確定相依性列在自動收集的相依性清單中。如果相依性未自動收集，您可以透過追蹤相依性呼叫以手動方式加以追蹤。

在主控台應用程式中設定自動相依性追蹤

若要從 .NET 主控台應用程式自動追蹤相依性，請安裝 NuGet 套件 Microsoft.ApplicationInsights.DependencyCollector 並初始化 DependencyTrackingTelemetryModule：

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

對於 .NET Core 主控台應用程式，TelemetryConfiguration.Active 已過時。請參閱背景工作角色服務文件和 ASP.NET Core 監視文件中的指引。

自動相依性監視如何運作？

相依性可使用下列其中一種技術自動收集：

對特定方法使用位元組字碼檢測。使用來自 StatusMonitor 或 Azure App Service Web Apps 延伸模組的 InstrumentationEngine。
EventSource 回呼。
最新 .NET 或 .NET Core SDK 中的 DiagnosticSource 回呼。

手動追蹤相依性

下列相依性範例不是自動收集的，因此需要手動追蹤：

只有在使用 HTTP/HTTPS 的情況下，才會自動追蹤 Azure Cosmos DB。對於比 2.22.0-Beta1 舊的 SDK 版本，Application Insights 不會自動擷取 TCP 模式。
Redis

對於未由 SDK 自動收集的相依性，您可以使用標準自動收集模組所使用的 TrackDependency API 以手動方式加以追蹤。

範例

如果您建置程式碼的組件不是您自己撰寫的，您可以對其所有的呼叫計時。此案例可讓您了解其佔回應時間的比例。

若要在 Application Insights 中的相依性圖表中顯示此資料，請使用 TrackDependency 傳送此資料。


    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData",  startTime, timer.Elapsed, success);
    }

或者，TelemetryClient 提供擴充方法 StartOperation 和 StopOperation，其可用來手動追蹤相依性，如連出相依性追蹤所示

如果您想要關閉標準的相依性追蹤模組，請在 ASP.NET 應用程式的 ApplicationInsights.config 中移除對 DependencyTrackingTelemetryModule 的參考。針對 ASP.NET Core應用程式，請遵循適用於 ASP.NET Core 應用程式的 Application Insights中的指示。

追蹤來自網頁的 AJAX 呼叫

若為網頁，Application Insights JavaScript SDK 會自動將 AJAX 呼叫收集為相依性。

透過進階 SQL 追蹤取得完整的 SQL 查詢

注意

Azure Functions 需要個別設定以啟用 SQL 文字收集。如需詳細資訊，請參閱啟用 SQL 查詢集合。

對於 SQL 呼叫，一律會收集伺服器和資料庫的名稱，並儲存為所收集 DependencyTelemetry 的名稱。另一個稱為 data 的欄位可以包含完整的 SQL 查詢文字。

對於 ASP.NET Core 應用程式，現在必須使用下列程式碼加入 SQL Text 收集：

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

對於 ASP.NET 應用程式，會在位元組字碼檢測的輔助下收集完整的 SQL 查詢文字，這需要使用檢測引擎或使用 Microsoft.Data.SqlClient NuGet 套件，而不是 System.Data.SqlClient 程式庫。下表描述啟用完整 SQL 查詢集合的平台專用步驟。

平台	取得完整 SQL 查詢所需的步驟
Azure App Service 中的 Web Apps	在 Web 應用程式控制台中，開啟 Application Insights 窗格，然後在 .NET 下啟用 SQL 命令。
IIS 伺服器 (Azure 虛擬機器、內部部署等)	使用 Microsoft.Data.SqlClient NuGet 套件，或使用 Application Insights 代理程式 PowerShell 模組來安裝檢測引擎並重新啟動 IIS。
Azure 雲端服務	新增啟動工作以安裝 StatusMonitor。您的應用程式應在建置期間上線至 ApplicationInsights SDK，方法是安裝適用於 ASP.NET 或 ASP.NET Core 應用程式的 NuGet 套件。
IIS Express	使用 Microsoft.Data.SqlClient NuGet 套件。
Azure App Service 中的 WebJobs	使用 Microsoft.Data.SqlClient NuGet 套件。

除了上述平台專用步驟以外，您也必須使用下列程式碼修改 applicationInsights.config 檔案，以明確地選擇啟用 SQL 命令集合：

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

在上述案例中，驗證檢測引擎是否已正確安裝的正確方式，就是驗證所收集 DependencyTelemetry 的 SDK 版本是否為 rddp。使用 rdddsd 或 rddf 指出相依性是透過 DiagnosticSource 或 EventSource 回呼來收集，因此不會擷取完整的 SQL 查詢。

哪裡可以找到相依性資料

應用程式對應會以視覺化方式顯示您應用程式與相鄰元件之間的相依性。
交易診斷會顯示統一、相互關聯的伺服器資料。
瀏覽器索引標籤會顯示來自使用者瀏覽器的 AJAX 呼叫。
從速度緩慢或失敗的要求選取，以檢查其相依性呼叫。
分析可用來查詢相依性資料。

診斷速度緩慢的要求

每個要求事件都會與相依性呼叫、例外狀況及處理要求時所追蹤的其他事件相關聯。因此，如果某些要求執行效能很差，您可以了解是否是因為某個相依性的回應太慢。

進行從要求到相依性的追蹤

選取左側的 [效能] 索引標籤，然後選取頂端的 [相依性] 索引標籤。

在 [整體] 底下，選取 [相依性名稱]。在您選取相依性之後，該相依性的持續時間分佈圖會出現在右側。

選取右下方的 [範例] 按鈕。然後選取範例以查看端對端交易詳細資料。

剖析您的即時網站

Application Insights 分析工具會追蹤對您即時站台發出的 HTTP 呼叫，並顯示您程式碼中的哪些函式耗時最久。

失敗的要求

失敗的要求可能也會與失敗的相依性呼叫關聯。

選取左側的 [失敗] 索引標籤，然後選取頂端的 [相依性] 索引標籤。

在這裡您會看到失敗的相依性計數。若要取得失敗發生次數的詳細資訊，請選取底部資料表中的相依性名稱。選取右下方的 [相依性] 按鈕，以查看端對端交易詳細資料。

記錄 (Analytics)

您可以在 Kusto 查詢語言中追蹤相依性。以下列出一些範例。

尋找任何失敗的相依性呼叫：


    dependencies | where success != "True" | take 10

尋找 AJAX 呼叫︰


    dependencies | where client_Type == "Browser" | take 10

尋找與要求關聯的相依性呼叫：


    dependencies
    | where timestamp > ago(1d) and  client_Type != "Browser"
    | join (requests | where timestamp > ago(1d))
      on operation_Id

尋找與頁面檢視關聯的 AJAX 呼叫：


    dependencies
    | where timestamp > ago(1d) and  client_Type == "Browser"
    | join (browserTimings | where timestamp > ago(1d))
      on operation_Id

常見問題集

本節提供常見問題的答案。

自動相依性收集器如何報告失敗的相依性呼叫？

失敗的相依性呼叫會將 success 欄位設定為 False。模組 DependencyTrackingTelemetryModule 不會報告 ExceptionTelemetry。 Application Insights 遙測資料模型中描述了相依性的完整資料模型。

如何計算相依性遙測的擷取延遲嗎？

使用這段程式碼：

dependencies
| extend E2EIngestionLatency = ingestion_time() - timestamp 
| extend TimeIngested = ingestion_time()

如何確認相依性呼叫的起始時間？

在 Log Analytics 查詢檢視中，timestamp 代表在收到相依性呼叫回應之後立即起始 TrackDependency() 呼叫的時間。若要計算相依性呼叫的開始時間，您應取用 timestamp，並減去為相依性呼叫記錄的 duration。

Application Insights 中的相依性追蹤是否包含記錄回應主體？

Application Insights 中的相依性追蹤不包含記錄回應主體，因為它會為大多數應用程式產生過多的遙測資料。

開放原始碼 SDK

就像每個 Application Insights SDK 一樣，相依性收集模組也是開放原始碼。請在官方 GitHub 存放庫參閱程式碼及參與其製作，或回報問題。

相依性自動收集

以下是目前支援的相依性呼叫清單，系統會自動將這些呼叫偵測為相依性，而且不需要修改應用程式的任何其他程式碼。這些相依項目會在 Application Insights 中的應用程式對應和交易診斷檢視中加以視覺化。如果您的相依性不在以下清單中，您仍可以透過追蹤相依性呼叫，以手動方式進行追蹤。

.NET

應用程式架構	版本
ASP.NET WebForm	4.5+
ASP.NET MVC	4+
ASP.NET WebAPI	4.5+
ASP.NET Core	1.1+
通訊程式庫
HttpClient	4.5+、.NET Core 1.1+
SqlClient	.NET Core 1.0+、NuGet 4.3.0
Microsoft.Data.SqlClient	1.1.0 - 最新的穩定版本。 (請參閱下方注意事項。)
事件中樞用戶端 SDK	1.1.0
ServiceBus 用戶端 SDK	7.0.0
儲存體用戶端
ADO.NET	4.5+

注意

舊版 Microsoft.Data.SqlClient 有一個已知問題。建議使用 1.1.0 或更新版本來減輕此問題。 Entity Framework Core 不一定隨附 Microsoft.Data.SqlClient 的最新穩定版本，因此建議您確認自己使用的至少為 1.1.0 版，以避免此問題。

Java

請參閱 Application Insights JAVA 自動收集相依性的清單。

Node.js

最新的目前支援模組清單會留存在此處。

JavaScript

通訊程式庫	版本
XMLHttpRequest	全部

下一步

例外狀況
使用者與頁面資料
可用性
設定 Java 的自訂相依性追蹤。
設定 OpenCensus Python 的自訂相依性追蹤。
撰寫自訂相依性遙測
如需 Application Insights 類型和資料模型，請參閱資料模型。
查看 Application Insights 支援的平台。

共用方式為