Skip to content
Client Plugin

Ktor Client의 로깅

필수 의존성: io.ktor:ktor-client-logging

코드 예제: client-logging

로깅(Logging)은 중요한 이벤트, 오류 또는 정보성 메시지를 기록하여 프로그램이 수행하는 작업을 추적하고 문제를 진단하는 방법입니다.

Ktor는 Logging 플러그인을 사용하여 HTTP 호출을 로깅하는 기능을 제공합니다. 이 플러그인은 플랫폼별로 다양한 로거 타입을 제공합니다.

서버 환경에서 Ktor는 애플리케이션 로깅을 위한 Logging 플러그인과 클라이언트 요청 로깅을 위한 CallLogging 플러그인을 제공합니다.

JVM ​

JVM에서 Ktor는 로깅을 위한 추상화 계층으로 Simple Logging Facade for Java(SLF4J)를 사용합니다. SLF4J는 로깅 API를 기반 로깅 구현체와 분리하여 애플리케이션 요구사항에 가장 적합한 로깅 프레임워크를 연동할 수 있도록 해줍니다. 일반적으로 Logback이나 Log4j를 많이 사용합니다. 별도의 프레임워크가 제공되지 않는 경우 SLF4J는 기본적으로 no-operation(NOP) 구현체를 사용하며, 이는 사실상 로깅을 비활성화합니다.

로깅을 활성화하려면 Logback과 같이 필요한 SLF4J 구현체가 포함된 아티팩트를 추가하세요:

kotlin
implementation("ch.qos.logback:logback-classic:$logback_version")
groovy
implementation "ch.qos.logback:logback-classic:$logback_version"
xml
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>${logback_version}</version>
</dependency>

Android ​

Android에서는 SLF4J Android 라이브러리를 사용하는 것을 권장합니다:

kotlin
implementation("org.slf4j:slf4j-android:$slf4j_version")
groovy
implementation "org.slf4j:slf4j-android:$slf4j_version"

Native ​

Native 타깃의 경우, Logging 플러그인은 모든 내용을 표준 출력 스트림(STDOUT)에 출력하는 로거를 제공합니다.

멀티플랫폼 ​

멀티플랫폼 프로젝트에서는 Napier와 같은 커스텀 로거를 지정할 수 있습니다.

의존성 추가 ​

Logging 플러그인을 추가하려면 빌드 스크립트에 다음 아티팩트를 포함하세요:

kotlin
implementation(ktorLibs.client.logging)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.logging
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-logging-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은 클라이언트 의존성 추가기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.를 참조하세요.

Logging 설치 ​

Logging을 설치하려면 클라이언트 구성 블록 내부의 install 함수에 전달하세요:

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.logging.*
//...
val client = HttpClient(CIO) {
    install(Logging)
}

Logging 구성 ​

Logging 플러그인 구성은 Logging.Config 클래스를 통해 제공됩니다. 아래 예제는 샘플 구성을 보여줍니다:

logger : Logger 인스턴스를 지정합니다. Logger.DEFAULT는 SLF4J 로깅 프레임워크를 사용합니다. Native 타깃의 경우 이 프로퍼티를 Logger.SIMPLE로 설정하세요.

level : 로깅 레벨을 지정합니다. LogLevel.HEADERS는 요청/응답 헤더만 로깅합니다.

filter() : 지정된 조건식(predicate)과 일치하는 요청에 대해서만 로그 메시지를 필터링할 수 있도록 합니다. 아래 예제에서는 ktor.io로 전송된 요청만 로그에 기록됩니다.

sanitizeHeader() : 로그에 민감한 정보가 노출되지 않도록 헤더 값을 마스킹(sanitize)할 수 있습니다. 아래 예제에서는 Authorization 헤더 값이 로깅될 때 '***'로 대체됩니다.

kotlin
package com.example

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.logging.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.coroutines.runBlocking

fun main() {
    runBlocking {
        val client = HttpClient(CIO) {
            install(Logging) {
                logger = Logger.DEFAULT
                level = LogLevel.HEADERS
                filter { request ->
                    request.url.host.contains("ktor.io")
                }
                sanitizeHeader { header -> header == HttpHeaders.Authorization }
            }
        }

        val response1: HttpResponse = client.get("https://ktor.io/")
        val response2: HttpResponse = client.get("https://jetbrains.com/")
    }
}

전체 예제는 client-logging을 참조하세요.

커스텀 로거 제공 ​

클라이언트 애플리케이션에서 커스텀 로거를 사용하려면 Logger 인스턴스를 생성하고 log 함수를 재정의(override)해야 합니다. 아래 예제는 Napier 라이브러리를 사용하여 HTTP 호출을 로깅하는 방법을 보여줍니다:

kotlin
package com.example

import io.github.aakira.napier.DebugAntilog
import io.github.aakira.napier.Napier
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.logging.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.runBlocking

fun main() {
    runBlocking {
        val client = HttpClient(CIO) {
            install(Logging) {
                logger = object: Logger {
                    override fun log(message: String) {
                        Napier.v("HTTP Client", null, message)
                    }
                }
                level = LogLevel.HEADERS
            }
        }.also { Napier.base(DebugAntilog()) }

        val response: HttpResponse = client.get("https://ktor.io/")
    }
}

전체 예제는 client-logging-napier를 참조하세요.