使用 ApplicationInsights.config 或 .xml 配置 Application Insights SDK
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
此设置确定显示数据的 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 应用程序配置快照集合。