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종속성 추가:kotlinimplementation(ktorLibs.server.metrics.micrometer)위의 코드 스니펫은 Ktor 종속성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.groovyimplementation 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용 아티팩트를 추가하는 방법을 보여줍니다:
kotlinimplementation("io.micrometer:micrometer-registry-prometheus:$prometheus_version")groovyimplementation "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()확장 함수 내에서 설치.
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)
}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를 생성합니다:
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 프로퍼티를 사용하여 분포 통계(distribution statistics)를 구성합니다. 예를 들면 다음과 같습니다:
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에서는 다음과 같은 방법으로 이를 수행할 수 있습니다:
필요한 주소(아래 예제에서는
/metrics)로 GET 요청을 수락하는 전용 라우트를 생성합니다.call.respond를 사용하여 Prometheus에 스크랩 데이터를 전송합니다.kotlinfun Application.module() { val appMicrometerRegistry = PrometheusMeterRegistry(PrometheusConfig.DEFAULT) install(MicrometerMetrics) { registry = appMicrometerRegistry } routing { get("/metrics") { call.respond(appMicrometerRegistry.scrape()) } } }전체 예제는 micrometer-metrics에서 확인할 수 있습니다.
