Micrometer metrics

The MicrometerMetrics plugin enables Micrometer metrics in your Ktor server application and allows you to choose the required monitoring system, such as Prometheus, JMX, Elastic, and so on. By default, Ktor exposes metrics for monitoring HTTP requests and a set of low-level metrics for monitoring the JVM. You can customize these metrics or create new ones.

Add dependencies

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

Add the ktor-metrics-micrometer dependency:
implementation "io.ktor:ktor-metrics-micrometer:$ktor_version"
implementation("io.ktor:ktor-metrics-micrometer:$ktor_version")
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-metrics-micrometer</artifactId> <version>${ktor_version}</version> </dependency>
Add a dependency required for a monitoring system. The example below shows how to add an artifact for Prometheus:
implementation "io.micrometer:micrometer-registry-prometheus:$prometeus_version"
implementation("io.micrometer:micrometer-registry-prometheus:$prometeus_version")
<dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> <version>${prometeus_version}</version> </dependency>
You can replace $prometeus_version with the required version of the micrometer-registry-prometheus artifact, for example, 1.7.1.

Install MicrometerMetrics

To install the MicrometerMetrics plugin, pass it to the install function in the application initialization code. Depending on the way used to create a server, this can be the embeddedServer function call ...

            import io.ktor.features.*
            // ...
            fun main() {
                embeddedServer(Netty, port = 8080) {
                    install(MicrometerMetrics)
                    // ...
                }.start(wait = true)
            }
        

... or a specified module.

            import io.ktor.features.*
            // ...
            fun Application.module() {
                install(MicrometerMetrics)
                // ...
            }
        

Exposed metrics

Ktor exposes the following metrics for monitoring HTTP requests:

ktor.http.server.requests.active: a gauge that counts the amount of concurrent HTTP requests. This metric doesn't provide any tags.
ktor.http.server.requests: a timer for measuring the time of each request. This metric provides a set of tags for monitoring request data, including address for a requested URL, method for an HTTP method, route for a Ktor route handling requests, and so on.

In addition to HTTP metrics, Ktor exposes a set of metrics for monitoring the JVM.

Create a registry

After installing MicrometerMetrics, you need to create a registry for your monitoring system and assign it to the registry property. In the example below, the PrometheusMeterRegistry is created outside the install block to have the capability to reuse this registry in different route handlers:

fun Application.module(testing: Boolean = false) {
    val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT)
    install(MicrometerMetrics) {
        registry = appMicrometerRegistry
    }
}

Configure metrics

The MicrometerMetrics plugin provides various configuration options that can be accessed using MicrometerMetrics.Configuration.

Timers

To customize tags for each timer, you can use the timers function that is called for each request:

install(MicrometerMetrics) {
    // ...
    timers { call, exception ->
        tag("region", call.request.headers["regionId"])
    }
}

Distribution statistics

You configure distribution statistics using the distributionStatisticConfig property, for example:

    install(MicrometerMetrics) {
        distributionStatisticConfig = DistributionStatisticConfig.Builder()
            .percentilesHistogram(true)
            .maximumExpectedValue(Duration.ofSeconds(20).toNanos().toDouble())
            .serviceLevelObjectives(
                Duration.ofMillis(100).toNanos().toDouble(),
                Duration.ofMillis(500).toNanos().toDouble()
            )
            .build()
    }

JVM and system metrics

In addition to HTTP metrics, Ktor exposes a set of metrics for monitoring the JVM. You can customize a list of these metrics using the meterBinders property, for example:

    install(MicrometerMetrics) {
        meterBinders = listOf(
            JvmMemoryMetrics(),
            JvmGcMetrics(),
            ProcessorMetrics()
        )
    }

You can also assign an empty list to disable these metrics at all.

Prometheus: expose a scrape endpoint

If you use Prometheus as a monitoring system, you need to expose an HTTP endpoint to the Prometheus scraper. In Ktor, you can do this in the following way:

Create a dedicated route that accepts GET requests by the required address (/metrics in the example below).
Use call.respond to send scraping data to Prometheus.
fun Application.module(testing: Boolean = false) { val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT) install(MicrometerMetrics) { registry = appMicrometerRegistry } routing { get("/metrics") { call.respond(appMicrometerRegistry.scrape()) } } }
You can find the full example here: micrometer-metrics.

Last modified: 11 May 2022