Micrometer Metrics

The MicrometerMetrics feature 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:

  

  Gradle (Groovy)

  Gradle (Kotlin)

  Maven

  

  implementation "io.ktor:ktor-metrics-micrometer:$ktor_version"

• Add a dependency required for a monitoring system. The example below shows how to add an artifact for Prometeus:

  

  Gradle (Groovy)

  Gradle (Kotlin)

  Maven

  

  implementation "io.micrometer:micrometer-registry-prometheus:$prometeus_version"

Install MicrometerMetrics

To install the MicrometerMetrics feature, pass it to the install function in the application initialization code. This can be the main function …

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

… 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.

tip

The metric names may be different depending on the configured monitoring system.

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:

import io.ktor.features.*
// ...
fun Application.module() {
    val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT)
    install(MicrometerMetrics) {
        registry = appMicrometerRegistry
    }
}

Configure Metrics

The MicrometerMetrics feature 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())
                .sla(
                    Duration.ofMillis(100).toNanos(),
                    Duration.ofMillis(500).toNanos()
                )
                .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:

1. Create a dedicated route that accepts GET requests by the required address (/metrics in the example below).

2. Use call.respond to send scraping data to Prometheus.

fun Application.module() {
    val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT)
    install(MicrometerMetrics) {
        registry = appMicrometerRegistry
        // ...
    }
    routing {
        get("/metrics") {
            call.respond(appMicrometerRegistry.scrape())
        }
    }
}