Skip to content
Server Plugin

Micrometer 指标

所需依赖项:io.ktor:ktor-server-metrics-micrometer

代码示例: micrometer-metrics

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✖️

MicrometerMetrics 插件可在您的 Ktor 服务器应用程序中启用 Micrometer 指标,并允许您选择所需的监控系统,例如 Prometheus、JMX、Elastic 等。默认情况下,Ktor 会公开用于监控 HTTP 请求的指标以及一组用于监控 JVM 的底层指标。您可以自定义这些指标或创建新指标。

添加依赖项 ​

要启用 MicrometerMetrics,您需要在构建脚本中包含以下构件:

  • 添加 ktor-server-metrics-micrometer 依赖项:

    kotlin
    implementation(ktorLibs.server.metrics.micrometer)
    上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    groovy
    implementation ktorLibs.server.metrics.micrometer
    上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-metrics-micrometer-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  • 添加监控系统所需的依赖项。以下示例展示了如何为 Prometheus 添加构件:

    kotlin
    implementation("io.micrometer:micrometer-registry-prometheus:$prometheus_version")
    groovy
    implementation "io.micrometer:micrometer-registry-prometheus:$prometheus_version"
    xml
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
        <version>${prometheus_version}</version>
    </dependency>

    您可以将 $prometheus_version 替换为所需版本的 micrometer-registry-prometheus 构件,例如 1.12.4。

安装 MicrometerMetrics ​

要将 MicrometerMetrics 插件安装到您的应用程序中, 请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。 以下示例展示了如何安装 MicrometerMetrics:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.metrics.micrometer.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(MicrometerMetrics)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.metrics.micrometer.*
// ...
fun Application.module() {
    install(MicrometerMetrics)
    // ...
}

公开的指标 ​

Ktor 公开了以下用于监控 HTTP 请求的指标:

  • ktor.http.server.requests.active:一个用于统计并发 HTTP 请求数的 gauge。该指标不提供任何标签。
  • ktor.http.server.requests:一个用于测量每个请求所耗费时间的 timer。该指标提供了一组用于监控请求数据的标签,包括所请求 URL 的 address、HTTP 方法的 method、处理请求的 Ktor 路由的 route 等。

您可以使用 metricName 配置属性自定义默认的 ktor.http.server.requests 前缀。

指标名称可能会根据配置的监控系统而有所不同。

除 HTTP 指标外,Ktor 还公开了一组用于监控 JVM 的指标。

创建注册表 ​

安装 MicrometerMetrics 后,您需要为您的监控系统创建一个注册表,并将其赋值给 registry 属性。在以下示例中,PrometheusMeterRegistry 是在 install 代码块外部创建的,以便能够在不同的路由处理程序中复用该注册表:

kotlin
fun Application.module() {
    val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT)
    install(MicrometerMetrics) {
        registry = appMicrometerRegistry
    }
}

配置指标 ​

MicrometerMetrics 插件提供了各种配置选项,可以通过 MicrometerMetricsConfig 进行访问。

计时器 ​

要为每个计时器自定义标签,可以使用针对每个请求调用的 timers 函数:

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

分布统计信息 ​

您可以使用 distributionStatisticConfig 属性配置分布统计信息,例如:

kotlin
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 与系统指标 ​

除 HTTP 指标外,Ktor 还公开了一组用于监控 JVM 的指标。您可以使用 meterBinders 属性自定义这些指标的列表,例如:

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

您还可以赋值一个空列表来完全禁用这些指标。

Prometheus:公开抓取端点 ​

如果您使用 Prometheus 作为监控系统,则需要向 Prometheus 抓取器公开一个 HTTP 端点。在 Ktor 中,您可以通过以下方式执行此操作:

  1. 创建一个专用路由,用于接收指定地址(在以下示例中为 /metrics)的 GET 请求。

  2. 使用 call.respond 将抓取数据发送至 Prometheus。

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

    您可以在此处找到完整示例:micrometer-metrics。