Skip to content
Server Plugin

Ktor Server에서 요청 추적하기

필수 의존성: io.ktor:ktor-server-call-id

코드 예제: call-id

Native 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅

CallId 플러그인을 사용하면 고유한 요청 ID 또는 call ID를 통해 클라이언트 요청을 엔드투엔드로 추적할 수 있습니다. 일반적으로 Ktor에서 call ID를 사용하는 작업 흐름은 다음과 같습니다.

  1. 먼저, 다음 방법 중 하나로 특정 요청에 대한 call ID를 가져와야 합니다.
    • 리버스 프록시(예: Nginx)나 클라우드 제공업체(예: Heroku)가 X-Request-Id와 같은 특정 헤더에 call ID를 추가할 수 있습니다. 이 경우 Ktor에서 해당 call ID를 조회(retrieve)할 수 있습니다.
    • 그렇지 않고 요청에 call ID가 포함되어 있지 않은 경우, Ktor 서버에서 직접 생성(generate)할 수 있습니다.
  2. 그런 다음 Ktor는 미리 정의된 딕셔너리(dictionary)를 사용하여 조회되거나 생성된 call ID를 검증(verify)합니다. 원하는 조건을 직접 지정하여 call ID를 검증할 수도 있습니다.
  3. 마지막으로, X-Request-Id와 같은 특정 헤더에 담아 클라이언트로 call ID를 전송(send)할 수 있습니다.

CallId를 CallLogging과 함께 사용하면 call ID를 MDC 컨텍스트에 넣고 각 요청마다 call ID가 표시되도록 로거를 구성하여 호출 문제를 손쉽게 디버깅할 수 있습니다.

클라이언트 측의 경우, Ktor는 클라이언트 요청 추적을 위한 CallId 플러그인을 제공합니다.

의존성 추가 ​

CallId를 사용하려면 빌드 스크립트에 ktor-server-call-id 아티팩트를 추가하세요.

kotlin
implementation(ktorLibs.server.callId)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.callId
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-call-id-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CallId 설치 ​

애플리케이션에 CallId 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 플러그인을 전달합니다. 다음 예제는 CallId를 설치하는 방법을 보여줍니다.

  • embeddedServer() 함수 호출 내부에서 설치
  • Application 클래스에 명시적으로 정의된 module() 확장 함수 내부에서 설치
kotlin
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)
}
kotlin
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 함수를 사용합니다. 예를 들면 다음과 같습니다.

    kotlin
    install(CallId) {
        retrieveFromHeader(HttpHeaders.XRequestId)
    }

    header 함수를 사용하여 동일한 헤더에서 call ID를 조회하고 클라이언트로 전송할 수도 있습니다.

  • 필요한 경우 ApplicationCall에서 직접 call ID를 가져올 수 있습니다.

    kotlin
    install(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를 생성합니다.
    kotlin
    install(CallId) {
        val counter = atomic(0)
        generate {
            "generated-call-id-${counter.getAndIncrement()}"
        }
    }

call ID 검증 ​

조회되거나 생성된 모든 call ID는 다음과 같은 기본 딕셔너리를 사용하여 검증됩니다.

kotlin
CALL_ID_DEFAULT_DICTIONARY: String = "abcdefghijklmnopqrstuvwxyz0123456789+/=-"

즉, 대문자가 포함된 call ID는 검증을 통과하지 못합니다. 필요한 경우 verify 함수를 사용하여 덜 엄격한 규칙을 적용할 수 있습니다.

kotlin
install(CallId) {
    verify { callId: String ->
        callId.isNotEmpty()
    }
}

전체 예제는 call-id에서 확인할 수 있습니다.

클라이언트로 call ID 전송 ​

call ID를 조회하거나 생성한 후에는 클라이언트로 전송할 수 있습니다.

  • header 함수를 사용하면 call ID를 조회하고 동일한 헤더에 담아 전송할 수 있습니다.

    kotlin
    install(CallId) {
        header(HttpHeaders.XRequestId)
    }

    전체 예제는 call-id에서 확인할 수 있습니다.

  • replyToHeader 함수는 지정된 헤더에 call ID를 담아 전송합니다.

    kotlin
    install(CallId) {
        replyToHeader(HttpHeaders.XRequestId)
    }
  • 필요한 경우 ApplicationCall을 사용하여 응답(response)에 call ID를 보낼 수 있습니다.

    kotlin
    reply { call, callId ->
        call.response.header(HttpHeaders.XRequestId, callId)
    }

MDC에 call ID 넣기 ​

CallId를 CallLogging과 함께 사용하면 MDC 컨텍스트에 call ID를 넣고 각 요청에 대해 call ID를 표시하도록 로거를 구성하여 호출 문제를 해결하는 데 도움이 됩니다. 이렇게 하려면 CallLogging 구성 블록 내에서 callIdMdc 함수를 호출하고 MDC 컨텍스트에 넣을 원하는 키를 지정합니다.

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