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 的指標。

建立 registry ​

安裝 MicrometerMetrics 後,您需要為您的監控系統建立一個 registry 並將其指派給 registry 屬性。在以下範例中,PrometheusMeterRegistry 是在 install 區塊之外建立的,以便能夠在不同的路由處理常式中重複使用此 registry:

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:公開 scrape 端點 ​

如果您使用 Prometheus 作為監控系統,您需要向 Prometheus scraper 公開一個 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。