# kenshoo/metrics-play architecture

> Architecture diagram of the GitHub repository kenshoo/metrics-play, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenshoo/metrics-play
- Repository: https://github.com/kenshoo/metrics-play

## Overview

#### 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: [`src/main/scala/com/kenshoo/play/metrics/Metrics.scala`](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/Metrics.scala) (Metrics / MetricsImpl), [`src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala`](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala) (MetricsFilter / Impl), [`src/main/scala/com/kenshoo/play/metrics/PlayModule.scala`](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/PlayModule.scala) (PlayModule), [`src/main/scala/com/kenshoo/play/metrics/MetricsController.scala`](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsController.scala) (MetricsController)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host Play application"]
  node_play_runtime{{"Play DI + HTTP runtime<br/>host runtime"}}
  node_app_code["Application metrics<br/>consumer code"]
  node_filter_installation["Filter installation<br/>host configuration"]
  node_metrics_route["Metrics route + access policy<br/>host routing"]
  node_downstream_action["Downstream Play action<br/>HTTP handler"]
end

subgraph group_library["metrics-play library"]
  node_play_module["PlayModule<br/>DI composition root<br/>[PlayModule.scala]"]
  node_metrics_service[("Metrics / MetricsImpl<br/>registry service<br/>[Metrics.scala]")]
  node_default_reporters["JVM + Logback registration<br/>default reporters<br/>[Metrics.scala]"]
  node_metrics_filter["MetricsFilter / Impl<br/>HTTP filter"]
  node_metrics_controller["MetricsController<br/>JSON export action"]
end

subgraph group_config["Build and defaults"]
  node_reference_conf["reference.conf<br/>library defaults<br/>[reference.conf]"]
  node_sbt_build["SBT build<br/>build declaration<br/>[build.sbt]"]
  node_build_properties["SBT properties<br/>build runtime declaration<br/>[build.properties]"]
end

node_sbt_build -.->|"targets"| node_play_runtime
node_build_properties -.->|"sets SBT runtime"| node_sbt_build
node_reference_conf -.->|"enables/configures module"| node_play_module
node_play_runtime -->|"loads when enabled"| node_play_module
node_play_module -->|"binds"| node_metrics_service
node_play_module -->|"binds"| node_metrics_filter
node_reference_conf -.->|"configures reporters"| node_metrics_service
node_metrics_service -->|"registers into registry"| node_default_reporters
node_app_code -->|"records custom metrics"| node_metrics_service
node_filter_installation -->|"installs and orders"| node_metrics_filter
node_play_runtime -->|"incoming request"| node_metrics_filter
node_metrics_filter -->|"times execution"| node_downstream_action
node_metrics_filter -->|"updates request metrics"| node_metrics_service
node_metrics_route -->|"maps and protects"| node_metrics_controller
node_play_runtime -->|"export request"| node_metrics_controller
node_metrics_controller -->|"serializes registry"| node_metrics_service
node_reference_conf -.->|"configures JSON format"| node_metrics_controller

click node_play_module "https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/PlayModule.scala"
click node_metrics_service "https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/Metrics.scala"
click node_default_reporters "https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/Metrics.scala"
click node_metrics_filter "https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala"
click node_metrics_controller "https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsController.scala"
click node_reference_conf "https://github.com/kenshoo/metrics-play/blob/master/src/main/resources/reference.conf"
click node_sbt_build "https://github.com/kenshoo/metrics-play/blob/master/build.sbt"
click node_build_properties "https://github.com/kenshoo/metrics-play/blob/master/project/build.properties"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_play_runtime,node_app_code,node_filter_installation,node_metrics_route,node_downstream_action toneBlue
class node_play_module,node_metrics_service,node_default_reporters,node_metrics_filter,node_metrics_controller toneAmber
class node_reference_conf,node_sbt_build,node_build_properties toneMint
```

## Components

### Host Play application

Controls library activation, filter ordering, routing, and access policy.

- **Play DI + HTTP runtime**: host runtime
- **Application metrics**: consumer code · Records custom Dropwizard metrics.
- **Filter installation**: host configuration · The application chooses whether and where to install the filter.
- **Metrics route + access policy**: host routing · The application explicitly exposes and protects export.
- **Downstream Play action**: HTTP handler · Produces the response or failure classified by the filter.

### metrics-play library

- [PlayModule](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/PlayModule.scala): DI composition root · Binds the metrics services into Play DI. · `src/main/scala/com/kenshoo/play/metrics/PlayModule.scala`
- [Metrics / MetricsImpl](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/Metrics.scala): registry service · Constructs and exposes the shared MetricRegistry. · `src/main/scala/com/kenshoo/play/metrics/Metrics.scala`
- [JVM + Logback registration](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/Metrics.scala): default reporters · Populates the shared registry when enabled. · `src/main/scala/com/kenshoo/play/metrics/Metrics.scala`
- [MetricsFilter / Impl](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala): HTTP filter · Times requests, tracks active work, and classifies responses. · `src/main/scala/com/kenshoo/play/metrics/MetricsFilter.scala`
- [MetricsController](https://github.com/kenshoo/metrics-play/blob/master/src/main/scala/com/kenshoo/play/metrics/MetricsController.scala): JSON export action · Serializes the shared registry as JSON. · `src/main/scala/com/kenshoo/play/metrics/MetricsController.scala`

### Build and defaults

- [reference.conf](https://github.com/kenshoo/metrics-play/blob/master/src/main/resources/reference.conf): library defaults · Controls reporters and JSON rate, duration, and sample settings. · `src/main/resources/reference.conf`
- [SBT build](https://github.com/kenshoo/metrics-play/blob/master/build.sbt): build declaration · Defines the Play 2 / Scala and Dropwizard Metrics baseline. · `build.sbt`
- [SBT properties](https://github.com/kenshoo/metrics-play/blob/master/project/build.properties): build runtime declaration · `project/build.properties`

## Connections

- 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
