Skip to content
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:

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)的记录器。

多平台 ​

在多平台项目中,你可以指定自定义记录器,例如 Napier。

添加依赖项 ​

要添加 Logging 插件,请在构建脚本中包含以下工件:

kotlin
implementation(ktorLibs.client.logging)
上述代码段使用 Ktor 版本目录指定 Ktor 依赖项。
groovy
implementation ktorLibs.client.logging
上述代码段使用 Ktor 版本目录指定 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。