Pinpoint Undertow 插件接入指南配置项详解与请求追踪原理【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint本指南围绕 Pinpoint 官方 Undertow 插件agent-module/plugins/undertow展开说明如何在 Spring Boot 内嵌 Undertow 或 WildFly 应用服务器场景下开启 Undertow 的请求追踪能力逐项解释pinpoint.config中的全部配置参数并结合插件源码剖析其基于Connectors.executeRootHandler入口插桩的追踪原理。读完本文你将能够独立完成 Undertow 应用的 Pinpoint 接入、按需调优追踪参数并理解请求参数、真实 IP、Header 过滤等功能在源码层面的实现方式。插件概览支持范围与适用场景Undertow 插件是 Pinpoint 服务端Web Server类型插件用于对基于 Undertow 构建的 HTTP 服务进行入口级Entry Point追踪。官方文档给出以下关键信息引入版本Since Pinpoint 1.8.0支持范围io.undertow/undertow-core [2.0.0.Final, 2.0.16.Final]即2.0.0.Final x 2.0.16.Final适用 Web ServerSpring Boot starter内嵌 Undertow与 WildFly Application Server从 pom.xml 可以看到插件的依赖设计undertow-core与javax.servlet-api均为provided作用域由目标应用提供插件自身不打包pinpoint-bootstrap-core提供插桩 APIpinpoint-common-servlet以compile作用域引入并在打包阶段被 maven-shade-plugin 重新定位relocation到com.navercorp.pinpoint.plugin.undertow.common.servlet命名空间避免与目标应用中的 Servlet 类冲突。插件通过UndertowConstants注册了两个服务类型UNDERTOWServiceType 1120带RECORD_STATISTICS属性用于统计与 Server Map 展示UNDERTOW_METHODServiceType 1121用于方法级调用栈记录两者由 UndertowTypeProvider.java 在 Trace 元数据初始化阶段注册。快速启用pinpoint.config 配置Undertow 插件默认随 agent 分发无需额外下载插件 jar。启用与调优均通过 agent 的pinpoint.config配置文件完成。官方文档给出的完整配置块如下# 总开关默认启用 profiler.undertow.enabletrue # Since pinpoint-1.8.2 # Servlet 部署模式支持如 Spring Boot Undertow、Wildfly # 如果是被 bootstrap 方式引导的 Undertow请设为 false profiler.undertow.deploy.servlettrue # 是否追踪请求参数默认值为 true profiler.undertow.tracerequestparamtrue # 隐藏 Pinpoint 相关的请求头 profiler.undertow.hidepinpointheadertrue # 需要排除追踪的 URL支持 Ant 风格模式如 /aa/*.html、/??/exclude.html profiler.undertow.excludeurl # 需要排除追踪的 HTTP 请求方法 #profiler.undertow.excludemethod # 原始 IP 地址请求头如经过反向代理时获取真实客户端 IP #profiler.undertow.realipheaderX-Forwarded-For # nginx 真实 IP 请求头 #profiler.undertow.realipheaderX-Real-IP # 可选参数当请求头值为 ${profiler.undertow.realipemptyvalue} 指定的值时忽略该请求头值 #profiler.undertow.realipemptyvalueunknown将上述内容写入pinpoint.config并重启应用后Undertow 插件即生效。profiler.undertow.enablefalse可整体关闭插件——在 UndertowPlugin.java 的setup()中插件启动时会读取该配置若为false则直接返回不注册任何类转换。配置参数详解参数默认值说明profiler.undertow.enabletrue插件总开关profiler.undertow.deploy.servlettrueServlet 部署模式支持Spring Boot Undertow / WildFlybootstrap 引导的 Undertow 建议设为falseprofiler.undertow.tracerequestparamtrue是否在调用栈中记录请求参数query stringprofiler.undertow.hidepinpointheadertrue是否在转发请求前移除 Pinpoint 私有请求头防止追踪上下文泄露给下游profiler.undertow.excludeurl空排除追踪的 URL支持 Ant 风格模式如/aa/*.html、/??/exclude.htmlprofiler.undertow.excludemethod空不记录参数的 HTTP 方法如POST详见下方源码说明profiler.undertow.realipheader空真实客户端 IP 请求头名称如X-Forwarded-For、X-Real-IPprofiler.undertow.realipemptyvalue空可选当realipheader对应请求头的值等于该值时忽略该值不采用以上参数与 UndertowConfig.java 的读取逻辑一一对应。此外源码中还暴露了两个官方文档未列出的进阶参数profiler.undertow.bootstrap.main通过config.readList(...)读取用于声明 bootstrap 主类列表与deploy.servletfalse的引导场景配合profiler.undertow.http-handler.class.nameHTTP Handler 类名过滤。默认值为空时插件对所有HttpHandler生效配置后按ExcludePathFilter语义以.为分隔、,分隔多个类名匹配用于只追踪特定 Handler 实现。值得注意的是hidepinpointheader、tracerequestparam、excludeurl、excludemethod、realipheader、realipemptyvalue六项并非插件独有而是通过公共的ServerConfig统一读取见 UndertowConfig.java因此它们的读取语义与其他 Web 容器插件Tomcat、Jetty 等完全一致便于在多容器混合部署时保持配置习惯统一。工作原理从入口插桩到请求追踪入口点插桩Undertow 每次 HTTP 请求都会经由io.undertow.server.Connectors.executeRootHandler(HttpHandler, HttpServerExchange)分发到根处理器。插件在 UndertowPlugin.java 中对io.undertow.server.Connectors类执行字节码转换transform找到executeRootHandler方法并挂载ConnectorsExecuteRootHandlerInterceptor拦截器。选择该方法作为入口点的原因在于它同时持有HttpHandler处理器与HttpServerExchange一次请求-响应交换的完整上下文是采集请求信息的天然锚点。请求/响应事件监听ConnectorsExecuteRootHandlerInterceptor.java 是插件的核心逻辑它在构造时组装了两套监听器ServletRequestListenerHttpServerExchange负责开启/关闭 Trace 块TraceBlock、记录 RPC 名称、方法、端点、远端地址、状态码、HTTP 状态码错误、请求头/ Cookie 记录等ServletResponseListenerHttpServerExchange负责响应侧的状态码采集与 Trace 块收尾。在before()中先通过Validator校验参数第一个参数必须是HttpHandler实例、第二个参数必须是HttpServerExchange并应用http-handler.class.name过滤随后依次触发请求监听器初始化、响应监听器初始化注释明确说明必须在请求监听器之后以保证 TraceBlock 先开启最后执行UndertowHttpHeaderFilter.filter()移除 Pinpoint 私有请求头。在after()中则按相反顺序销毁响应监听器与请求监听器并调用HttpServerExchange.getStatusCode()获取 HTTP 状态码。请求信息采集适配插件通过 HttpServerExchangeAdaptor.java 将 Undertow 的HttpServerExchange适配为 Pinpoint 统一的RequestAdaptor接口映射关系如下Pinpoint 字段数据来源RPC 名称HttpServerExchange.getRequestURI()方法名HttpServerExchange.getRequestMethod()EndPointgetDestinationAddress()host:port远端地址getSourceAddress()客户端 socket 地址请求头getRequestHeaders()取peekFirst()请求参数追踪与截断策略profiler.undertow.tracerequestparamtrue时插件通过 ParameterRecorderFactory.java 创建参数记录器参数提取器为HttpServerExchangeParameterExtractor其构造参数为eachLimit64、totalLimit512即单个 key/value 最长截断 64 字符、整体参数字符串超过 512 字符后以...截断避免超长 query string 撑爆 Trace 数据见 HttpServerExchangeParameterExtractor.java提取结果来自HttpServerExchange.getQueryParameters()query string 解析后的 key 到多值队列的映射MethodFilterExtractor会先按excludemethod过滤 HTTP 方法被排除的方法不记录参数若tracerequestparamfalse则直接使用DisableParameterRecorder完全不采集参数。这套「总长限制 单项限制 方法过滤」的组合保证了高并发生产环境下的数据体积可控。隐藏 Pinpoint 请求头UndertowHttpHeaderFilter.java 实现了hidepinpointheader的语义当配置为true时遍历HttpServerExchange.getRequestHeaders()的全部请求头名称凡是以 Pinpoint 私有头前缀Header.startWithPinpointHeader如Pinpoint-*追踪上下文头命名的一律从HeaderMap中移除。该机制防止 Pinpoint 的追踪上下文TraceId、SpanId 等经 Undertow 应用透传或回传避免下游应用误建跨系统追踪链或造成上下文污染。Real IP 支持当应用部署在反向代理Nginx 等之后时HttpServerExchange.getSourceAddress()拿到的是代理地址而非客户端真实 IP。此时可通过profiler.undertow.realipheaderX-Forwarded-For指定真实 IP 请求头若同时设置realipemptyvalueunknown则当请求头值恰好为unknown或你指定的哨兵值时插件会忽略该头回退到 socket 地址。该能力由ServletRequestListenerBuilder.setRealIpSupport(config.getRealIpHeader(), config.getRealIpEmptyValue())注入见 ConnectorsExecuteRootHandlerInterceptor.java保证 Server Map 与调用栈中的远端地址是真实客户端。测试与验证仓库在 undertow-plugin-testweb 提供了配套的测试 Web 应用其pom.xml引入undertow-core、undertow-servlet、undertow-websockets-jsr版本 2.2.17.Final启动类为 UndertowPluginTestStarter.java可直接作为接入验证的最小样例以带 agent 的方式启动该应用并发起 HTTP 请求即可在 Pinpoint Web 的 Server Map 中看到UNDERTOW节点在调用栈中看到UNDERTOW_METHOD级别的请求记录。注意事项版本边界官方声明支持undertow-core [2.0.0.Final, 2.0.16.Final]。测试应用使用 2.2.17.Final 仅用于集成验证生产环境若使用超出声明范围的版本建议先在测试环境验证字节码转换兼容性。部署模式Spring Boot 内嵌 Undertow 与 WildFly 属于 Servlet 部署模式保持profiler.undertow.deploy.servlettrue若你的应用以编程方式bootstrap直接组装 Undertow例如纯非 Servlet 的 HTTP 服务应将其设为false并结合bootstrap.main、http-handler.class.name做精细化控制。与 Servlet 插件的协同由于插件 shade 了pinpoint-common-servlet且依赖javax.servlet-apiprovided在 WildFly 等 Servlet 容器内Undertow 插件负责入口采集容器内的 Servlet 插件继续负责更深层 Servlet 调用链两者互不冲突。综上Undertow 插件是一个典型的「入口插桩 统一 Request/Response 监听」型 Web 容器插件通过Connectors.executeRootHandler单点插桩覆盖全部请求再以可配置的开关、过滤器与截断策略平衡追踪深度与数据开销。参考本指南完成 agent-module/plugins/undertow/README.md 中的配置即可快速接入深入 agent-module/plugins/undertow 源码可进一步理解每个参数背后的实现细节。【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pinpoint Undertow 插件接入指南：配置项详解与请求追踪原理
Pinpoint Undertow 插件接入指南配置项详解与请求追踪原理【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint本指南围绕 Pinpoint 官方 Undertow 插件agent-module/plugins/undertow展开说明如何在 Spring Boot 内嵌 Undertow 或 WildFly 应用服务器场景下开启 Undertow 的请求追踪能力逐项解释pinpoint.config中的全部配置参数并结合插件源码剖析其基于Connectors.executeRootHandler入口插桩的追踪原理。读完本文你将能够独立完成 Undertow 应用的 Pinpoint 接入、按需调优追踪参数并理解请求参数、真实 IP、Header 过滤等功能在源码层面的实现方式。插件概览支持范围与适用场景Undertow 插件是 Pinpoint 服务端Web Server类型插件用于对基于 Undertow 构建的 HTTP 服务进行入口级Entry Point追踪。官方文档给出以下关键信息引入版本Since Pinpoint 1.8.0支持范围io.undertow/undertow-core [2.0.0.Final, 2.0.16.Final]即2.0.0.Final x 2.0.16.Final适用 Web ServerSpring Boot starter内嵌 Undertow与 WildFly Application Server从 pom.xml 可以看到插件的依赖设计undertow-core与javax.servlet-api均为provided作用域由目标应用提供插件自身不打包pinpoint-bootstrap-core提供插桩 APIpinpoint-common-servlet以compile作用域引入并在打包阶段被 maven-shade-plugin 重新定位relocation到com.navercorp.pinpoint.plugin.undertow.common.servlet命名空间避免与目标应用中的 Servlet 类冲突。插件通过UndertowConstants注册了两个服务类型UNDERTOWServiceType 1120带RECORD_STATISTICS属性用于统计与 Server Map 展示UNDERTOW_METHODServiceType 1121用于方法级调用栈记录两者由 UndertowTypeProvider.java 在 Trace 元数据初始化阶段注册。快速启用pinpoint.config 配置Undertow 插件默认随 agent 分发无需额外下载插件 jar。启用与调优均通过 agent 的pinpoint.config配置文件完成。官方文档给出的完整配置块如下# 总开关默认启用 profiler.undertow.enabletrue # Since pinpoint-1.8.2 # Servlet 部署模式支持如 Spring Boot Undertow、Wildfly # 如果是被 bootstrap 方式引导的 Undertow请设为 false profiler.undertow.deploy.servlettrue # 是否追踪请求参数默认值为 true profiler.undertow.tracerequestparamtrue # 隐藏 Pinpoint 相关的请求头 profiler.undertow.hidepinpointheadertrue # 需要排除追踪的 URL支持 Ant 风格模式如 /aa/*.html、/??/exclude.html profiler.undertow.excludeurl # 需要排除追踪的 HTTP 请求方法 #profiler.undertow.excludemethod # 原始 IP 地址请求头如经过反向代理时获取真实客户端 IP #profiler.undertow.realipheaderX-Forwarded-For # nginx 真实 IP 请求头 #profiler.undertow.realipheaderX-Real-IP # 可选参数当请求头值为 ${profiler.undertow.realipemptyvalue} 指定的值时忽略该请求头值 #profiler.undertow.realipemptyvalueunknown将上述内容写入pinpoint.config并重启应用后Undertow 插件即生效。profiler.undertow.enablefalse可整体关闭插件——在 UndertowPlugin.java 的setup()中插件启动时会读取该配置若为false则直接返回不注册任何类转换。配置参数详解参数默认值说明profiler.undertow.enabletrue插件总开关profiler.undertow.deploy.servlettrueServlet 部署模式支持Spring Boot Undertow / WildFlybootstrap 引导的 Undertow 建议设为falseprofiler.undertow.tracerequestparamtrue是否在调用栈中记录请求参数query stringprofiler.undertow.hidepinpointheadertrue是否在转发请求前移除 Pinpoint 私有请求头防止追踪上下文泄露给下游profiler.undertow.excludeurl空排除追踪的 URL支持 Ant 风格模式如/aa/*.html、/??/exclude.htmlprofiler.undertow.excludemethod空不记录参数的 HTTP 方法如POST详见下方源码说明profiler.undertow.realipheader空真实客户端 IP 请求头名称如X-Forwarded-For、X-Real-IPprofiler.undertow.realipemptyvalue空可选当realipheader对应请求头的值等于该值时忽略该值不采用以上参数与 UndertowConfig.java 的读取逻辑一一对应。此外源码中还暴露了两个官方文档未列出的进阶参数profiler.undertow.bootstrap.main通过config.readList(...)读取用于声明 bootstrap 主类列表与deploy.servletfalse的引导场景配合profiler.undertow.http-handler.class.nameHTTP Handler 类名过滤。默认值为空时插件对所有HttpHandler生效配置后按ExcludePathFilter语义以.为分隔、,分隔多个类名匹配用于只追踪特定 Handler 实现。值得注意的是hidepinpointheader、tracerequestparam、excludeurl、excludemethod、realipheader、realipemptyvalue六项并非插件独有而是通过公共的ServerConfig统一读取见 UndertowConfig.java因此它们的读取语义与其他 Web 容器插件Tomcat、Jetty 等完全一致便于在多容器混合部署时保持配置习惯统一。工作原理从入口插桩到请求追踪入口点插桩Undertow 每次 HTTP 请求都会经由io.undertow.server.Connectors.executeRootHandler(HttpHandler, HttpServerExchange)分发到根处理器。插件在 UndertowPlugin.java 中对io.undertow.server.Connectors类执行字节码转换transform找到executeRootHandler方法并挂载ConnectorsExecuteRootHandlerInterceptor拦截器。选择该方法作为入口点的原因在于它同时持有HttpHandler处理器与HttpServerExchange一次请求-响应交换的完整上下文是采集请求信息的天然锚点。请求/响应事件监听ConnectorsExecuteRootHandlerInterceptor.java 是插件的核心逻辑它在构造时组装了两套监听器ServletRequestListenerHttpServerExchange负责开启/关闭 Trace 块TraceBlock、记录 RPC 名称、方法、端点、远端地址、状态码、HTTP 状态码错误、请求头/ Cookie 记录等ServletResponseListenerHttpServerExchange负责响应侧的状态码采集与 Trace 块收尾。在before()中先通过Validator校验参数第一个参数必须是HttpHandler实例、第二个参数必须是HttpServerExchange并应用http-handler.class.name过滤随后依次触发请求监听器初始化、响应监听器初始化注释明确说明必须在请求监听器之后以保证 TraceBlock 先开启最后执行UndertowHttpHeaderFilter.filter()移除 Pinpoint 私有请求头。在after()中则按相反顺序销毁响应监听器与请求监听器并调用HttpServerExchange.getStatusCode()获取 HTTP 状态码。请求信息采集适配插件通过 HttpServerExchangeAdaptor.java 将 Undertow 的HttpServerExchange适配为 Pinpoint 统一的RequestAdaptor接口映射关系如下Pinpoint 字段数据来源RPC 名称HttpServerExchange.getRequestURI()方法名HttpServerExchange.getRequestMethod()EndPointgetDestinationAddress()host:port远端地址getSourceAddress()客户端 socket 地址请求头getRequestHeaders()取peekFirst()请求参数追踪与截断策略profiler.undertow.tracerequestparamtrue时插件通过 ParameterRecorderFactory.java 创建参数记录器参数提取器为HttpServerExchangeParameterExtractor其构造参数为eachLimit64、totalLimit512即单个 key/value 最长截断 64 字符、整体参数字符串超过 512 字符后以...截断避免超长 query string 撑爆 Trace 数据见 HttpServerExchangeParameterExtractor.java提取结果来自HttpServerExchange.getQueryParameters()query string 解析后的 key 到多值队列的映射MethodFilterExtractor会先按excludemethod过滤 HTTP 方法被排除的方法不记录参数若tracerequestparamfalse则直接使用DisableParameterRecorder完全不采集参数。这套「总长限制 单项限制 方法过滤」的组合保证了高并发生产环境下的数据体积可控。隐藏 Pinpoint 请求头UndertowHttpHeaderFilter.java 实现了hidepinpointheader的语义当配置为true时遍历HttpServerExchange.getRequestHeaders()的全部请求头名称凡是以 Pinpoint 私有头前缀Header.startWithPinpointHeader如Pinpoint-*追踪上下文头命名的一律从HeaderMap中移除。该机制防止 Pinpoint 的追踪上下文TraceId、SpanId 等经 Undertow 应用透传或回传避免下游应用误建跨系统追踪链或造成上下文污染。Real IP 支持当应用部署在反向代理Nginx 等之后时HttpServerExchange.getSourceAddress()拿到的是代理地址而非客户端真实 IP。此时可通过profiler.undertow.realipheaderX-Forwarded-For指定真实 IP 请求头若同时设置realipemptyvalueunknown则当请求头值恰好为unknown或你指定的哨兵值时插件会忽略该头回退到 socket 地址。该能力由ServletRequestListenerBuilder.setRealIpSupport(config.getRealIpHeader(), config.getRealIpEmptyValue())注入见 ConnectorsExecuteRootHandlerInterceptor.java保证 Server Map 与调用栈中的远端地址是真实客户端。测试与验证仓库在 undertow-plugin-testweb 提供了配套的测试 Web 应用其pom.xml引入undertow-core、undertow-servlet、undertow-websockets-jsr版本 2.2.17.Final启动类为 UndertowPluginTestStarter.java可直接作为接入验证的最小样例以带 agent 的方式启动该应用并发起 HTTP 请求即可在 Pinpoint Web 的 Server Map 中看到UNDERTOW节点在调用栈中看到UNDERTOW_METHOD级别的请求记录。注意事项版本边界官方声明支持undertow-core [2.0.0.Final, 2.0.16.Final]。测试应用使用 2.2.17.Final 仅用于集成验证生产环境若使用超出声明范围的版本建议先在测试环境验证字节码转换兼容性。部署模式Spring Boot 内嵌 Undertow 与 WildFly 属于 Servlet 部署模式保持profiler.undertow.deploy.servlettrue若你的应用以编程方式bootstrap直接组装 Undertow例如纯非 Servlet 的 HTTP 服务应将其设为false并结合bootstrap.main、http-handler.class.name做精细化控制。与 Servlet 插件的协同由于插件 shade 了pinpoint-common-servlet且依赖javax.servlet-apiprovided在 WildFly 等 Servlet 容器内Undertow 插件负责入口采集容器内的 Servlet 插件继续负责更深层 Servlet 调用链两者互不冲突。综上Undertow 插件是一个典型的「入口插桩 统一 Request/Response 监听」型 Web 容器插件通过Connectors.executeRootHandler单点插桩覆盖全部请求再以可配置的开关、过滤器与截断策略平衡追踪深度与数据开销。参考本指南完成 agent-module/plugins/undertow/README.md 中的配置即可快速接入深入 agent-module/plugins/undertow 源码可进一步理解每个参数背后的实现细节。【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考