ApplicationInsights-dotnet 从 2.x 升级到 3.x 完整指南OpenTelemetry 架构迁移全解析【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet是 .NET 应用接入 Azure Monitor / Application Insights 的官方 SDK。从2.x 升级到 3.x是一次架构级迁移底层全面改用OpenTelemetry Azure Monitor Exporter发送遥测数据。本文用一份清单式指南帮你快速掌握升级中的每个关键变化少走弯路。一、3.x 和 2.x 到底有什么本质区别一句话概括2.x 是自研管线3.x 是标准底座。对比项2.x3.x遥测管线自定义处理器 / 初始化器 / 通道OpenTelemetry SDK数据发送TelemetryChannelAzure Monitor Exporter内置批处理与离线存储分布式追踪自研关联机制W3C TraceContext 原生支持扩展方式ITelemetryProcessor / ITelemetryInitializerOpenTelemetry Processor包数量10 个辅助包精简为 5 个核心包3.x 架构分层如下完整说明见概念文档docs/concepts.md你的应用代码 ↓ TelemetryClient API兼容层 OpenTelemetry SDKActivity / LogRecord / Metrics ↓ Processors富化、过滤、采样 Azure Monitor Exporter ↓ Azure Monitor / Application Insights 好消息3.x 保留了大部分 2.x 的公共 API如TrackEvent、TrackException属于平滑兼容层你的业务代码大部分不用动主要工作在依赖和配置。3.0 发布的 5 个核心包Microsoft.ApplicationInsights核心 SDKMicrosoft.ApplicationInsights.AspNetCoreMicrosoft.ApplicationInsights.WorkerServiceMicrosoft.ApplicationInsights.NLogTargetMicrosoft.ApplicationInsights.Web经典 ASP.NET二、迁移前必做三步准备清单⚠️最重要的一条2.x 和 3.x 的包不能混用应用中所有 Application Insights 相关包必须一次性全部升级到 3.x同时清理传递依赖。✅ 第 1 步删除 2.x 遗留包以下包在 3.x 中不再支持升级时必须从项目中移除待删除的 2.x 包3.x 中的替代方式WindowsServer.TelemetryChannel内置 Azure Monitor Exporter 自动完成DependencyCollector各包内置自动依赖采集PerfCounterCollector自动采集性能计数器可配置关闭WindowsServer资源检测器 开关属性替代Extensions.Logging.ApplicationInsights自动采集 ILogger 日志无需此包DiagnosticSourceListener/EventSourceListener内置 HTTP/SQL 自动插桩Log4NetAppender/TraceListener已停更改用TrackTrace()或 ILogger✅ 第 2 步准备连接字符串ConnectionStringInstrumentationKey 单独配置的方式被彻底移除。3.x 要求提供完整连接字符串其中包含端点信息且不提供连接字符串会直接抛异常。测试场景可用占位值InstrumentationKey00000000-0000-0000-0000-000000000000✅ 第 3 步确认目标框架版本Microsoft.ApplicationInsights.Web和Microsoft.ApplicationInsights.NLogTarget的最低框架要求提升.NET Framework4.5.2 → 4.6.2netstandard2.0目标被net8.0取代三、连接字符串配置四种应用类型的最快方法升级后最常见的报错就是缺少连接字符串。按你的应用类型选择对应配置方式 ASP.NET Core / Worker Service推荐通过环境变量或配置文件注入代码示例详见MigrationGuidance.md// appsettings.json { ApplicationInsights: { ConnectionString: InstrumentationKeyxxx;IngestionEndpointhttps://... } }也可以设置环境变量APPLICATIONINSIGHTS_CONNECTION_STRING两个包会自动读取。 核心 SDKTelemetryConfigurationvar config TelemetryConfiguration.CreateDefault(); config.ConnectionString InstrumentationKeyxxx;IngestionEndpointhttps://...; var client new TelemetryClient(config);注意TelemetryConfiguration.Active和new TelemetryClient()无参构造已被移除CreateDefault()是唯一推荐入口。 经典 ASP.NETWeb在applicationinsights.config中把InstrumentationKey替换为ConnectionStringInstrumentationKeyxxx;IngestionEndpointhttps://.../ConnectionString NLognlog.config中的InstrumentationKey属性改为connectionString属性即可。四、高频破坏性变更速查表升级时编译器报错最多的 API 都在这里完整列表见BreakingChanges.md变更2.x 用法3.x 迁移方案无参构造函数new TelemetryClient()new TelemetryClient(config)InstrumentationKey 属性config.InstrumentationKey ...config.ConnectionString ...TrackEvent 指标参数TrackEvent(name, props, metrics)移除 metrics 参数改用TrackMetric()单独上报GetMetric 重载带MetricConfiguration参数参数简化聚合由 OpenTelemetry 内部管理TrackPageView支持完全移除用TrackEvent或TrackRequest替代遥测采样处理器SamplingTelemetryProcessor等见下文采样配置章节通道 ITelemetryChannel内存/服务器通道移除由 Exporter 内置批处理与磁盘持久化指标命名新规范3.x 的TrackMetric/GetMetric指标名必须符合 OpenTelemetry 命名语法——首字符必须是字母后续只能包含字母、数字、_、.、-、/最长 255 字符。含空格、$等非法字符的旧指标名必须在迁移前重命名。五、采样配置去哪了两个新属性替代三种旧处理器2.x 的固定采样和自适应采样处理器全部移除3.x 用两个属性统一替代TracesPerSecond速率限制采样限制每秒发送的追踪数3.x 的默认采样模式SamplingRatio固定比例采样0.0 ~ 1.0设为 1.0 表示全量发送设置后覆盖速率限制模式EnableTraceBasedLogsSampler默认 true日志跟随其所属追踪的采样决策追踪被丢弃时日志一并丢弃// 方式一速率限制默认行为 configuration.TracesPerSecond 5; // 方式二固定比例25% 采样 configuration.SamplingRatio 0.25f;这些属性在TelemetryConfiguration、ApplicationInsightsServiceOptions、applicationinsights.config和appsettings.json中均可配置。⚠️注意3.x 不再支持按遥测类型分别设置采样例如异常全量、请求 25%采样决策统一作用于所有追踪遥测。六、自定义扩展迁移Initializer 和 Processor 的替代方案这是迁移中最考验功力的部分2.x 的三大扩展点都换成了 OpenTelemetry 概念 ITelemetryInitializer → 资源检测器 / Activity Processor大部分内置初始化器已被内部资源检测器或自动插桩接管无需手动处理如OperationCorrelationTelemetryInitializer、OperationNameTelemetryInitializer原来想给每条遥测加属性的场景最简单的替代是全局属性client.Context.GlobalProperties[MyCustomKey] MyCustomValue;更复杂的富化/过滤需求请编写OpenTelemetry Processor并通过ConfigureOpenTelemetryBuilder注册注册写法差异详见MigrationGuidance.md的TelemetryProcessors章节 ITelemetryProcessor → OpenTelemetry Processor处理器按注册顺序执行。核心 SDK 用configuration.ConfigureOpenTelemetryBuilder(...)注册AspNetCore/WorkerService 用builder.Services.ConfigureOpenTelemetryTracerProvider(...)注册。 ITelemetryChannel / TelemetrySinks → OpenTelemetry Exporter磁盘持久化通过StorageDirectory配置离线存储目录DisableOfflineStorage可完全关闭测试场景改用 OpenTelemetry 的 InMemory Exporter需要发到多个后端安装对应的 OpenTelemetry Exporter 包通过 builder 追加即可⚠️ 两个容易踩的坑ILogger.BeginScope的作用域属性默认不生效3.x 中 logging scope 默认被禁用需要显式开启IncludeScopes否则作用域值会被静默丢弃。Context 对指标不生效TelemetryClient.Context设置的属性只应用于追踪和日志Request、Dependency、Trace、Event、Exception、AvailabilityMetrics 不会被富化。七、迁移完成后验证与排错✅验证清单全局搜索确认无残留的 2.x 包引用含传递依赖确认所有环境开发/测试/生产都已配置连接字符串检查指标名是否符合 OpenTelemetry 命名规范在 Azure 门户的实时度量中确认数据流正常排查应用日志中是否有属性静默丢弃BeginScope 场景排错资源均在仓库内路径为相对仓库根目录troubleshooting/Readme.md— 常见问题总入口含自诊断日志开关说明troubleshooting/ETW/Readme.md— ETW 追踪工具说明troubleshooting/Ingestion/PostTelemetry.ps1— 手动投递遥测的脚本docs/concepts.md— OpenTelemetry 核心概念与架构详解MigrationGuidance.md/BreakingChanges.md— 官方完整迁移指南与破坏性变更清单skills/applicationinsights-setup/— 项目内置的 AI 辅助迁移技能可配合 AI 编码代理完成自动检测与升级 小建议升级前先阅读MigrationGuidance.md中与你在用的包对应的章节文档按 5 个包分节组织把移除 → 配置连接串 → 替换扩展点 → 验证四步走下来绝大多数 2.x 项目可以在半天内完成 3.x 升级。八、常见问题FAQQ1可以只升级部分包到 3.x 吗不行。2.x 与 3.x 包混用不受支持必须整体升级。Q2升级后数据量明显变多了3.x 自动采集了 HTTP 服务端/客户端指标.NET 8 使用运行时内置 Meter如果不需要可用 OpenTelemetry View 丢弃对应的 instrument写法见MigrationGuidance.md的Autocollected Metrics章节。Q3DeveloperMode 没了怎么办3.x 的批处理由 Exporter 内部管理测试场景直接用TelemetryClient.Flush()即可。Q4AAD 认证支持吗支持。通过SetAzureTokenCredential(TokenCredential)方法或选项中的Credential属性启用。Q5经典 ASP.NET 的 applicationinsights.config 怎么改删掉TelemetryInitializers和TelemetryModules整个区块3.x 不再支持InstrumentationKey换成ConnectionString其余内置模块会自动启用 OpenTelemetry 插桩。总结ApplicationInsights-dotnet 3.x 的升级本质是换底座、精简 API、拥抱 OpenTelemetry。抓住三条主线——统一升级所有包、全面改用连接字符串、用 OpenTelemetry 概念替换旧扩展点——再配合本文第五、六章的对照表就能顺利完成这次架构迁移。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ApplicationInsights-dotnet 从 2.x 升级到 3.x 完整指南：OpenTelemetry 架构迁移全解析
ApplicationInsights-dotnet 从 2.x 升级到 3.x 完整指南OpenTelemetry 架构迁移全解析【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet是 .NET 应用接入 Azure Monitor / Application Insights 的官方 SDK。从2.x 升级到 3.x是一次架构级迁移底层全面改用OpenTelemetry Azure Monitor Exporter发送遥测数据。本文用一份清单式指南帮你快速掌握升级中的每个关键变化少走弯路。一、3.x 和 2.x 到底有什么本质区别一句话概括2.x 是自研管线3.x 是标准底座。对比项2.x3.x遥测管线自定义处理器 / 初始化器 / 通道OpenTelemetry SDK数据发送TelemetryChannelAzure Monitor Exporter内置批处理与离线存储分布式追踪自研关联机制W3C TraceContext 原生支持扩展方式ITelemetryProcessor / ITelemetryInitializerOpenTelemetry Processor包数量10 个辅助包精简为 5 个核心包3.x 架构分层如下完整说明见概念文档docs/concepts.md你的应用代码 ↓ TelemetryClient API兼容层 OpenTelemetry SDKActivity / LogRecord / Metrics ↓ Processors富化、过滤、采样 Azure Monitor Exporter ↓ Azure Monitor / Application Insights 好消息3.x 保留了大部分 2.x 的公共 API如TrackEvent、TrackException属于平滑兼容层你的业务代码大部分不用动主要工作在依赖和配置。3.0 发布的 5 个核心包Microsoft.ApplicationInsights核心 SDKMicrosoft.ApplicationInsights.AspNetCoreMicrosoft.ApplicationInsights.WorkerServiceMicrosoft.ApplicationInsights.NLogTargetMicrosoft.ApplicationInsights.Web经典 ASP.NET二、迁移前必做三步准备清单⚠️最重要的一条2.x 和 3.x 的包不能混用应用中所有 Application Insights 相关包必须一次性全部升级到 3.x同时清理传递依赖。✅ 第 1 步删除 2.x 遗留包以下包在 3.x 中不再支持升级时必须从项目中移除待删除的 2.x 包3.x 中的替代方式WindowsServer.TelemetryChannel内置 Azure Monitor Exporter 自动完成DependencyCollector各包内置自动依赖采集PerfCounterCollector自动采集性能计数器可配置关闭WindowsServer资源检测器 开关属性替代Extensions.Logging.ApplicationInsights自动采集 ILogger 日志无需此包DiagnosticSourceListener/EventSourceListener内置 HTTP/SQL 自动插桩Log4NetAppender/TraceListener已停更改用TrackTrace()或 ILogger✅ 第 2 步准备连接字符串ConnectionStringInstrumentationKey 单独配置的方式被彻底移除。3.x 要求提供完整连接字符串其中包含端点信息且不提供连接字符串会直接抛异常。测试场景可用占位值InstrumentationKey00000000-0000-0000-0000-000000000000✅ 第 3 步确认目标框架版本Microsoft.ApplicationInsights.Web和Microsoft.ApplicationInsights.NLogTarget的最低框架要求提升.NET Framework4.5.2 → 4.6.2netstandard2.0目标被net8.0取代三、连接字符串配置四种应用类型的最快方法升级后最常见的报错就是缺少连接字符串。按你的应用类型选择对应配置方式 ASP.NET Core / Worker Service推荐通过环境变量或配置文件注入代码示例详见MigrationGuidance.md// appsettings.json { ApplicationInsights: { ConnectionString: InstrumentationKeyxxx;IngestionEndpointhttps://... } }也可以设置环境变量APPLICATIONINSIGHTS_CONNECTION_STRING两个包会自动读取。 核心 SDKTelemetryConfigurationvar config TelemetryConfiguration.CreateDefault(); config.ConnectionString InstrumentationKeyxxx;IngestionEndpointhttps://...; var client new TelemetryClient(config);注意TelemetryConfiguration.Active和new TelemetryClient()无参构造已被移除CreateDefault()是唯一推荐入口。 经典 ASP.NETWeb在applicationinsights.config中把InstrumentationKey替换为ConnectionStringInstrumentationKeyxxx;IngestionEndpointhttps://.../ConnectionString NLognlog.config中的InstrumentationKey属性改为connectionString属性即可。四、高频破坏性变更速查表升级时编译器报错最多的 API 都在这里完整列表见BreakingChanges.md变更2.x 用法3.x 迁移方案无参构造函数new TelemetryClient()new TelemetryClient(config)InstrumentationKey 属性config.InstrumentationKey ...config.ConnectionString ...TrackEvent 指标参数TrackEvent(name, props, metrics)移除 metrics 参数改用TrackMetric()单独上报GetMetric 重载带MetricConfiguration参数参数简化聚合由 OpenTelemetry 内部管理TrackPageView支持完全移除用TrackEvent或TrackRequest替代遥测采样处理器SamplingTelemetryProcessor等见下文采样配置章节通道 ITelemetryChannel内存/服务器通道移除由 Exporter 内置批处理与磁盘持久化指标命名新规范3.x 的TrackMetric/GetMetric指标名必须符合 OpenTelemetry 命名语法——首字符必须是字母后续只能包含字母、数字、_、.、-、/最长 255 字符。含空格、$等非法字符的旧指标名必须在迁移前重命名。五、采样配置去哪了两个新属性替代三种旧处理器2.x 的固定采样和自适应采样处理器全部移除3.x 用两个属性统一替代TracesPerSecond速率限制采样限制每秒发送的追踪数3.x 的默认采样模式SamplingRatio固定比例采样0.0 ~ 1.0设为 1.0 表示全量发送设置后覆盖速率限制模式EnableTraceBasedLogsSampler默认 true日志跟随其所属追踪的采样决策追踪被丢弃时日志一并丢弃// 方式一速率限制默认行为 configuration.TracesPerSecond 5; // 方式二固定比例25% 采样 configuration.SamplingRatio 0.25f;这些属性在TelemetryConfiguration、ApplicationInsightsServiceOptions、applicationinsights.config和appsettings.json中均可配置。⚠️注意3.x 不再支持按遥测类型分别设置采样例如异常全量、请求 25%采样决策统一作用于所有追踪遥测。六、自定义扩展迁移Initializer 和 Processor 的替代方案这是迁移中最考验功力的部分2.x 的三大扩展点都换成了 OpenTelemetry 概念 ITelemetryInitializer → 资源检测器 / Activity Processor大部分内置初始化器已被内部资源检测器或自动插桩接管无需手动处理如OperationCorrelationTelemetryInitializer、OperationNameTelemetryInitializer原来想给每条遥测加属性的场景最简单的替代是全局属性client.Context.GlobalProperties[MyCustomKey] MyCustomValue;更复杂的富化/过滤需求请编写OpenTelemetry Processor并通过ConfigureOpenTelemetryBuilder注册注册写法差异详见MigrationGuidance.md的TelemetryProcessors章节 ITelemetryProcessor → OpenTelemetry Processor处理器按注册顺序执行。核心 SDK 用configuration.ConfigureOpenTelemetryBuilder(...)注册AspNetCore/WorkerService 用builder.Services.ConfigureOpenTelemetryTracerProvider(...)注册。 ITelemetryChannel / TelemetrySinks → OpenTelemetry Exporter磁盘持久化通过StorageDirectory配置离线存储目录DisableOfflineStorage可完全关闭测试场景改用 OpenTelemetry 的 InMemory Exporter需要发到多个后端安装对应的 OpenTelemetry Exporter 包通过 builder 追加即可⚠️ 两个容易踩的坑ILogger.BeginScope的作用域属性默认不生效3.x 中 logging scope 默认被禁用需要显式开启IncludeScopes否则作用域值会被静默丢弃。Context 对指标不生效TelemetryClient.Context设置的属性只应用于追踪和日志Request、Dependency、Trace、Event、Exception、AvailabilityMetrics 不会被富化。七、迁移完成后验证与排错✅验证清单全局搜索确认无残留的 2.x 包引用含传递依赖确认所有环境开发/测试/生产都已配置连接字符串检查指标名是否符合 OpenTelemetry 命名规范在 Azure 门户的实时度量中确认数据流正常排查应用日志中是否有属性静默丢弃BeginScope 场景排错资源均在仓库内路径为相对仓库根目录troubleshooting/Readme.md— 常见问题总入口含自诊断日志开关说明troubleshooting/ETW/Readme.md— ETW 追踪工具说明troubleshooting/Ingestion/PostTelemetry.ps1— 手动投递遥测的脚本docs/concepts.md— OpenTelemetry 核心概念与架构详解MigrationGuidance.md/BreakingChanges.md— 官方完整迁移指南与破坏性变更清单skills/applicationinsights-setup/— 项目内置的 AI 辅助迁移技能可配合 AI 编码代理完成自动检测与升级 小建议升级前先阅读MigrationGuidance.md中与你在用的包对应的章节文档按 5 个包分节组织把移除 → 配置连接串 → 替换扩展点 → 验证四步走下来绝大多数 2.x 项目可以在半天内完成 3.x 升级。八、常见问题FAQQ1可以只升级部分包到 3.x 吗不行。2.x 与 3.x 包混用不受支持必须整体升级。Q2升级后数据量明显变多了3.x 自动采集了 HTTP 服务端/客户端指标.NET 8 使用运行时内置 Meter如果不需要可用 OpenTelemetry View 丢弃对应的 instrument写法见MigrationGuidance.md的Autocollected Metrics章节。Q3DeveloperMode 没了怎么办3.x 的批处理由 Exporter 内部管理测试场景直接用TelemetryClient.Flush()即可。Q4AAD 认证支持吗支持。通过SetAzureTokenCredential(TokenCredential)方法或选项中的Credential属性启用。Q5经典 ASP.NET 的 applicationinsights.config 怎么改删掉TelemetryInitializers和TelemetryModules整个区块3.x 不再支持InstrumentationKey换成ConnectionString其余内置模块会自动启用 OpenTelemetry 插桩。总结ApplicationInsights-dotnet 3.x 的升级本质是换底座、精简 API、拥抱 OpenTelemetry。抓住三条主线——统一升级所有包、全面改用连接字符串、用 OpenTelemetry 概念替换旧扩展点——再配合本文第五、六章的对照表就能顺利完成这次架构迁移。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考