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: 同時HTTPリクエスト数をカウントするゲージ。このメトリクスにはタグは提供されません。
• ktor.http.server.requests: 各リクエストの時間を測定するためのタイマー。このメトリクスは、要求された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を監視システムとして使用する場合、Prometheusスクレイパーに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。