Dropwizard metrics

The DropwizardMetrics plugin lets you configure the Metrics library to get useful information about the server and incoming requests.

Add dependencies

To enable DropwizardMetrics, you need to include the following artifacts in the build script:

Add the ktor-server-metrics dependency:
implementation("io.ktor:ktor-server-metrics:$ktor_version")
implementation "io.ktor:ktor-server-metrics:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-metrics-jvm</artifactId> <version>${ktor_version}</version> </dependency>
Optionally, add a dependency required for a specific reporter. The example below shows how to add an artifact required to report metrics via JMX:
implementation("io.dropwizard.metrics:metrics-jmx:$dropwizard_version")
implementation "io.dropwizard.metrics:metrics-jmx:$dropwizard_version"
<dependency> <groupId>io.dropwizard.metrics</groupId> <artifactId>metrics-jmx</artifactId> <version>${dropwizard_version}</version> </dependency>
You can replace $dropwizard_version with the required version of the metrics-jmx artifact, for example, 4.2.15.

Install DropwizardMetrics

To install the DropwizardMetrics plugin to the application, pass it to the install function in the specified module. The code snippets below show how to install DropwizardMetrics...

... inside the embeddedServer function call.
... inside the explicitly defined module, which is an extension function of the Application class.

                    import io.ktor.server.engine.*
                    import io.ktor.server.netty.*
                    import io.ktor.server.application.*
                    import io.ktor.server.metrics.dropwizard.*

                    fun main() {
                        embeddedServer(Netty, port = 8080) {
                            install(DropwizardMetrics)
                            // ...
                        }.start(wait = true)
                    }
                

                    import io.ktor.server.application.*
                    import io.ktor.server.metrics.dropwizard.*
                    // ...
                    fun Application.module() {
                        install(DropwizardMetrics)
                        // ...
                    }
                

Configure DropwizardMetrics

DropwizardMetrics allows you to use any supported Metric reporter using the registry property. Let's take a look at how to configure the SLF4J and JMX reporters.

SLF4J reporter

The SLF4J reporter allows you to periodically emit reports to any output supported by SLF4J. For example, to output the metrics every 10 seconds, you would:

    install(DropwizardMetrics) {
        Slf4jReporter.forRegistry(registry)
            .outputTo(this@module.log)
            .convertRatesTo(TimeUnit.SECONDS)
            .convertDurationsTo(TimeUnit.MILLISECONDS)
            .build()
            .start(10, TimeUnit.SECONDS)
    }

You can find the full example here: dropwizard-metrics.

If you run the application and open http://0.0.0.0:8080, the output will look like this:

[DefaultDispatcher-worker-1] INFO  Application - Responding at http://0.0.0.0:8080
... type=COUNTER, name=ktor.calls.active, count=0
... type=METER, name=ktor.calls./(method:GET).200, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.98655785084844, rate_unit=events/second
... type=METER, name=ktor.calls./(method:GET).meter, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9841134429134598, rate_unit=events/second
... type=METER, name=ktor.calls.exceptions, count=0, m1_rate=0.0, m5_rate=0.0, m15_rate=0.0, mean_rate=0.0, rate_unit=events/second
... type=METER, name=ktor.calls.status.200, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9866015088545449, rate_unit=events/second
... type=TIMER, name=ktor.calls./(method:GET).timer, count=6, min=0.359683, max=14.213046, mean=2.691307542732234, stddev=5.099546889849414, p50=0.400967, p75=0.618972, p95=14.213046, p98=14.213046, p99=14.213046, p999=14.213046, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9830677128229028, rate_unit=events/second, duration_unit=milliseconds
... type=TIMER, name=ktor.calls.duration, count=6, min=0.732149, max=33.735719, mean=6.238046092985701, stddev=12.169258340009847, p50=0.778864, p75=1.050454, p95=33.735719, p98=33.735719, p99=33.735719, p999=33.735719, m1_rate=0.2, m5_rate=0.2, m15_rate=0.2, mean_rate=0.6040311229887146, rate_unit=events/second, duration_unit=milliseconds

JMX reporter

The JMX reporter allows you to expose all the metrics to JMX, allowing you to view those metrics using jconsole.

    install(DropwizardMetrics) {
        JmxReporter.forRegistry(registry)
            .convertRatesTo(TimeUnit.SECONDS)
            .convertDurationsTo(TimeUnit.MILLISECONDS)
            .build()
            .start()
    }

You can find the full example here: dropwizard-metrics.

If you run the application and connect to its process using the JConsole, metrics will look like this:

Exposed metrics

DropwizardMetrics exposes the following metrics:

Global metrics that include Ktor-specific and JVM metrics.
Metrics for endpoints.

Global metrics

Global metrics include the following Ktor-specific metrics:

ktor.calls.active: Count - The number of unfinished active requests.
ktor.calls.duration - Information about the duration of the calls.
ktor.calls.exceptions - Information about the number of exceptions.
ktor.calls.status.NNN - Information about the number of times that happened a specific HTTP status code NNN.

Note that a metric name starts with the ktor.calls prefix. You can customize it using the baseName property:

install(DropwizardMetrics) {
    baseName = "my.prefix"
}

Metrics per endpoint

"/uri(method:VERB).NNN" - Information about the number of times that happened a specific HTTP status code NNN, for this path and verb.
"/uri(method:VERB).meter" - Information about the number of calls for this path and verb.
"/uri(method:VERB).timer" - Information about the duration for this endpoint.

JVM metrics

In addition to HTTP metrics, Ktor exposes a set of metrics for monitoring the JVM. You can disable these metrics using the registerJvmMetricSets property:

    install(DropwizardMetrics) {
        registerJvmMetricSets = false
    }

You can find the full example here: dropwizard-metrics.

Last modified: 02 April 2024