在 Application Insights 中探索 .NET/.NET Core 和 Python 追蹤記錄

發行項
03/20/2024

將 ASP.NET/ASP.NET Core 應用程式的診斷追蹤記錄從 ILogger、NLog、log4Net 或 System.Diagnostics.Trace 傳送至 Azure Application Insights。若為 Python 應用程式，請在適用於 Azure 監視器的 OpenCensus Python 中使用 AzureLogHandler 傳送診斷追蹤記錄。然後可以探索並搜尋這些記錄。那些記錄會與您應用程式的其他記錄檔合併。您可以使用這些記錄來識別與每個使用者要求相關聯的追蹤，並將其與其他事件和例外狀況報告相互關聯。

注意

您需要記錄擷取模組嗎？對於第三方記錄器來說，其是一個有用的配接器。但是，如果您還沒使用 NLog、log4Net 或 System.Diagnostics.Trace，請考慮直接呼叫 Application Insights TrackTrace()。

注意

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

在您的 app 上安裝記錄

在您的專案中安裝您選擇的記錄架構，這應該會在 app.config 或 web.config 中產生項目。

 <configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

設定 Application Insights 收集記錄

如果您尚未這麼做，且可選擇包含記錄收集器，請將 Application Insights 新增至您的專案。

或者，在 [方案總管] 中以滑鼠右鍵按一下您的專案，來設定 Application Insights。選取 [設定追蹤集合] 選項。

注意

沒有 Application Insights 功能表或記錄收集器選項嗎？請嘗試進行疑難排解。

手動安裝

如果 Application Insights 安裝程式不支援您的專案類型，請使用這個方法。例如假設為 Windows 桌面專案。

若您打算使用 log4Net 或 NLog，請將它安裝在您的專案中。
在 [方案總管] 中，以滑鼠右鍵按一下您的專案，然後選取 [管理 NuGet 套件]。
搜尋 Application Insights。
選取下列其中一個套件：
- ILogger：Microsoft.Extensions.Logging.ApplicationInsights
- NLog：Microsoft.ApplicationInsights.NLogTarget
- log4net：Microsoft.ApplicationInsights.Log4NetAppender
- System.Diagnostics：Microsoft.ApplicationInsights.TraceListener
- Microsoft.ApplicationInsights.DiagnosticSourceListener
- Microsoft.ApplicationInsights.EtwCollector
- Microsoft.ApplicationInsights.EventSourceListener

NuGet 套件會安裝必要的組件，並在適用的情況下修改 web.config 或 app.config。

ILogger

如需使用 Application Insights ILogger 實作搭配主控台應用程式和 ASP.NET Core 的範例，請參閱 ApplicationInsightsLoggerProvider for .NET Core ILogger 記錄。

插入診斷記錄呼叫

如果您使用 System.Diagnostics.Trace，典型的呼叫如下：

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

如果您偏好 log4net 或 NLog，請使用：

    logger.Warn("Slow response - database01");

使用 EventSource 事件

您可以將 System.Diagnostics.Tracing.EventSource 設定為要傳送至 Application Insights 作為追蹤的事件。首先，安裝 Microsoft.ApplicationInsights.EventSourceListener NuGet 套件。然後編輯 ApplicationInsights.config 檔案的 TelemetryModules 區段。

    <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

針對每個來源，您可以設定下列參數︰

Name 指定要收集的 EventSource 名稱。
層級會指定要收集的記錄層級：重大、錯誤、資訊、LogAlways、詳細資訊或警告。
Keywords (選擇性) 指定要使用的關鍵字組合整數值。

使用 DiagnosticSource 事件

您可以將 System.Diagnostics.DiagnosticSource 設定為要傳送至 Application Insights 作為追蹤的事件。首先，安裝 Microsoft.ApplicationInsights.DiagnosticSourceListener NuGet 套件。然後編輯 ApplicationInsights.config 檔案的 "TelemetryModules" 區段。

    <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

針對您想要追蹤的每個診斷來源，新增項目並將其 Name 屬性設定為您診斷來源的名稱。

使用 ETW 事件

您可以設定要傳送至 Application Insights 作為追蹤的 Windows 事件追蹤 (ETW) 事件。首先，安裝 Microsoft.ApplicationInsights.EtwCollector NuGet 套件。然後編輯 ApplicationInsights.config 檔案的 "TelemetryModules" 區段。

注意

僅在裝載 SDK 的處理序是以效能記錄使用者或系統管理員成員的身分識別執行時，才可收集 ETW 事件。

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

針對每個來源，您可以設定下列參數︰

ProviderName 是要收集的 ETW 提供者名稱。
ProviderGuid 指定要收集的 ETW 提供者 GUID。可以使用此 GUID 代替 ProviderName。
Level 設定要收集的記錄層級。其可以是 Critical、Error、Informational、LogAlways、Verbose 或 Warning。
Keywords (選擇性) 設定要使用的關鍵字組合整數值。

直接使用追蹤 API

您可以直接呼叫 Application Insights 追蹤 API。記錄配接器會使用此 API。

例如：

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

TrackTrace 的優點在於您可以將較長的資料放在訊息中。例如，您可以在該處編碼 POST 資料。

您也可以將嚴重性層級新增至訊息。就像其他遙測一樣，您可以新增屬性值，以協助篩選或搜尋不同的追蹤集。例如：

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

現在，您可以輕鬆地在交易搜尋中篩選出與特定資料庫相關且具有特定嚴重性層級的所有訊息。

適用於 OpenCensus Python 的 AzureLogHandler

Azure 監視器記錄處理常式可讓您將 Python 記錄匯出至 Azure 監視器。

使用適用於 Azure 監視器的 OpenCensus Python SDK 檢測您的應用程式。

這個範例示範如何將警告層級的記錄檔傳送至 Azure 監視器。

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>'))
logger.warning('Hello, World!')

探索記錄

在偵錯模式中執行應用程式或即時部署應用程式。

在 Application Insights 入口網站的應用程式概觀窗格中，選取 [交易搜尋]。

例如，您可以：

篩選記錄追蹤，或具有特定屬性的項目。
詳細檢查特定項目。
尋找與相同使用者要求 (具有相同的作業識別碼) 相關的其他系統記錄檔資料。
將頁面的組態儲存為我的最愛。

注意

如果您的應用程式傳送大量資料，且您是使用 Application Insights SDK for ASP.NET 版本 2.0.0-beta3 或更新版本，則調適型取樣功能可能會運作，並只傳送一部分的遙測資料。深入了解取樣。

疑難排解

尋找常見問題的解答。

造成延遲遙測、多載網路，以及傳輸效率不佳的原因為何？

System.Diagnostics.Tracing 具有自動排清功能。此功能會導致 SDK 對每個遙測項目都進行不必要的排清，並可能導致如延遲遙測、多載網路、傳輸效率不佳等記錄配接器的問題。

如果是 Java，我要怎麼做？

在 JAVA 無程式碼檢測 (建議動作) 中，會立即收集記錄。請使用 JAVA 3.0 代理程式。

Application Insights JAVA 代理程式會從 Log4j、Logback 和 java.util.logging 立即收集記錄。

確定已在開發電腦上安裝 Developer Analytics Tools。在 Visual Studio 中，移至 [工具]>[擴充功能和更新]，然後尋找 Developer Analytics Tools。如果其不在 [已安裝] 索引標籤上，請開啟 [線上] 索引標籤並加以安裝。
這可能是 Developer Analytics Tools 不支援的專案類型。請使用手動安裝。

為什麼組態工具中沒有記錄配接器選項？

請先安裝記錄架構。
如果您是使用 System.Diagnostics.Trace，請確定您已將其設定在 web.config 中。
確定您有最新版的 Application Insights。在 Visual Studio 中，移至 [工具]>[擴充功能和更新]，然後開啟 [更新] 索引標籤。如果發現 Developer Analytics Tools，請選取以進行更新。

為什麼我收到「檢測金鑰不能是空白」的錯誤訊息？

您可能已安裝記錄配接器 NuGet 套件，但未安裝 Application Insights。在 [方案總管] 中，以滑鼠右鍵按一下 ApplicationInsights.config，然後選取 [更新 Application Insights]。這時會提示您登入 Azure，並建立 Application Insights 資源或重複使用現有的資源。這應該可修正問題。

為什麼我可以在診斷搜尋中看見追蹤，但是看不到其他事件？

可能需要一段時間，所有事件和要求才會通過管線。

保留多少資料？

有好幾個因素會影響保留的資料量。如需詳細資訊，請參閱客戶事件計量頁面的限制區段。

為什麼我看不到我預期的一些記錄項目？

也許是您的應用程式傳送大量資料，且您是使用 Application Insights SDK for ASP.NET 版本 2.0.0-beta3 或更新版本。在此情況下，調適型取樣功能可能會運作，並只傳送一部分的遙測。深入了解取樣。