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) 並將其指派給 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 抓取器 (scraper) 公開一個 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。