Client Plugin

Ktor 客户端中的日志记录

所需依赖项: io.ktor:ktor-client-logging

代码示例: client-logging

日志记录是一种通过记录重要事件、错误或信息性消息来跟踪程序运行状况和诊断问题的方式。

Ktor 提供了使用 Logging 插件记录 HTTP 调用的能力。 此插件为不同的平台提供了不同的 Logger 类型。

在服务器端，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

对于 原生目标平台，Logging 插件提供了一个 Logger，它将所有内容打印到标准输出流 (STDOUT)。

Multiplatform

在 多平台项目 中，你可以指定一个 自定义 Logger，例如 Napier。

添加依赖项

要添加 Logging 插件，请在你的构建脚本中包含以下构件：

Gradle (Kotlin)Gradle (Groovy)Maven

你可以通过

添加客户端依赖项

了解如何向现有项目添加客户端依赖项。

了解更多关于 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.Config 类提供了 Logging 插件的配置。以下示例展示了一个配置示例：

logger : 指定一个 Logger 实例。Logger.DEFAULT 使用 SLF4J 日志框架。对于原生目标平台，将此属性设置为 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

要在客户端应用程序中使用自定义 Logger，你需要创建一个 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。