使用 metrics-servlet 的 InstrumentedFilter 为 Web 应用注入请求级指标监控

发布时间：2026/9/27 7:48:12来源：尧图网络

可观测性后端【免费下载链接】metrics:chart_with_upwards_trend: Capturing JVM- and application-level metrics. So you know whats going on.项目地址https://gitcode.com/gh_mirrors/met/metrics点击查看免费下载本文以 Dropwizard Metrics 项目中的metrics-servlet模块为核心讲解如何通过一个 Servlet 过滤器InstrumentedFilter为 Web 应用自动采集 HTTP 请求的响应状态码速率、活跃请求数与请求耗时分布。读完本文你将掌握该过滤器的web.xml配置方法、name-prefix多映射命名技巧、MetricRegistry的注入方式并能基于源码理解每个指标背后的实现原理。模块定位一个过滤器解决三类核心监控需求metrics-servlet是当前仓库中的一个独立 Maven 模块其定位在 metrics-servlet/pom.xml 的描述中被明确为 An instrumented filter for servlet environments面向 Servlet 环境的插桩过滤器。它并不要求你改造业务代码而是以标准javax.servlet.Filter的形式挂载到应用的过滤器链上对进出应用的每个 HTTP 请求自动采集三类数据状态码速率Meter对返回的响应状态码分别计数并计算速率例如 200成功、404未找到、500服务端错误等活跃请求数Counter统计当前正在处理中的请求数量请求耗时Timer统计每个请求的耗时分布如均值、中位数、P95、P99 等。模块的实现由三个主类构成均位于 metrics-servlet/src/main/java/com/codahale/metrics/servlet 目录下类名职责InstrumentedFilter过滤器对外入口预置一组默认状态码映射指定默认registry属性名AbstractInstrumentedFilter过滤器核心逻辑负责指标创建、请求计时、状态码上报与异步请求处理InstrumentedFilterContextListenerServletContextListener实现负责把应用的MetricRegistry注入 Servlet 上下文依赖关系上该模块只依赖metrics-core提供Meter、Counter、Timer、MetricRegistry等核心类型并以provided作用域使用javax.servlet-api4.0.1意味着 Servlet API 由你的应用容器如 Tomcat、Jetty提供模块本身打包为 OSGi bundle。快速上手在 web.xml 中启用过滤器默认情况下过滤器会使用com.codahale.metrics.servlet.InstrumentedFilter作为所有指标的基础名称base name。在应用的web.xml中添加如下配置即可启用filter filter-nameinstrumentedFilter/filter-name filter-classcom.codahale.metrics.servlet.InstrumentedFilter/filter-class /filter filter-mapping filter-nameinstrumentedFilter/filter-name url-pattern/*/url-pattern /filter-mapping这里用url-pattern/*/url-pattern将过滤器映射到应用的全部请求。结合源码看init阶段AbstractInstrumentedFilter.java会完成以下指标的创建预置状态码对应的Meter兜底用的otherMetertimeoutsMeter与errorsMeteractiveRequestsCounterrequestsTimer。其中基础名称metricName的解析逻辑为先读取name-prefix初始化参数若未配置或为空字符串则回退到过滤器类名getClass().getName()即com.codahale.metrics.servlet.InstrumentedFilter。多 URL 模式差异化命名name-prefix 参数当应用需要按 URL 模式区分监控指标时可通过过滤器可选的init-param——name-prefix覆盖指标的基础名称。例如单独为/auth/*的认证接口建立一套独立指标filter filter-nameinstrumentedFilter/filter-name filter-classcom.codahale.metrics.servlet.InstrumentedFilter/filter-class init-param param-namename-prefix/param-name param-valueauthentication/param-value /init-param /filter filter-mapping filter-nameinstrumentedFilter/filter-name url-pattern/auth/*/url-pattern /filter-mapping通过为不同url-pattern声明多个同名过滤器、各自指定不同的name-prefix可以让每个 URL 模式拥有独一无二的指标命名空间。例如上述配置下认证接口的指标名将以authentication开头如authentication.requests、authentication.activeRequests、authentication.responseCodes.*与根路径映射的com.codahale.metrics.servlet.InstrumentedFilter.*系列指标互不冲突。从源码实现看name-prefix的读取位于 AbstractInstrumentedFilter.java常量METRIC_PREFIX name-prefix定义了该参数的名称参数值为空时按未配置处理自动回退到类名。注入 MetricRegistryServletContext 属性上下文监听器过滤器的指标需要写入应用自身的MetricRegistry否则无法与你其余指标汇总统一输出如写入 Graphite、JMX。metrics-servlet约定将MetricRegistry作为 Servlet 上下文ServletContext的一个属性存放属性名为com.codahale.metrics.servlet.InstrumentedFilter.registry。这一点在InstrumentedFilter中通过常量固化InstrumentedFilter.javapublic static final String REGISTRY_ATTRIBUTE InstrumentedFilter.class.getName() .registry;推荐的注入方式是扩展InstrumentedFilterContextListener在容器启动时由监听器把 registry 放入上下文public class MyInstrumentedFilterContextListener extends InstrumentedFilterContextListener { public static final MetricRegistry REGISTRY new MetricRegistry(); Override protected MetricRegistry getMetricRegistry() { return REGISTRY; } }然后在web.xml中注册该监听器listener listener-classcom.example.MyInstrumentedFilterContextListener/listener-class /listener其底层机制在 InstrumentedFilterContextListener.java 中非常直观contextInitialized回调时调用sce.getServletContext().setAttribute(InstrumentedFilter.REGISTRY_ATTRIBUTE, getMetricRegistry())把抽象方法getMetricRegistry()返回的实例挂到上下文。对应的单元测试 InstrumentedFilterContextListenerTest.java 使用 Mockito 验证了setAttribute(com.codahale.metrics.servlet.InstrumentedFilter.registry, registry)这一行为可作为阅读源码时行为确认的参照。需要留意的是过滤器读取 registry 时的回退行为在getMetricsFactory方法AbstractInstrumentedFilter.java中若上下文属性不存在或不是MetricRegistry实例过滤器会静默地 new 一个全新的MetricRegistry。这意味着漏配监听器时应用不会报错但指标将进入一个独立、无法被统一输出消费的 registry因此务必按上述步骤完成注入。指标全景过滤器会创建哪些指标综合 InstrumentedFilter.java 与 AbstractInstrumentedFilter.java在默认基础名称com.codahale.metrics.servlet.InstrumentedFilter下每个映射会创建如下指标按name(metricName, 子名)拼接即基础名.子名指标名子名部分类型含义requestsTimer所有同步或异步请求的耗时分布activeRequestsCounter当前正在处理中的请求数请求进入doFilter时 1结束时 -1responseCodes.okMeter返回 200 的响应速率responseCodes.createdMeter返回 201 的响应速率responseCodes.noContentMeter返回 204 的响应速率responseCodes.badRequestMeter返回 400 的响应速率responseCodes.notFoundMeter返回 404 的响应速率responseCodes.serverErrorMeter返回 500 的响应速率responseCodes.otherMeter兜底速率统计所有未在上表列出的状态码catch-alltimeoutsMeter异步请求超时次数errorsMeter请求抛出异常IOException、RuntimeException、ServletException的次数其中默认状态码映射由createMeterNamesByStatusCode方法InstrumentedFilter.java定义200→ok、201→created、204→noContent、400→badRequest、404→notFound、500→serverError其余状态码统一计入responseCodes.other。请求处理流程与状态码上报原理doFilter方法AbstractInstrumentedFilter.java刻画了每个请求的完整生命周期将原始HttpServletResponse包装为StatusExposingServletResponse用于捕获最终状态码——由于 Servlet 规范规定未显式设置状态时默认为 200该包装类初始状态为 200并覆写setStatus、sendError等方法记录每次设置activeRequests.inc()递增活跃请求计数requestTimer.time()启动计时调用chain.doFilter(request, wrappedResponse)继续后续过滤器与目标 Servlet若调用链抛出IOException、RuntimeException或ServletException标记error true后重新抛出由容器继续处理也因此errorsMeter统计的是进入过滤器链的请求本身抛出的异常而非 HTTP 500finally块中按请求是否为异步请求分流处理见下节。状态码上报的核心在markMeterForStatusCode方法AbstractInstrumentedFilter.java先查预置的状态码映射表命中则标记对应Meter未命中则标记otherMeter。异步请求Async的正确计时处理由于 Servlet 3.0 异步请求在doFilter返回后可能仍未完成处理AbstractInstrumentedFilter对此做了专门处理。当请求调用了request.startAsync()且未发生错误时过滤器不会立刻结束计时而是注册AsyncResultListenerAbstractInstrumentedFilter.java按异步生命周期事件结算指标onComplete异步处理完成——停止计时、递减activeRequests、按最终响应状态码标记对应MeteronTimeout异步处理超时——停止计时、递减activeRequests、标记timeoutsonError异步出错——停止计时、递减activeRequests、标记errorsonStartAsync空实现用于接收异步启动事件。若容器在onTimeout/onError之后再触发onCompletedone标志位可防止重复结算。这保证了基于异步 Servlet 的长连接、SSE、WebSocket 握手等场景下的耗时数据依然真实可信。依赖配置与自定义扩展方向在 Maven 项目中引入该模块时只需声明对metrics-servlet的依赖Servlet API 由容器提供dependency groupIdio.dropwizard.metrics/groupId artifactIdmetrics-servlet/artifactId /dependency版本可通过 metrics-bom 统一管理模块打包为 OSGi bundle模块名com.codahale.metrics.servletJava 9 模块名见 metrics-servlet/pom.xml 中的javaModuleName属性。如需自定义状态码分类例如为 401、429 单独建 Meter可以从源码结构推断出扩展路径AbstractInstrumentedFilter的受保护构造函数接收registryAttribute、meterNamesByStatusCode映射与otherMetricName三个参数子类传入自定义映射即可复刻InstrumentedFilter的完整能力——这与InstrumentedFilter本身预置默认映射的设计思路一致。最后建议将InstrumentedFilter与仓库中的 metrics-servlets 模块提供指标 HTTP 输出端点或metrics-graphite、metrics-jmx等报告器配合使用即可把上述requests、activeRequests、responseCodes.*指标接入你的监控大盘形成从采集到展示的完整链路。赞分享可观测性后端【免费下载链接】metrics:chart_with_upwards_trend: Capturing JVM- and application-level metrics. So you know whats going on.项目地址https://gitcode.com/gh_mirrors/met/metrics点击查看免费下载相关推荐Sentinel Web Servlet Filter 接入指南为 Java Web 请求注入流控防护Sentinel Web Servlet Filter 接入指南为 Java Web 请求注入流控防护导读本文围绕 Sentinel 的 sentinel后端微服务Kingfisher预提交钩子在代码提交前自动检测密钥的终极指南Kingfisher预提交钩子在代码提交前自动检测密钥的终极指南在软件开发中意外提交敏感信息是常见的安全风险。Kingfisher预提交钩子为您提供了一种终极指南使用Prometheus Operator监控Web服务器请求与错误指标终极指南使用Prometheus Operator监控Web服务器请求与错误指标 Prometheus Operator是一个针对Kubernetes的运营商云原生可观测性上一篇Midday校准限制配置最大调整与最小样本要求的最佳值下一篇Preact Query 的 QueryClientProviderProps 类型详解从 Props 到上下文注入的完整原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

网站建设高端定制企业官网