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 모니터링을 위한 메트릭 세트도 노출합니다.

레지스트리 생성 ​

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 프로퍼티를 사용하여 분포 통계(distribution statistics)를 구성합니다. 예를 들면 다음과 같습니다:

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에서 확인할 수 있습니다.