使用 ApplicationInsights.config 或 .xml 配置 Application Insights SDK

项目
10/15/2024

Application Insights .NET SDK 由很多 NuGet 包组成。核心包提供 API，用于将遥测数据发送到 Application Insights。其他包提供遥测模块和初始值设定项，用于自动从应用程序及其上下文跟踪遥测。可以通过调整配置文件来启用或禁用遥测模块和初始值设定项。对于其中的一些，你还可以设置参数。

注意

以下文档依赖于 Application Insights 经典 API。 Application Insights 的长期计划是使用 OpenTelemetry 收集数据。有关详细信息，请参阅为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry 和我们的 OpenTelemetry 路线图。迁移指导适用于 .NET、Node.js 和 Python。

配置文件名称是 ApplicationInsights.config 或 ApplicationInsights.xml。该名称取决于应用程序的类型。安装大多数版本的 SDK 时，系统会自动将配置文件添加到项目。默认情况下，使用支持“添加”>“Application Insights 遥测”的 Visual Studio 模板项目提供的自动化体验时，ApplicationInsights.config 文件将在项目根文件夹中创建。在经过编译后，它将复制到 bin 文件夹。它也会由 IIS 服务器上的 Application Insights 代理添加到 Web 应用。如果使用了 Azure 网站的扩展或 Azure VM 和虚拟机规模集的扩展，则会忽略此配置文件。

没有一个等效的文件用来控制网页中的 SDK。

本文说明配置文件中显示的节、这些节如何控制 SDK 的组件，以及哪些 NuGet 包会加载这些组件。

注意

ApplicationInsights.config 和 .xml 指令不适用于 .NET Core SDK。若要配置 ASP.NET Core 应用程序，请按照适用于 ASP.NET Core 应用程序的 Application Insights 中的说明操作。

遥测模块 (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 类可配置要作为跟踪发送到 Application Insights 的 EventSource 事件。有关跟踪 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 包设置：

AccountIdTelemetryInitializer 设置 AccountId 属性。
AuthenticatedUserIdTelemetryInitializer 像 JavaScript SDK 一样设置 AuthenticatedUserId 属性。
对于包含从 Azure 运行时环境提取的信息的所有遥测项，AzureRoleEnvironmentTelemetryInitializer 将更新 Device 上下文的 RoleName 和 RoleInstance 属性。
对于包含从 MS 版本生成的 BuildInfo.config 文件提取的值的所有遥测项，BuildInfoConfigComponentVersionTelemetryInitializer 将更新 Component 上下文的 Version 属性。
ClientIpHeaderTelemetryInitializer 根据请求的 X-Forwarded-For HTTP 标头更新所有遥测项的 Location 上下文的 Ip 属性。
DeviceTelemetryInitializer 更新所有遥测项的 Device 上下文的以下属性。
- Type 设置为 PC。
- Id 设置为 Web 应用程序运行所在的计算机的域名。
- OemName 设置为使用 WMI 从 Win32_ComputerSystem.Manufacturer 字段提取的值。
- Model 设置为使用 WMI 从 Win32_ComputerSystem.Model 字段提取的值。
- NetworkType 设置为从 NetworkInterface 属性提取的值。
- Language 设置为 CurrentCulture 属性的名称。
对于包含 Web 应用程序运行所在计算机的域名的所有遥测项，DomainNameRoleInstanceTelemetryInitializer 将更新 Device 上下文的 RoleInstance 属性。
OperationNameTelemetryInitializer 根据 HTTP 方法、ASP.NET MVC 控制器的名称以及为了处理请求而调用的操作，更新所有遥测项的 RequestTelemetry 的 Name 属性，以及 Operation 上下文的 Name 属性。
OperationIdTelemetryInitializer 或 OperationCorrelationTelemetryInitializer 在处理包含自动生成的 RequestTelemetry.Id 的请求时，更新跟踪的所有遥测项的 Operation.Id 上下文属性。
对于包含从用户浏览器中运行的 ApplicationInsights JavaScript 检测代码生成的 ai_session Cookie 提取的值的所有遥测项，SessionTelemetryInitializer 将更新 Session 上下文的 Id 属性。
SyntheticTelemetryInitializer 或 SyntheticUserAgentTelemetryInitializer 在处理来自综合源（例如可用性测试或搜索引擎 Bot）的请求时，更新跟踪的所有遥测项的 User、Session 和 Operation 上下文属性。默认情况下，指标资源管理器不显示综合遥测数据。

<Filters> 设置请求的标识属性。
对于包含从用户浏览器中运行的 Application Insights JavaScript 检测代码生成的 ai_user Cookie 提取的值的所有遥测项，UserTelemetryInitializer 将更新 User 上下文的 Id 和 AcquisitionDate 属性。
WebTestTelemetryInitializer 设置用户 ID、会话 ID，以及来自可用性测试的 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 开始提供了该提供程序。

此提供程序的用途是根据检测密钥查找应用程序 ID。应用程序 ID 包含在 RequestTelemetry 和 DependencyTelemetry 中，用于在门户中确定关联。

此功能是通过在代码或配置文件中设置 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。如果需要为此配置来配置一个代理，建议为基址使用代理并包括 "/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

此静态提供程序依赖于所配置的检测密钥/应用程序 ID 对。

此类具有 Defined 属性，该属性是检测密钥/应用程序 ID 对的 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 应用程序配置快照集合

后续步骤

其他资源