Client Plugin

Ktor Client 中的日誌記錄

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

程式碼範例： client-logging

日誌記錄是一種追蹤程式執行情況，並透過記錄重要事件、錯誤或資訊訊息來診斷問題的方式。

Ktor 提供了使用 Logging 外掛程式記錄 HTTP 呼叫的功能。 此外掛程式為不同平台提供不同的日誌記錄器類型。

在伺服器端，Ktor 為應用程式日誌記錄提供 Logging 外掛程式，並為記錄用戶端請求提供 CallLogging 外掛程式。

JVM

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

若要啟用日誌記錄，請包含具有所需 SLF4J 實作的構件，例如 Logback：

Gradle (Kotlin)Gradle (Groovy)Maven

Android

在 Android 上，我們建議使用 SLF4J Android 程式庫：

Gradle (Kotlin)Gradle (Groovy)

Native

對於 Native 目標，Logging 外掛程式提供了一個將所有內容列印到標準輸出串流 (STDOUT) 的日誌記錄器。

多平台

在 多平台專案 中，您可以指定 自訂日誌記錄器，例如 Napier。

新增相依性

若要新增 Logging 外掛程式，請將以下構件包含在您的建置指令碼中：

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

若要進一步了解 Ktor 用戶端所需的構件，請參閱

新增用戶端相依性

了解如何將用戶端相依性新增至現有專案。

。

安裝 Logging

若要安裝 Logging，請將其傳遞給 用戶端配置區塊 內的 install 函式：

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.DEFAULT 使用 SLF4J 日誌記錄架構。對於 Native 目標，請將此屬性設定為 Logger.SIMPLE。

level : 指定日誌記錄級別。LogLevel.HEADERS 將僅記錄請求/回應標頭。

filter() : 允許您為符合指定述句的請求篩選日誌訊息。在下面的範例中，只有發送到 ktor.io 的請求會進入日誌。

sanitizeHeader() : 允許您淨化敏感標頭，以避免它們的值出現在日誌中。在下面的範例中，Authorization 標頭值在記錄時將被替換為 '***'。

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 呼叫：

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。