一文读懂 ApplicationInsights-dotnet：基于 OpenTelemetry 的 .NET 应用性能监控终极指南
发布时间：2026/8/22 15:40:16 作者：尧图编辑部 阅读量：1,286
一文读懂 ApplicationInsights-dotnet基于 OpenTelemetry 的 .NET 应用性能监控终极指南【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet是微软官方为 .NET 应用打造的应用性能监控APMSDK负责将遥测数据发送到 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 SDKActivity / LogRecord / Metrics / Resource Detectors → Activity / Log Processors丰富、过滤、采样 → Azure Monitor Exporter转换为 Application Insights 数据模式 → Azure Monitor / Application Insights一个对新手很实用的映射关系——你调用的旧 API 背后发生了什么TrackEvent()/TrackException()/TrackTrace()→ 变成LogRecord日志TrackDependency()→ 变成出站调用的ActivityClient 类型TrackRequest()→ 变成入站请求的ActivityServer 类型TrackMetric()→ 变成 OpenTelemetryHistogram直方图 记忆技巧3.x 里链路追踪Traces对应 OpenTelemetry 的 Trace/Activity而日志追踪Application Insights 里的 traces 概念对应的是 Logs别搞混了。 第一步为你的应用选对 NuGet 包仓库按应用场景组织了多套 SDK仓库结构详见根目录AGENTS.md按你的应用类型对号入座即可你的应用类型应安装的包源码位置ASP.NET Core Web 应用Microsoft.ApplicationInsights.AspNetCoreNETCORE/src/Microsoft.ApplicationInsights.AspNetCore/Worker Service / 控制台 / 后台服务Microsoft.ApplicationInsights.WorkerServiceNETCORE/src/Microsoft.ApplicationInsights.WorkerService/经典 ASP.NET.NET FrameworkMicrosoft.ApplicationInsights.WebWEB/Src/Web/Web/任意 .NET 应用核心 APIMicrosoft.ApplicationInsightsBASE/src/Microsoft.ApplicationInsights/需要兼容 NLog 日志Microsoft.ApplicationInsights.NLogTargetLOGGING/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_STRINGappsettings.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.mdvar config TelemetryConfiguration.CreateDefault(); config.ConnectionString InstrumentationKey...;IngestionEndpointhttps://...; 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%TracesPerSecond5速率限制采样每秒最多保留 5 条链路StorageDirectory平台默认目录离线存储目录网络失败时缓存遥测EnableLiveMetricstrue门户中的 Live Metrics 实时流EnableTraceBasedLogsSamplertrue日志跟随所属链路的采样决定⚠️采样二选一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 导出器等主题本身就是一份高质量的实践手册。❓ 常见问题FAQQ3.x 和 2.x 能同时用吗不能混用。升级时应移除所有 2.x 包引用包括被其他包传递依赖引入的情况。Q本地开发时数据发到哪里只要连接字符串指向你的 Application Insights 资源本地运行的遥测同样会被采集便于开发期验证埋点是否正确。Q测试场景没有真实资源怎么办可以传入占位连接字符串例如InstrumentationKey00000000-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），仅供参考
尧图网站开发 