Skip to content
Server Plugin

Dropwizard 指標

必要相依性:io.ktor:ktor-server-metrics

程式碼範例: dropwizard-metrics

原生伺服器 (Native server)Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✖️

DropwizardMetrics 外掛程式讓您可以設定 Metrics 程式庫,以取得關於伺服器和傳入請求的實用資訊。

新增相依性 ​

若要啟用 DropwizardMetrics,您需要在建置指令碼中包含以下構件:

  • 新增 ktor-server-metrics 相依性:

    kotlin
    implementation(ktorLibs.server.metrics)
    上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
    groovy
    implementation ktorLibs.server.metrics
    上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-metrics-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  • (選用)新增特定回報器 (reporter) 所需的相依性。以下範例展示如何新增透過 JMX 回報指標所需的構件:

    kotlin
    implementation("io.dropwizard.metrics:metrics-jmx:$dropwizard_version")
    groovy
    implementation "io.dropwizard.metrics:metrics-jmx:$dropwizard_version"
    xml
    <dependency>
        <groupId>io.dropwizard.metrics</groupId>
        <artifactId>metrics-jmx</artifactId>
        <version>${dropwizard_version}</version>
    </dependency>

    您可以將 $dropwizard_version 替換為 metrics-jmx 構件所需的版本,例如 4.2.40。

安裝 DropwizardMetrics ​

若要將 DropwizardMetrics 外掛程式安裝至您的應用程式,請在指定的 模組模組可讓您透過對路由進行分組來建構應用程式。 中將其傳遞給 install 函式。 以下範例展示如何安裝 DropwizardMetrics:

  • 在 embeddedServer() 函式呼叫中。
  • 在 Application 類別上明確定義的 module() 擴充函式中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.metrics.dropwizard.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(DropwizardMetrics)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.metrics.dropwizard.*
// ...
fun Application.module() {
    install(DropwizardMetrics)
    // ...
}

設定 DropwizardMetrics ​

DropwizardMetrics 允許您透過 registry 屬性使用任何受支援的 Metric 回報器。讓我們來看看如何設定 SLF4J 與 JMX 回報器。

SLF4J 回報器 ​

SLF4J 回報器允許您定期向 SLF4J 支援的任何輸出發送報告。 例如,若要每 10 秒輸出一次指標,您可以:

kotlin
install(DropwizardMetrics) {
    Slf4jReporter.forRegistry(registry)
        .outputTo(this@module.log)
        .convertRatesTo(TimeUnit.SECONDS)
        .convertDurationsTo(TimeUnit.MILLISECONDS)
        .build()
        .start(10, TimeUnit.SECONDS)
}

您可以在此處找到完整的範例:dropwizard-metrics。

如果您執行應用程式並開啟 http://0.0.0.0:8080,輸出將如下所示:

Bash
[DefaultDispatcher-worker-1] INFO  Application - Responding at http://0.0.0.0:8080
... type=COUNTER, name=ktor.calls.active, count=0
... type=METER, name=ktor.calls./(method:GET).200, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.98655785084844, rate_unit=events/second
... type=METER, name=ktor.calls./(method:GET).meter, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9841134429134598, rate_unit=events/second
... type=METER, name=ktor.calls.exceptions, count=0, m1_rate=0.0, m5_rate=0.0, m15_rate=0.0, mean_rate=0.0, rate_unit=events/second
... type=METER, name=ktor.calls.status.200, count=6, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9866015088545449, rate_unit=events/second
... type=TIMER, name=ktor.calls./(method:GET).timer, count=6, min=0.359683, max=14.213046, mean=2.691307542732234, stddev=5.099546889849414, p50=0.400967, p75=0.618972, p95=14.213046, p98=14.213046, p99=14.213046, p999=14.213046, m1_rate=1.2, m5_rate=1.2, m15_rate=1.2, mean_rate=0.9830677128229028, rate_unit=events/second, duration_unit=milliseconds
... type=TIMER, name=ktor.calls.duration, count=6, min=0.732149, max=33.735719, mean=6.238046092985701, stddev=12.169258340009847, p50=0.778864, p75=1.050454, p95=33.735719, p98=33.735719, p99=33.735719, p999=33.735719, m1_rate=0.2, m5_rate=0.2, m15_rate=0.2, mean_rate=0.6040311229887146, rate_unit=events/second, duration_unit=milliseconds

JMX 回報器 ​

JMX 回報器允許您將所有指標公開至 JMX,讓您可以使用 jconsole 檢視這些指標。

kotlin
install(DropwizardMetrics) {
    JmxReporter.forRegistry(registry)
        .convertRatesTo(TimeUnit.SECONDS)
        .convertDurationsTo(TimeUnit.MILLISECONDS)
        .build()
        .start()
}

您可以在此處找到完整的範例:dropwizard-metrics。

如果您執行應用程式並使用 JConsole 連線至其處理程序,指標將如下所示:

Ktor Metrics: JMX

公開的指標 ​

DropwizardMetrics 公開以下指標:

全域指標 ​

全域指標包含以下 Ktor 專屬指標:

  • ktor.calls.active:Count - 尚未完成的活躍請求數。
  • ktor.calls.duration - 關於呼叫持續時間的資訊。
  • ktor.calls.exceptions - 關於例外數量的資訊。
  • ktor.calls.status.NNN - 關於特定 HTTP 狀態碼 NNN 發生次數的資訊。

請注意,指標名稱以 ktor.calls 前綴開頭。您可以使用 baseName 屬性自訂它:

kotlin
install(DropwizardMetrics) {
    baseName = "my.prefix"
}

每個端點的指標 ​

  • "/uri(method:VERB).NNN" - 針對此路徑與動詞發生特定 HTTP 狀態碼 NNN 次數的資訊。
  • "/uri(method:VERB).meter" - 針對此路徑與動詞的呼叫次數資訊。
  • "/uri(method:VERB).timer" - 針對此端點持續時間的資訊。

JVM 指標 ​

除了 HTTP 指標之外,Ktor 還公開了一組用於監控 JVM 的指標。您可以使用 registerJvmMetricSets 屬性停用這些指標:

kotlin
install(DropwizardMetrics) {
    registerJvmMetricSets = false
}

您可以在此處找到完整的範例:dropwizard-metrics。