How kenshoo/metrics-play works
Purpose and integration
metrics-play is a Scala library module that adapts Dropwizard/Codahale Metrics for Play applications. It provides a shared metric registry, HTTP request instrumentation, and a Play controller that exposes metrics as JSON. Consumers add the dependency, enable its Play module, optionally install its filter, and add their own route for the metrics endpoint.
Key integration points:
• src/main/scala/com/kenshoo/play/metrics/PlayModule.scala
• src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala
• src/main/scala/com/kenshoo/play/metrics/MetricsController.scala
Runtime and dependency model
The project is built with SBT and targets the Play 2 / Scala runtime; the README identifies Play 2.7, Scala 2.12, and Dropwizard Metrics 4.0.5 as its baseline. It is not a standalone service: it runs in the host application's Play dependency-injection and HTTP pipeline.
Build/runtime declarations and default configuration:
• build.sbt
• src/main/resources/reference.conf
• project/build.properties
Dependency-injection bootstrap
PlayModule is the library’s composition root. When enabled through Play’s module configuration, it binds the metrics abstraction and concrete implementations into Play DI, making them injectable into application controllers, filters, and other services. Eager bindings likely ensure registry/filter setup occurs during application startup rather than first use.
Primary boundary: host Play application configuration controls whether this module exists at all.
• src/main/scala/com/kenshoo/play/metrics/PlayModule.scala
• src/main/resources/reference.conf
Shared metrics registry
Metrics is the application-facing abstraction for obtaining the default Dropwizard MetricRegistry; MetricsImpl is represented within the same source file. Application code records counters, timers, meters, and other Dropwizard metric types through this registry. This registry is the common state shared by HTTP instrumentation, JVM/logback reporting, custom application metrics, and JSON export.
• src/main/scala/com/kenshoo/play/metrics/Metrics.scala
JVM and logging metric registration
The metrics service reads library defaults from reference.conf, including whether JVM and Logback metrics are reported. These registrations populate the same default registry, so they appear alongside application and request metrics. Configuration also determines display units and whether timer samples are included in exports.
• src/main/scala/com/kenshoo/play/metrics/Metrics.scala
• src/main/resources/reference.conf
HTTP instrumentation filter
MetricsFilter / MetricsFilterImpl sits in Play’s request filter chain. For each request it measures duration, tracks active requests, and increments response-status metrics. The implementation provides customization seams: applications can subclass it to change the metric label prefix and define which status codes receive distinct labels versus an “other” bucket.
Control flow: incoming Play request → filter starts/tracks timing → downstream action executes → response or failure is classified and metrics are updated.
• src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala
• src/main/scala/com/kenshoo/play/metrics/Metrics.scala
Metrics export endpoint
MetricsController adapts the Dropwizard metrics servlet behavior to a Play controller action. A host application explicitly maps a route to this action; on request, it serializes the shared registry to a JSON response. Export formatting is controlled by configured rate/duration units and sample visibility.
This endpoint is an observability boundary and should generally be protected by the host application’s routing/authentication policy; the library supplies export behavior, not deployment access control.
• src/main/scala/com/kenshoo/play/metrics/MetricsController.scala
• src/main/resources/reference.conf
Extension and ownership boundaries
The library owns metric registry construction, default reporters, request metric conventions, and JSON presentation. The consuming application owns module enablement, filter installation/order, route exposure, access control, and optional replacement bindings. Custom modules can bind a subclass of MetricsFilterImpl while retaining the library’s Metrics implementation.
• src/main/scala/com/kenshoo/play/metrics/PlayModule.scala
• src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala
• src/main/scala/com/kenshoo/play/metrics/Metrics.scala
Main entry points: Metrics.scala Metrics / MetricsImpl · MetricsFilter.scala MetricsFilter / Impl · PlayModule.scala PlayModule · MetricsController.scala MetricsController
Components 13
Host Play application
Controls library activation, filter ordering, routing, and access policy.
- Play DI + HTTP runtime
- Application metrics · Records custom Dropwizard metrics.
- Filter installation · The application chooses whether and where to install the filter.
- Metrics route + access policy · The application explicitly exposes and protects export.
- Downstream Play action · Produces the response or failure classified by the filter.
metrics-play library
- PlayModule · Binds the metrics services into Play DI.
src/main/scala/com/kenshoo/play/metrics/PlayModule.scala - Metrics / MetricsImpl · Constructs and exposes the shared MetricRegistry.
src/main/scala/com/kenshoo/play/metrics/Metrics.scala - JVM + Logback registration · Populates the shared registry when enabled.
src/main/scala/com/kenshoo/play/metrics/Metrics.scala - MetricsFilter / Impl · Times requests, tracks active work, and classifies responses.
src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala - MetricsController · Serializes the shared registry as JSON.
src/main/scala/com/kenshoo/play/metrics/MetricsController.scala
Build and defaults
- reference.conf · Controls reporters and JSON rate, duration, and sample settings.
src/main/resources/reference.conf - SBT build · Defines the Play 2 / Scala and Dropwizard Metrics baseline.
build.sbt - SBT properties
project/build.properties
Connections 17
- SBT build → Play DI + HTTP runtime: targets
- SBT properties → SBT build: sets SBT runtime
- reference.conf → PlayModule: enables/configures module
- Play DI + HTTP runtime → PlayModule: loads when enabled
- PlayModule → Metrics / MetricsImpl: binds
- PlayModule → MetricsFilter / Impl: binds
- reference.conf → Metrics / MetricsImpl: configures reporters
- Metrics / MetricsImpl → JVM + Logback registration: registers into registry
- Application metrics → Metrics / MetricsImpl: records custom metrics
- Filter installation → MetricsFilter / Impl: installs and orders
- Play DI + HTTP runtime → MetricsFilter / Impl: incoming request
- MetricsFilter / Impl → Downstream Play action: times execution
- MetricsFilter / Impl → Metrics / MetricsImpl: updates request metrics
- Metrics route + access policy → MetricsController: maps and protects
- Play DI + HTTP runtime → MetricsController: export request
- MetricsController → Metrics / MetricsImpl: serializes registry
- reference.conf → MetricsController: configures JSON format