Skip to content
Server Plugin

Micrometer メトリクス

必要な依存関係: io.ktor:ktor-server-metrics-micrometer

コード例: micrometer-metrics

Nativeサーバー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 を監視するための一連のメトリクスも公開します。

レジストリの作成 ​

MicrometerMetrics をインストールした後、モニタリングシステム用のレジストリを作成し、それを registry プロパティに割り当てる必要があります。以下の例では、異なるルートハンドラーでこのレジストリを再利用できるように、install ブロックの外側で PrometheusMeterRegistry を作成しています:

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: スクレイプエンドポイントの公開 ​

モニタリングシステムとして Prometheus を使用する場合、Prometheus スクレイパーに 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。