Logging

Logging is a way to keep track of what your program is doing and diagnose problems by recording important events, errors, or informational messages.

Ktor provides the capability to log HTTP calls using the Logging plugin. This plugin provides different logger types for different platforms.

JVM

On JVM, Ktor uses the Simple Logging Facade for Java (SLF4J) as an abstraction layer for logging. SLF4J decouples the logging API from the underlying logging implementation, allowing you to integrate the logging framework that best suits your application's requirements. Common choices include Logback or Log4j. If no framework is provided, SLF4J will default to a no-operation (NOP) implementation, which essentially disables logging.

To enable logging, include an artifact with the required SLF4J implementation, such as Logback:

implementation("ch.qos.logback:logback-classic:$logback_version")

implementation "ch.qos.logback:logback-classic:$logback_version"

        
                    <dependency>
                        <groupId>ch.qos.logback</groupId>
                        <artifactId>logback-classic</artifactId>
                        <version>${logback_version}</version>
                    </dependency>
                    
        

Android

On Android, we recommend to use the SLF4J Android library:

implementation("org.slf4j:slf4j-android:$slf4j_version")

implementation "org.slf4j:slf4j-android:$slf4j_version"

Native

For Native targets, the Logging plugin provides a logger that prints everything to the standard output stream (STDOUT).

Multiplatform

In multiplatform projects, you can specify a custom logger, such as Napier.

Add dependencies

To add the Logging plugin, include the following artifact to your build script:

implementation("io.ktor:ktor-client-logging:$ktor_version")

implementation "io.ktor:ktor-client-logging:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-logging-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

You can learn more about artifacts required by the Ktor client from Adding client dependencies.

Install Logging

To install Logging, pass it to the install function inside a client configuration block:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.logging.*
//...
val client = HttpClient(CIO) {
    install(Logging)
}

Configure Logging

The Logging plugin configuration is provided by the Logging.Config class. The example below shows a sample configuration:

logger: Specifies a Logger instance. Logger.DEFAULT uses an SLF4J logging framework. For Native targets, set this property to Logger.SIMPLE.
level: Specifies the logging level. LogLevel.HEADERS will log only request/response headers.
filter(): Allows you to filter log messages for requests matching the specified predicate. In the example below, only requests made to ktor.io get into the log.
sanitizeHeader(): Allows you to sanitize sensitive headers to avoid their values appearing in the logs. In the example below, the Authorization header value will be replaced with '***' when logged.

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/")
    }
}

For the full example, see client-logging.

Provide a custom logger

To use a custom logger in your client application, you need to create a Logger instance and override the log function. The example below shows how to use the Napier library to log HTTP calls:

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/")
    }
}

For the full example, see client-logging-napier.

Last modified: 14 June 2024