使用 ApplicationInsights.config 或 .xml 設定 Application Insights SDK

發行項
01/31/2024

Application Insights .NET SDK 包含許多 NuGet 套件。核心套件提供將遙測傳送至 Application Insights 的 API。其他套件提供遙測模組和 初始化表達式 ，以自動追蹤來自您的應用程式及其內容的遙測。藉由調整組態檔，您可以啟用或停用遙測模組和初始化表達式。您也可以為其中一些參數設定參數。

注意

下列文件依賴Application Insights傳統 API。 Application Insights 的長期計劃是使用 OpenTelemetry 收集數據。如需詳細資訊，請參閱為 .NET、Node.js、Python 和 Java 應用程式啟用 Azure 監視器 OpenTelemetry。

組態檔名為 ApplicationInsights.config 或 ApplicationInsights.xml。名稱取決於您的應用程式類型。當您安裝大部分版本的 SDK 時，它會自動新增至您的專案。根據預設，當您從支援新增>Application Insights 遙測的Visual Studio樣本專案使用自動化體驗時，ApplicationInsights.config檔案會在專案根資料夾中建立。編譯時，它會複製到 bin 資料夾。它也會由 IIS 伺服器上的 Application Insights Agent 新增至 Web 應用程式。如果使用 Azure 網站的擴充功能或 Azure VM 和虛擬機擴展集的擴充功能，則會忽略組態檔。

網頁中沒有對等的檔案可控制 SDK。

本文說明您在元件檔中看到的各節、它們如何控制 SDK 的元件，以及哪些 NuGet 套件會載入這些元件。

注意

ApplicationInsights.config和 .xml指示不適用於 .NET Core SDK。若要設定 .NET Core 應用程式，請遵循 Application Insights 中適用於 ASP.NET Core 應用程式的指示。

遙測模組（ASP.NET）

每個遙測模組都會收集特定類型的數據，並使用核心 API 來傳送數據。模組是由不同的 NuGet 套件所安裝，這些套件也會將所需的幾行新增至 .config 檔案。

每個模組的組態檔中有一個節點。若要停用模組，請刪除節點或將其批注化。

相依性追蹤

相依性追蹤會收集應用程式對資料庫和外部服務和資料庫進行呼叫的相關遙測。若要允許此模組在 IIS 伺服器中運作，您需要安裝 Application Insights 代理程式。

您也可以使用 TrackDependency API 撰寫自己的相依性追蹤程式代碼。

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
Microsoft.ApplicationInsights.DependencyCollector NuGet 套件

相依性可以自動擷取，而不需使用代理程式型（無程序代碼）附加來修改程序代碼。若要在 Azure Web 應用程式中使用它，請啟用 Application Insights 擴充功能。若要在 Azure VM 或 Azure 虛擬機擴展集中使用它，請啟用 VM 和虛擬機擴展集的應用程式監視擴充功能。

效能收集器

性能收集器會從 IIS 安裝收集系統性能計數器，例如 CPU、記憶體和網路負載。您可以指定要收集的計數器，包括您已自行設定的性能計數器。

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
Microsoft.ApplicationInsights.PerfCounterCollector NuGet 套件

Application Insights 診斷遙測

類別 DiagnosticsTelemetryModule 會報告 Application Insights 檢測程式代碼本身的錯誤。例如，如果程式代碼無法存取性能計數器，或 ITelemetryInitializer 擲回例外狀況，則為。此課程模組所追蹤的追蹤遙測會出現在診斷搜尋中。

Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
Microsoft.ApplicationInsights NuGet 套件。如果您只安裝此套件，則不會自動建立 ApplicationInsights.config 檔案。

開發人員模式

類別 DeveloperModeWithDebuggerAttachedTelemetryModule 會強制 Application Insights TelemetryChannel 在調試程式附加至應用程式進程時，立即傳送一個遙測專案。此設計可減少應用程式追蹤遙測的時間，以及應用程式出現在Application Insights入口網站中的時間。這會導致 CPU 和網路頻寬的巨大額外負荷。

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
Application Insights Windows Server NuGet 套件

Web 要求追蹤

Web 要求追蹤會報告 HTTP 要求的回應時間和結果碼。

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
Microsoft.ApplicationInsights.Web NuGet 套件

例外狀況追蹤

類別會 ExceptionTrackingTelemetryModule 追蹤 Web 應用程式中未處理的例外狀況。如需詳細資訊，請參閱失敗和例外狀況。

Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
Microsoft.ApplicationInsights.Web NuGet 套件。
Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule：追蹤未追蹤的工作。異常。
Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule：追蹤背景工作角色、Windows 服務和控制台應用程式的未處理例外狀況。
Application Insights Windows Server NuGet 套件。

EventSource 追蹤

類別 EventSourceTelemetryModule 可讓您將 EventSource 事件設定為以追蹤的形式傳送至 Application Insights。如需追蹤 EventSource 事件的資訊，請參閱使用 EventSource 事件。

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft.ApplicationInsights.EventSourceListener

ETW 事件追蹤

類別 EtwCollectorTelemetryModule 可讓您將來自 ETW 提供者的事件設定為追蹤傳送至 Application Insights。如需追蹤 ETW 事件的資訊，請參閱使用 ETW 事件。

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

套件 Microsoft.ApplicationInsights 提供 SDK 的核心 API 。其他遙測模組會使用此 API。您也可以使用它來定義自己的遙測。

ApplicationInsights.config 中沒有專案。
Microsoft.ApplicationInsights NuGet 套件。如果您只安裝此 NuGet，則不會產生 .config 檔案。

遙測通道

遙測通道會管理遙測的緩衝處理和傳輸至 Application Insights 服務。

Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel 是 Web 應用程式的預設通道。它會緩衝記憶體中的數據，並採用重試機制和本機磁碟記憶體，以取得更可靠的遙測傳遞。
Microsoft.ApplicationInsights.InMemoryChannel 是輕量型遙測通道。如果未設定其他通道，則會使用它。

遙測初始化表示式（ASP.NET）

遙測初始化表達式會設定隨每個遙測專案一起傳送的內容屬性。

您可以撰寫自己的初始化運算式來設定內容屬性。

標準初始化運算式都是由 Web 或 WindowsServer NuGet 套件所設定：

AccountIdTelemetryInitializerAccountId會設定屬性。
AuthenticatedUserIdTelemetryInitializer 設定 AuthenticatedUserId JavaScript SDK 所設定的屬性。
AzureRoleEnvironmentTelemetryInitializer會RoleNameRoleInstance使用從 Azure 執行時間環境擷取的資訊，更新所有遙測專案的和內容屬性Device。
BuildInfoConfigComponentVersionTelemetryInitializer使用 Version MS Build 所產生的檔案擷取BuildInfo.config值，更新所有遙測項目的內容屬性Component。
ClientIpHeaderTelemetryInitializerIp會根據X-Forwarded-For要求的 HTTP 標頭，更新所有遙測專案內容的屬性Location。
DeviceTelemetryInitializer 會更新所有遙測項目內容的下列屬性 Device 。
- Type 設定為 PC。
- Id 設定為 Web 應用程式執行所在電腦的功能變數名稱。
- OemName 會設定為使用 WMI 從 Win32_ComputerSystem.Manufacturer 字段擷取的值。
- Model 會設定為使用 WMI 從 Win32_ComputerSystem.Model 字段擷取的值。
- NetworkType 設定為從 NetworkInterface 屬性擷取的值。
- Language 設定為屬性的名稱 CurrentCulture 。
DomainNameRoleInstanceTelemetryInitializer 會 RoleInstance 使用 Web 應用程式執行所在電腦的功能變數名稱，更新所有遙測專案的內容屬性 Device 。
OperationNameTelemetryInitializerName會根據 HTTP 方法更新和 Name 所有遙測專案內容的屬性RequestTelemetryOperation，以及叫用以處理要求之 ASP.NET MVC 控制器和動作的名稱。
OperationIdTelemetryInitializer 或 OperationCorrelationTelemetryInitializer 更新 Operation.Id 處理具有自動產生 RequestTelemetry.Id之要求時所追蹤之所有遙測項目的內容屬性。
SessionTelemetryInitializer 會 Id 更新所有遙測專案的內容屬性 Session ，其值會從 ai_session 用戶瀏覽器中執行的 JavaScript 檢測程式代碼所產生的 ApplicationInsights Cookie 擷取。
SyntheticTelemetryInitializer 或 SyntheticUserAgentTelemetryInitializer 更新 User處理綜合來源要求時所追蹤之所有遙測專案的、 Session和 Operation 內容屬性，例如可用性測試或搜尋引擎 Bot。根據預設，計量總管不會顯示綜合遙測。

識別 <Filters> 要求屬性的集合。
UserTelemetryInitializer會Id針對所有遙測專案，更新內容的內容User和AcquisitionDate屬性，其中包含從ai_user用戶瀏覽器中執行之 Application Insights JavaScript 檢測程式代碼所產生的 Cookie 擷取的值。
WebTestTelemetryInitializer 會設定來自可用性測試之 HTTP 要求的使用者標識碼、會話標識碼和綜合來源屬性。識別 <Filters> 要求屬性的集合。

針對在 Azure Service Fabric 中執行的 .NET 應用程式，您可以包含 Microsoft.ApplicationInsights.ServiceFabric NuGet 套件。此套件包含 FabricTelemetryInitializer 屬性，可將 Service Fabric 屬性新增至遙測專案。如需詳細資訊，請參閱 GitHub 頁面，以瞭解此 NuGet 套件所新增的屬性。

遙測處理器（ASP.NET）

遙測處理器可以在從 SDK 傳送至入口網站之前篩選和修改每個遙測專案。

您可以撰寫自己的遙測處理器。

自適性取樣遙測處理器（從 2.0.0-beta3）

此功能預設為啟用。如果您的應用程式傳送相當多的遙測，此處理器會移除其中一些遙測。


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

參數會提供演算法嘗試達到的目標。 SDK 的每個實例都會獨立運作。因此，如果您的伺服器是數部計算機的叢集，則遙測的實際磁碟區會據以相乘。

深入了解取樣。

固定速率取樣遙測處理器（從 2.0.0-beta1）

還有標準取樣遙測處理器（從 2.0.1 起）：


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

請參閱連接字串程式代碼範例。

InstrumentationKey

注意

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

此設定會決定您的數據出現在其中的 Application Insights 資源。一般而言，您會為每個應用程式建立具有個別索引鍵的個別資源。

例如，如果您想要動態設定金鑰，如果您想要將應用程式的結果傳送到不同的資源，則可以省略組態檔中的密鑰，並改為在程式代碼中設定密鑰。

若要設定所有實例的 TelemetryClient索引鍵，包括標準遙測模組，請在初始化方法中執行此步驟，例如 ASP.NET 服務中的global.aspx.cs：

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

如果您想要將一組特定事件傳送至不同的資源，您可以設定特定遙測用戶端的金鑰：


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

若要取得新的金鑰，請在 Application Insights 入口網站中建立新的資源。

ApplicationId 提供者

提供者可從 v2.6.0 開始提供。

此提供者的目的是要根據檢測金鑰來查閱應用程式識別碼。應用程式標識碼包含在和 DependencyTelemetry 中RequestTelemetry，用來判斷入口網站中的相互關聯。

在程式代碼或組態檔中設定 TelemetryConfiguration.ApplicationIdProvider ，即可使用這項功能。

介面：IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

我們在 Microsoft.ApplicationInsights SDK 中提供兩個實作：ApplicationInsightsApplicationIdProvider和 DictionaryApplicationIdProvider。

ApplicationInsightsApplicationIdProvider

此包裝函式適用於我們的配置檔 API。它會節流要求和快取結果。

當您安裝 Microsoft.ApplicationInsights.DependencyCollector 或 Microsoft.ApplicationInsights.Web 時，此提供者會新增至組態檔。

這個類別具有選擇性屬性 ProfileQueryEndpoint。根據預設，它會設定為 https://dc.services.visualstudio.com/api/profiles/{0}/appId。如果您需要設定這個設定的 Proxy，建議您 Proxy 基位址並包含 "/api/profiles/{0}/appId"。 {0}在每次要求執行時間以偵測金鑰取代。

透過ApplicationInsights.config的範例組態

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

透過程式代碼的範例組態

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

此靜態提供者依賴您設定的檢測金鑰/應用程式識別元組。

這個類別具有 Defined 屬性，這是 Dictionary<string,string> 檢測金鑰/應用程式識別子組的。

這個類別具有選擇性屬性 Next，可用來設定其他提供者，以在要求不存在於組態中的檢測密鑰時使用。

透過ApplicationInsights.config的範例組態

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

透過程式代碼的範例組態

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

設定 ASP.NET 應用程式的快照集集合

設定 ASP.NET 應用程式的快照集集合。

下一步

深入瞭解 API

使用 ApplicationInsights.config 或 .xml 設定 Application Insights SDK

遙測模組 （ASP.NET）

相依性追蹤

效能收集器

Application Insights 診斷遙測

開發人員模式

Web 要求追蹤

例外狀況追蹤

EventSource 追蹤

ETW 事件追蹤

Microsoft.ApplicationInsights

遙測通道

遙測初始化表示式 （ASP.NET）

遙測處理器 （ASP.NET）

自適性取樣遙測處理器（從 2.0.0-beta3）

固定速率取樣遙測處理器（從 2.0.0-beta1）

ConnectionString

InstrumentationKey

ApplicationId 提供者

介面：IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

透過ApplicationInsights.config的範例組態

透過程式代碼的範例組態

DictionaryApplicationIdProvider

透過ApplicationInsights.config的範例組態

透過程式代碼的範例組態

設定 ASP.NET 應用程式的快照集集合

下一步

其他資源

遙測模組（ASP.NET）

遙測初始化表示式（ASP.NET）

遙測處理器（ASP.NET）