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 함수 호출 내부.
• ... Application 클래스의 확장 함수인 명시적으로 정의된 module 내부.

embeddedServermodule

노출된 메트릭

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 속성에 할당해야 합니다. 아래 예시에서는 다른 경로 핸들러에서 이 레지스트리를 재사용할 수 있도록 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 요청을 수락하는 전용 경로 (route)를 생성합니다.

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.