Skip to content
Client Plugin

Ktor Client 中的日誌記錄

必要相依性:io.ktor:ktor-client-logging

程式碼範例: client-logging

日誌記錄是一種透過記錄重要事件、錯誤或資訊性訊息,來追蹤程式正在執行的操作並診斷問題的方法。

Ktor 提供了使用 Logging 外掛程式記錄 HTTP 呼叫的功能。 此外掛程式針對不同平台提供了不同的記錄器 (logger) 類型。

在伺服器端,Ktor 提供了用於應用程式日誌記錄的 Logging 外掛程式,以及用於記錄用戶端請求的 CallLogging 外掛程式。

JVM ​

在 JVM 上,Ktor 使用 Simple Logging Facade for Java (SLF4J) 作為日誌記錄的抽象層。SLF4J 將日誌 API 與底層的日誌實作分離, 讓你可以整合最符合應用程式需求的日誌架構。 常見的選擇包括 Logback 或 Log4j。如果未提供任何架構,SLF4J 將預設使用無操作 (NOP) 實作,這基本上會停用日誌記錄。

若要啟用日誌記錄,請引入包含所需 SLF4J 實作的構件,例如 Logback:

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) 的記錄器。

多平台 (Multiplatform) ​

在多平台專案中,你可以指定自訂記錄器,例如 Napier。

新增相依性 ​

若要新增 Logging 外掛程式,請在建置指令碼中引入以下構件:

kotlin
implementation(ktorLibs.client.logging)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.logging
上述程式碼片段使用 Ktor version catalog 來指定 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() : 允許你篩選符合指定述詞之請求的日誌訊息。在以下範例中,只有傳送至 ktor.io 的請求才會被記錄。

sanitizeHeader() : 允許你清理敏感標頭,避免其值出現在日誌中。在以下範例中,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 函式。 以下範例展示了如何使用 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。