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 依存関係を追加します。

  Gradle (Kotlin)Gradle (Groovy)Maven

• モニタリングシステムに必要な依存関係を追加します。以下の例は、Prometheus 用のアーティファクトを追加する方法を示しています。

  Gradle (Kotlin)Gradle (Groovy)Maven

  $prometheus_version は、micrometer-registry-prometheus アーティファクトの必要なバージョン（例: 1.10.3）に置き換えることができます。

MicrometerMetrics のインストール

アプリケーションに MicrometerMetrics プラグインをインストールするには、 指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

内の install 関数に渡します。 以下のコードスニペットは、MicrometerMetrics をインストールする方法を示しています。

• ... embeddedServer 関数の呼び出し内。
• ... Application クラスの拡張関数である明示的に定義された module 内。

embeddedServermodule

公開されるメトリクス

Ktor は HTTP リクエストをモニタリングするために以下のメトリクスを公開します。

• ktor.http.server.requests.active: 同時実行 HTTP リクエストの数をカウントする gauge (ゲージ)。このメトリクスにはタグはありません。
• ktor.http.server.requests: 各リクエストの時間を測定する timer (タイマー)。このメトリクスは、リクエストされた URL の address、HTTP メソッドの method、リクエストを処理する Ktor ルートの route など、リクエストデータをモニタリングするための一連のタグを提供します。

デフォルトの ktor.http.server.requests プレフィックスは、metricName 設定プロパティを使用してカスタマイズできます。

メトリクス名は、設定されたモニタリングシステムによって異なる場合があります。

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 を使用する場合、HTTP エンドポイントを Prometheus スクレイパーに公開する必要があります。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