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：一个 gauge，用于统计并发 HTTP 请求的数量。此指标不提供任何标签。
• ktor.http.server.requests：一个 timer，用于测量每个请求的时间。此指标提供了一组用于监控请求数据的标签，包括请求 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. 创建一个专用的路由，用于接收指定地址（在下面的示例中为 /metrics）的 GET 请求。

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。