ApplicationInsights-dotnet 内置 ActivityProcessor 全解Session、User、ClientIp 等处理器原理【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet 是微软的 .NET 应用性能监控APMSDK。本文完整解析其内置的 7 个 ActivityProcessorActivity 处理器SessionActivityProcessor、UserActivityProcessor、ClientIpHeaderActivityProcessor 等讲清每个处理器读取什么数据、写入哪个遥测标签以及执行顺序与自定义扩展方法。什么是 ActivityProcessor为什么需要它 在 ASP.NET 经典 Web 应用中每次 HTTP 请求都会产生一个 OpenTelemetryActivity对象即一次链路。但裸的 Activity 只知道发生了什么请求并不天然携带用户是谁、属于哪个会话、IP 地址是什么这类业务上下文。ActivityProcessor 就是挂在 Activity 生命周期上的加工器当一次请求的 Activity 结束时OnEnd处理器从HttpContext中读取 Cookie、请求头等数据把它们以标签Tag的形式写入遥测数据最终随请求遥测一起上报到监控平台。 全部 7 个内置处理器统一注册在 Extensions/ApplicationInsightsExtensions.cs完整路径WEB/Src/Web/Web/Extensions/ApplicationInsightsExtensions.cs中AddProcessor(new WebTestActivityProcessor()) AddProcessor(new SyntheticUserAgentActivityProcessor()) AddProcessor(new SessionActivityProcessor()) AddProcessor(new UserActivityProcessor()) AddProcessor(new AuthenticatedUserIdActivityProcessor()) AddProcessor(new AccountIdActivityProcessor()) AddProcessor(new ClientIpHeaderActivityProcessor())也就是说无需任何手动配置安装 SDK 后这些处理器就自动生效。整个初始化由WEB/Src/Web/Web/WebApplicationInsightsInitializer.cs通过 ASP.NET 的 PreApplicationStartMethod 机制在Application_Start之前自动完成WEB/Src/Web/Web/ApplicationInsightsHttpModule.cs则是每个请求的入口模块。内置 ActivityProcessor 一览表处理器数据来源写入的标签作用WebTestActivityProcessor请求头 SyntheticTest-RunId / SyntheticTest-Locationai.operation.syntheticSource、ai.user.id、session.id识别 Azure 可用性探测流量SyntheticUserAgentActivityProcessorUser-Agent 请求头ai.operation.syntheticSource识别爬虫/机器人流量SessionActivityProcessorai_sessionCookiesession.id、session.isFirst会话追踪UserActivityProcessorai_userCookieai.user.id匿名用户识别AuthenticatedUserIdActivityProcessorai_authUserCookieenduser.id登录用户 IDAccountIdActivityProcessorai_authUserCookieenduser.account用户账号标识ClientIpHeaderActivityProcessorX-Forwarded-For等请求头client.address客户端 IP 地址Cookie 与常量的定义见WEB/Src/Web/Web/Implementation/RequestTrackingConstants.cs及各处理器源文件均位于WEB/Src/Web/Web/目录下。执行顺序与不覆盖原则 ⚠️理解内置处理器的两个关键设计顺序有意义。WebTestActivityProcessor排在SyntheticUserAgentActivityProcessor之前如果请求带可用性探测的请求头就优先判定为 GSM 探测流量后面的机器人检测检测到标签已存在会直接跳过避免误判。不覆盖已有值。每个处理器都遵循先检查标签是否已设置已设置则跳过的模式。这意味着你完全可以在业务代码中手动SetTag覆盖 SDK 的默认行为SDK 不会强行改写。逐个解析 7 个处理器原理1. WebTestActivityProcessor识别可用性探测流量源码WEB/Src/Web/Web/WebTestActivityProcessor.cs如果请求同时携带SyntheticTest-RunId和SyntheticTest-Location两个请求头说明流量来自 Azure 可用性监控处理器会写入ai.operation.syntheticSource Application Insights Availability Monitoringsession.id RunId同一次探测的所有请求归入同一会话ai.user.idLocation_RunId拼接 Pop 位置名与 RunId注释中说明了原因单独用 Location 无法应对采样2. SyntheticUserAgentActivityProcessor机器人流量识别源码WEB/Src/Web/Web/SyntheticUserAgentActivityProcessor.cs检查请求的 User-Agent命中过滤词就标记为合成流量ai.operation.syntheticSource Bot。默认过滤词为search|spider|crawl|Bot|Monitor|BrowserMob|PhantomJS|HeadlessChrome|Selenium|URLNormalization过滤词可通过Filters属性自定义竖线分隔的多个模式不区分大小写匹配结果会缓存到HttpContext.Items同一请求内只匹配一次避免重复计算这个标签的价值在于报表中可以把机器人流量与真实用户流量分开统计3. SessionActivityProcessor会话追踪原理源码WEB/Src/Web/Web/SessionActivityProcessor.cs读取ai_sessionCookie通常由前端脚本注入Cookie 值以竖线分隔sessionId|acquisitionDate|renewalDate取第 1 段作为session.id若获取日期与续期日期相同说明是用户第一次访问额外写入session.isFirst true—— 这是新用户/回访用户分析的基础数据4. UserActivityProcessor匿名用户识别原理源码WEB/Src/Web/Web/UserActivityProcessor.cs读取ai_userCookie格式为userId|ISO8601时间戳处理器会校验时间戳可解析为DateTimeOffset通过后才把 userId 写入ai.user.id。这个匿名 ID 让平台能把同一个访客的多次请求串起来即使访客从未登录。5. AuthenticatedUserIdActivityProcessor登录用户 ID源码WEB/Src/Web/Web/AuthenticatedUserIdActivityProcessor.cs针对登录用户读取ai_authUserCookie先做 URL 解码按竖线拆分后取第 1 段写入enduser.id。典型用法是在用户登录时由代码写入该 Cookie实现谁在用你的系统的分析。6. AccountIdActivityProcessor用户账号标识源码WEB/Src/Web/Web/AccountIdActivityProcessor.cs与上一个处理器读取同一个ai_authUserCookie但取第 2 段写入enduser.account。enduser.id与enduser.account配合使用可以同时支撑身份和账号体系两个维度的分析。7. ClientIpHeaderActivityProcessor客户端 IP 获取原理源码WEB/Src/Web/Web/ClientIpHeaderActivityProcessor.cs这是唯一支持较多运行时配置的处理器属性包括属性默认值说明HeaderNamesX-Forwarded-For依次尝试的 IP 请求头列表HeaderValueSeparators,多 IP 的分割符UseFirstIptrue取列表第一个还是最后一个 IP工作流程按顺序检查各请求头取到第一个有效值后按分割符拆分根据UseFirstIp决定取第一个通常是客户端真实 IP或最后一个通常是上游代理用tcp://URI 方式校验 IP 合法性支持带端口、IPv6 方括号形式所有请求头都取不到时回退到request.GetUserHostAddress()直连 IP最终写入client.address 部署在反向代理/负载均衡后面时如果 IP 全是内网地址需要在这个处理器上添加实际的转发头名称并调整UseFirstIp。如何自定义自己的 ActivityProcessor ✍️内置处理器均继承自BaseProcessorActivity并只重写OnEnd方法自定义处理器可以照葫芦画瓢读取HttpContext中的业务数据如租户 ID、部门 ID调用activity.SetTag(your.tag, value)写入标签然后通过TelemetryConfiguration的ConfigureOpenTelemetryBuilder用AddProcessor注册即可。注册时注意你添加的处理器会在内置处理器之后执行因此可以读取到内置处理器已写入的标签也可以对业务上更精确的值做覆盖。配置项参考经典 Web 配置读取逻辑WEB/Src/Web/Web/Implementation/ApplicationInsightsConfigurationReader.cs配置选项定义WEB/Src/Web/Web/Implementation/ApplicationInsightsConfigOptions.cs示例配置WEB/Src/Web/Web/applicationinsights.config.sample各处理器单元测试可直接参考预期行为WEB/Src/Web/Web.Tests/SessionActivityProcessorTests.cs、ClientIpHeaderActivityProcessorTests.cs、WebTestActivityProcessorTests.cs等另外NETCORE/src/Shared/ActivityFilterProcessor.cs中还有一个ActivityFilterProcessor用于按配置关闭依赖追踪或请求追踪对应配置中的 EnableDependencyTrackingTelemetryModule / EnableRequestTrackingTelemetryModule属于过滤型处理器与上面 7 个打标签型处理器职责不同。常见问题 FAQ Q1为什么遥测里看不到 session.id 或 ai.user.id这两个值依赖ai_session/ai_userCookie而 Cookie 通常由 Application Insights 前端脚本JS SDK在浏览器端生成。如果页面没有引入前端脚本或爬虫/Postman 直接请求Cookie 不存在时处理器会静默跳过可通过 ETW 事件源WebEventSource查看诊断日志定义见WEB/Src/Web/Web/Implementation/WebEventSource.cs。Q2登录用户的 enduser.id 没有值需要你在登录逻辑中手动写入ai_authUserCookie值格式userId|accountIdSDK 不会替你猜。Q3这些处理器影响性能吗影响很小。所有处理只在请求结束的OnEnd时刻执行一次只读取 Cookie/请求头这类内存数据没有 IO 操作机器人匹配的过滤词还会缓存复用。总结 ApplicationInsights-dotnet 内置的 7 个 ActivityProcessor 构成了经典 ASP.NET 场景下完整的请求上下文补全链路先判定流量性质可用性探测 → 机器人再补全会话、用户、账号、IP 四类上下文全部默认开启、顺序固定、支持业务覆盖。理解这套机制既能解释报表中各个上下文字段的来龙去脉也为扩展自定义标签处理器打下了基础。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考