Ktor Server에서 요청 추적하기
필수 의존성: io.ktor:ktor-server-call-id
코드 예제: call-id
Native 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
CallId 플러그인을 사용하면 고유한 요청 ID 또는 call ID를 통해 클라이언트 요청을 엔드투엔드로 추적할 수 있습니다. 일반적으로 Ktor에서 call ID를 사용하는 작업 흐름은 다음과 같습니다.
- 먼저, 다음 방법 중 하나로 특정 요청에 대한 call ID를 가져와야 합니다.
- 리버스 프록시(예: Nginx)나 클라우드 제공업체(예: Heroku)가
X-Request-Id와 같은 특정 헤더에 call ID를 추가할 수 있습니다. 이 경우 Ktor에서 해당 call ID를 조회(retrieve)할 수 있습니다. - 그렇지 않고 요청에 call ID가 포함되어 있지 않은 경우, Ktor 서버에서 직접 생성(generate)할 수 있습니다.
- 리버스 프록시(예: Nginx)나 클라우드 제공업체(예: Heroku)가
- 그런 다음 Ktor는 미리 정의된 딕셔너리(dictionary)를 사용하여 조회되거나 생성된 call ID를 검증(verify)합니다. 원하는 조건을 직접 지정하여 call ID를 검증할 수도 있습니다.
- 마지막으로,
X-Request-Id와 같은 특정 헤더에 담아 클라이언트로 call ID를 전송(send)할 수 있습니다.
CallId를 CallLogging과 함께 사용하면 call ID를 MDC 컨텍스트에 넣고 각 요청마다 call ID가 표시되도록 로거를 구성하여 호출 문제를 손쉽게 디버깅할 수 있습니다.
클라이언트 측의 경우, Ktor는 클라이언트 요청 추적을 위한 CallId 플러그인을 제공합니다.
의존성 추가
CallId를 사용하려면 빌드 스크립트에 ktor-server-call-id 아티팩트를 추가하세요.
implementation(ktorLibs.server.callId)implementation ktorLibs.server.callId<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-call-id-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CallId 설치
애플리케이션에 CallId 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 플러그인을 전달합니다. 다음 예제는 CallId를 설치하는 방법을 보여줍니다.
embeddedServer()함수 호출 내부에서 설치Application클래스에 명시적으로 정의된module()확장 함수 내부에서 설치
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.callid.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(CallId)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.callid.*
// ...
fun Application.module() {
install(CallId)
// ...
}CallId 구성
call ID 조회
CallId는 call ID를 가져오는 여러 가지 방법을 제공합니다.
지정된 헤더에서 call ID를 조회하려면
retrieveFromHeader함수를 사용합니다. 예를 들면 다음과 같습니다.kotlininstall(CallId) { retrieveFromHeader(HttpHeaders.XRequestId) }header함수를 사용하여 동일한 헤더에서 call ID를 조회하고 클라이언트로 전송할 수도 있습니다.필요한 경우
ApplicationCall에서 직접 call ID를 가져올 수 있습니다.kotlininstall(CallId) { retrieve { call -> call.request.header(HttpHeaders.XRequestId) } }
조회된 모든 call ID는 기본 딕셔너리를 사용하여 검증됩니다.
call ID 생성
들어오는 요청에 call ID가 포함되어 있지 않은 경우 generate 함수를 사용하여 생성할 수 있습니다.
- 아래 예제는 미리 정의된 딕셔너리에서 특정 길이의 call ID를 생성하는 방법을 보여줍니다.kotlin
install(CallId) { generate(10, "abcde12345") } - 아래 예제에서는
generate함수에 블록을 전달하여 call ID를 생성합니다.kotlininstall(CallId) { val counter = atomic(0) generate { "generated-call-id-${counter.getAndIncrement()}" } }
call ID 검증
조회되거나 생성된 모든 call ID는 다음과 같은 기본 딕셔너리를 사용하여 검증됩니다.
CALL_ID_DEFAULT_DICTIONARY: String = "abcdefghijklmnopqrstuvwxyz0123456789+/=-"즉, 대문자가 포함된 call ID는 검증을 통과하지 못합니다. 필요한 경우 verify 함수를 사용하여 덜 엄격한 규칙을 적용할 수 있습니다.
install(CallId) {
verify { callId: String ->
callId.isNotEmpty()
}
}전체 예제는 call-id에서 확인할 수 있습니다.
클라이언트로 call ID 전송
call ID를 조회하거나 생성한 후에는 클라이언트로 전송할 수 있습니다.
header함수를 사용하면 call ID를 조회하고 동일한 헤더에 담아 전송할 수 있습니다.kotlininstall(CallId) { header(HttpHeaders.XRequestId) }전체 예제는 call-id에서 확인할 수 있습니다.
replyToHeader함수는 지정된 헤더에 call ID를 담아 전송합니다.kotlininstall(CallId) { replyToHeader(HttpHeaders.XRequestId) }필요한 경우
ApplicationCall을 사용하여 응답(response)에 call ID를 보낼 수 있습니다.kotlinreply { call, callId -> call.response.header(HttpHeaders.XRequestId, callId) }
MDC에 call ID 넣기
CallId를 CallLogging과 함께 사용하면 MDC 컨텍스트에 call ID를 넣고 각 요청에 대해 call ID를 표시하도록 로거를 구성하여 호출 문제를 해결하는 데 도움이 됩니다. 이렇게 하려면 CallLogging 구성 블록 내에서 callIdMdc 함수를 호출하고 MDC 컨텍스트에 넣을 원하는 키를 지정합니다.
install(CallLogging) {
callIdMdc("call-id")
}이 키를 로거 구성에 전달하여 로그에 call ID가 나타나도록 할 수 있습니다. 예를 들어, logback.xml 파일은 다음과 같이 작성할 수 있습니다.
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %X{call-id} %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>전체 예제는 call-id에서 확인할 수 있습니다.
