Client Plugin

Ktor Client 中的日志记录

所需依赖项：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 实现的构件，例如 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 实例。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。