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 依赖项：

  Gradle (Kotlin)Gradle (Groovy)Maven

• 添加监控系统所需的依赖项。下面的示例展示了如何为 Prometheus 添加构件：

  Gradle (Kotlin)Gradle (Groovy)Maven

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

安装 MicrometerMetrics

要将 MicrometerMetrics 插件安装到应用程序中， 请将其传递给指定

模块

模块允许您通过对路由进行分组来组织应用程序。

中的 install 函数。 下面的代码片段展示了如何安装 MicrometerMetrics ...

• ... 在 embeddedServer 函数调用内部。
• ... 在显式定义的 module 内部，它是 Application 类的扩展函数。

embeddedServermodule

暴露的指标

Ktor 暴露以下指标用于监控 HTTP 请求：

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

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

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

除了 HTTP 指标外，Ktor 还暴露一组用于监控 JVM 的指标。

创建注册表

安装 MicrometerMetrics 后，您需要为监控系统创建注册表并将其赋值给 registry 属性。在下面的示例中，PrometheusMeterRegistry 在 install 代码块外部创建，以便能够在不同的路由处理器中重用此注册表：

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

配置指标

MicrometerMetrics 插件提供各种配置选项，可以使用 MicrometerMetricsConfig 进行访问。

计时器

要自定义每个计时器的标签，可以使用为每个请求调用的 timers 函数：

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

分布统计

您可以使用 distributionStatisticConfig 属性配置分布统计，例如：

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 属性自定义这些指标的列表，例如：

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

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

Prometheus：暴露抓取端点

如果您使用 Prometheus 作为监控系统，您需要向 Prometheus 抓取器暴露一个 HTTP 端点。在 Ktor 中，您可以通过以下方式实现：

1. 创建一个接受 GET 请求的专用路由，使用所需的地址（在下面的示例中为 /metrics）。

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

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

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