一文读懂 ApplicationInsights-dotnet：基于 OpenTelemetry 的 .NET 应用性能监控终极指南-平芜编程栈

一文读懂 ApplicationInsights-dotnet：基于 OpenTelemetry 的 .NET 应用性能监控终极指南

【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet

ApplicationInsights-dotnet是微软官方为 .NET 应用打造的应用性能监控（APM）SDK，负责将遥测数据发送到 Azure Monitor 与 Application Insights。自 3.x 版本起，它全面重构为基于 OpenTelemetry的遥测采集框架，并配合 Azure Monitor Exporter 完成数据传输——让 .NET 开发者既能保留熟悉的TelemetryClientAPI，又能无缝融入 OpenTelemetry 生态，向多个后端发送遥测数据。

无论你是第一次给 ASP.NET Core 网站加监控，还是要从 2.x 升级到 3.x，这篇文章都能帮你 10 分钟上手。

🔍 为什么你需要 ApplicationInsights-dotnet？

上线后"应用为什么慢？哪个接口在报错？用户卡在哪一步？"——这些问题的答案都藏在遥测数据里。ApplicationInsights-dotnet 帮你自动采集五大类数据：

数据类型	说明	典型场景
Traces（追踪）	分布式调用链	一次请求经过的每个环节耗时
Metrics（指标）	数值型度量	请求耗时、队列长度
Logs（日志）	日志记录	异常堆栈、诊断信息
Requests（请求）	入站 HTTP 请求	接口的成功率和响应时间
Dependencies（依赖）	出站调用	数据库、HTTP API、队列调用

3.x 版本的三大核心优势：

⚙️Built on OpenTelemetry：以 OpenTelemetry 为底层采集框架，行业标准、不绑定单一厂商
🧩OpenTelemetry 扩展性：可用 Activity Processor、Resource Detector 等标准模式扩展采集
🌐统一可观测性：同一份数据可以同时发往多个监控后端

🏗️ 3.x 新架构：遥测数据是如何流动的？

理解架构是选对扩展方式的前提。整个数据流自底向上分为五层（详见 docs/concepts.md 中的概念文档，文件路径为docs/concepts.md）：

你的应用代码 → TelemetryClient API（兼容层，翻译为 OpenTelemetry 原语） → OpenTelemetry SDK（Activity / LogRecord / Metrics / Resource Detectors） → Activity / Log Processors（丰富、过滤、采样） → Azure Monitor Exporter（转换为 Application Insights 数据模式） → Azure Monitor / Application Insights

一个对新手很实用的映射关系——你调用的旧 API 背后发生了什么：

TrackEvent()/TrackException()/TrackTrace()→ 变成LogRecord（日志）
TrackDependency()→ 变成出站调用的Activity（Client 类型）
TrackRequest()→ 变成入站请求的Activity（Server 类型）
TrackMetric()→ 变成 OpenTelemetryHistogram（直方图）

💡 记忆技巧：3.x 里"链路追踪"（Traces）对应 OpenTelemetry 的 Trace/Activity，而"日志追踪"（Application Insights 里的 traces 概念）对应的是 Logs，别搞混了。

📦 第一步：为你的应用选对 NuGet 包

仓库按应用场景组织了多套 SDK（仓库结构详见根目录AGENTS.md），按你的应用类型对号入座即可：

你的应用类型	应安装的包	源码位置
ASP.NET Core Web 应用	`Microsoft.ApplicationInsights.AspNetCore`	`NETCORE/src/Microsoft.ApplicationInsights.AspNetCore/`
Worker Service / 控制台 / 后台服务	`Microsoft.ApplicationInsights.WorkerService`	`NETCORE/src/Microsoft.ApplicationInsights.WorkerService/`
经典 ASP.NET（.NET Framework）	`Microsoft.ApplicationInsights.Web`	`WEB/Src/Web/Web/`
任意 .NET 应用（核心 API）	`Microsoft.ApplicationInsights`	`BASE/src/Microsoft.ApplicationInsights/`
需要兼容 NLog 日志	`Microsoft.ApplicationInsights.NLogTarget`	`LOGGING/src/NLogTarget/`

怎么选？Web 应用首选 AspNetCore 包（自动插桩最全面）；后台服务用 WorkerService 包（配置最简）；只做自定义埋点则基础包Microsoft.ApplicationInsights足够。

🚀 快速上手：ASP.NET Core 三步接入

这是最常用的场景，只需三步：

第 1 步：安装 NuGet 包

dotnet add package Microsoft.ApplicationInsights.AspNetCore

第 2 步：在 Program.cs 中注册遥测

builder.Services.AddApplicationInsightsTelemetry();

第 3 步：配置连接字符串（三种方式任选其一，优先级从高到低）：

代码中设置options.ConnectionString
环境变量APPLICATIONINSIGHTS_CONNECTION_STRING
appsettings.json中的ApplicationInsights:ConnectionString配置节

连接字符串在 Azure 门户的 Application Insights 资源"概览"页即可复制。注意：3.x 不再支持仅填 InstrumentationKey，必须使用包含IngestionEndpoint的完整连接字符串（迁移细节见MigrationGuidance.md）。

接入后，ASP.NET Core 包会自动帮你采集：入站 HTTP 请求追踪、HttpClient出站调用追踪、SqlClient数据库查询追踪、标准性能指标，以及所有Microsoft.Extensions.Logging的日志——几乎零代码就拥有了完整的可观测性。

⚙️ Worker Service 与后台任务：同样简单

后台服务使用AddApplicationInsightsTelemetryWorkerService()扩展方法即可启用（文档见NETCORE/WorkerService.md），与 ASP.NET Core 版本的差异只在于：没有入站请求追踪，其余能力（HttpClient/SQL 插桩、标准指标、日志采集、Live Metrics 实时流）完全一致。

仓库内置了 7 个可直接运行的示例项目（examples/目录），推荐从这几个入手：

examples/AspNetCoreWebApp/—— 标准 MVC 网站示例
examples/WorkerService/—— 后台服务示例
examples/BasicConsoleApp/—— 基础包 +TelemetryClient手动埋点示例（含事件、指标、异常追踪的完整用法）

📝 手动埋点：TelemetryClient 核心 API

自动采集覆盖不了业务语义时，用TelemetryClient补充自定义遥测。核心用法（完整示例见BASE/README.md）：

var config = TelemetryConfiguration.CreateDefault(); config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=https://..."; var telemetryClient = new TelemetryClient(config); telemetryClient.TrackEvent("UserLoggedIn"); // 业务事件 telemetryClient.TrackMetric("QueueLength", 42); // 自定义指标 telemetryClient.TrackTrace("Processing started"); // 诊断日志 telemetryClient.TrackException(ex); // 异常追踪

几个新手要点：

应用退出前调用telemetryClient.Flush()，确保批量缓冲的遥测全部发出（控制台应用尤其重要）
事件属性是字符串字典，数值需转字符串后放入
3.x 中TelemetryClient是兼容层（shim），新代码更推荐直接用 OpenTelemetry API
需要关闭全部遥测时，在创建第一个TelemetryClient之前设置configuration.DisableTelemetry = true

🎛️ 高级配置：采样、存储与自定义处理器

TelemetryConfiguration控制 SDK 行为，最常被调用的几个开关：

属性	默认值	作用
`SamplingRatio`	无	百分比采样（如 0.5 = 保留 50%）
`TracesPerSecond`	5	速率限制采样（每秒最多保留 5 条链路）
`StorageDirectory`	平台默认目录	离线存储目录，网络失败时缓存遥测
`EnableLiveMetrics`	true	门户中的 Live Metrics 实时流
`EnableTraceBasedLogsSampler`	true	日志跟随所属链路的采样决定

⚠️采样二选一：SamplingRatio（按比例）和TracesPerSecond（按速率）只能配一个，别同时设置。

用 OpenTelemetry 扩展采集

这是 3.x 相对 2.x 最大的能力升级——通过ConfigureOpenTelemetryBuilder()接入标准 OpenTelemetry 扩展点：

自定义 ActivitySource：在业务代码里用ActivitySource.StartActivity()创建自定义链路段，再用tracing.AddSource("MyApp.*")按通配符注册，数据会自动出现在 Application Insights 的依赖/请求视图中
Activity Processor：替代 2.x 的ITelemetryInitializer，用于丰富（打标签）或过滤（丢弃健康检查等噪音请求）遥测
Log Processor：对日志类遥测做同样的丰富与过滤
Resource Detector：在启动时探测运行环境（Azure App Service、VM、Container Apps 等），注入service.name、service.version等资源属性；SDK 已内置 Azure 环境检测器（源码见NETCORE/src/Shared/Vendoring/OpenTelemetry.Resources.Azure/）
多后端导出：再加一个 Exporter，同一份遥测即可同时发往其他监控系统

🔄 从 2.x 迁移到 3.x：你需要知道的变化

升级 3.x 前，建议通读MigrationGuidance.md（迁移指南）和BreakingChanges.md（破坏性变更清单）。核心变化有四点：

删除大量 2.x 包：WindowsServer.TelemetryChannel、DependencyCollector、PerfCounterCollector、EventCounterCollector等共 10 个包不再支持，其能力已内置到 3.x 包中，升级时直接移除引用即可
InstrumentationKey 全面退役：改为完整的 ConnectionString，否则运行时会抛异常
Telemetry Modules / Initializers 移除：用 OpenTelemetry Processor 和 Resource Detector 替代
创建配置改用TelemetryConfiguration.CreateDefault()

好消息是Track*系列 API 全部保留，绝大多数业务埋点代码可以不改；真正的改动集中在初始化和扩展层。

🤖 新玩法：让 AI 帮你完成接入

仓库内置了一个可移植的 AI 技能包（skills/applicationinsights-setup/），支持 Claude Code、Cursor、GitHub Copilot、Codex 等主流 AI 编程代理。把它复制到你的代理技能目录后，只需对 AI 说"给我的应用加上 Application Insights"，它会自动：

检测你的应用类型（ASP.NET Core / Worker Service / 经典 ASP.NET / 控制台）
识别现有的 2.x 埋点代码并给出逐步迁移方案
指导追加 Entity Framework、Redis、SQL、OTLP 等增强项

技能包内附 20 多个参考文档（skills/applicationinsights-setup/references/），覆盖自定义指标、HTTP 插桩、采样迁移、OTLP 导出器等主题，本身就是一份高质量的实践手册。

❓ 常见问题（FAQ）

Q：3.x 和 2.x 能同时用吗？不能混用。升级时应移除所有 2.x 包引用，包括被其他包传递依赖引入的情况。

Q：本地开发时数据发到哪里？只要连接字符串指向你的 Application Insights 资源，本地运行的遥测同样会被采集，便于开发期验证埋点是否正确。

Q：测试场景没有真实资源怎么办？可以传入占位连接字符串，例如InstrumentationKey=00000000-0000-0000-0000-000000000000。

Q：性能开销大吗？3.x 默认采用速率限制采样（默认 5 traces/秒），且导出器自带批量机制，对绝大多数应用性能影响可忽略。

📚 学习路线图

按这个顺序探索仓库，效率最高：

根目录Readme.md—— 总览与快速开始
docs/concepts.md—— 核心概念与 OpenTelemetry 架构
NETCORE/Readme.md与NETCORE/WorkerService.md—— 两种主场景的完整配置
examples/下对应你的应用类型的示例
troubleshooting/—— 常见问题排查（含 ETW 与数据投递工具）

ApplicationInsights-dotnet 3.x 让 .NET 应用性能监控从"装一堆采集包"变成"接一条标准 OpenTelemetry 流水线"——熟悉的TelemetryClient继续可用，标准的 OpenTelemetry 能力全部打开。现在就可以复制你的应用类型对应的示例项目，开始第一次遥测之旅。🎉

【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考