Client Plugin

Ktor 客戶端中的日誌記錄

所需的依賴項：io.ktor:ktor-client-logging

程式碼範例： client-logging

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

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

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

JVM

在 JVM 上，Ktor 使用適用於 Java 的簡單日誌記錄介面 (SLF4J) 作為日誌記錄的抽象層。SLF4J 將日誌記錄 API 與底層日誌記錄實作解耦， 讓您可以整合最符合應用程式需求的日誌記錄框架。 常見的選擇包括 Logback 或 Log4j。如果沒有提供框架，SLF4J 將預設使用 無操作 (NOP) 實作，這基本上會禁用日誌記錄。

要啟用日誌記錄，請包含一個具有所需 SLF4J 實作的 artifact，例如 Logback：

Gradle (Kotlin)Gradle (Groovy)Maven

Android

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

Gradle (Kotlin)Gradle (Groovy)

Native

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

Multiplatform

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

新增依賴項

要新增 Logging 外掛程式，請在您的建置腳本中包含以下 artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

您可以從

新增客戶端依賴項

了解如何將客戶端依賴項新增到現有專案。

中了解更多關於 Ktor 客戶端所需的 artifact。

安裝 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 實例。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。