Server Plugin

Micrometer 指標

必要依賴: io.ktor:ktor-server-metrics-micrometer

程式碼範例: micrometer-metrics

原生伺服器

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

支援: ✖️

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 插件安裝到應用程式中， 請將其傳遞給指定

模組

Modules allow you to structure your application by grouping routes.

中的 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。