Call logging

Ktor provides the capability to log application events using the SLF4J library. You can learn about general logging configuration from the Logging topic.

The CallLogging plugin allows you to log incoming client requests.

Add dependencies

To use CallLogging, you need to include the ktor-server-call-logging artifact in the build script:

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

implementation "io.ktor:ktor-server-call-logging:$ktor_version"

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

Install CallLogging

To install the CallLogging plugin to the application, pass it to the install function in the specified module. The code snippets below show how to install CallLogging...

... inside the embeddedServer function call.
... inside the explicitly defined module, which is an extension function of the Application class.

                    import io.ktor.server.engine.*
                    import io.ktor.server.netty.*
                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.calllogging.*

                    fun main() {
                        embeddedServer(Netty, port = 8080) {
                            install(CallLogging)
                            // ...
                        }.start(wait = true)
                    }
                

                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.calllogging.*
                    // ...
                    fun Application.module() {
                        install(CallLogging)
                        // ...
                    }
                

Configure logging settings

You can configure CallLogging in multiple ways: specify a logging level, filter requests based on a specified condition, customize log messages, and so on. You can see the available configuration settings at CallLoggingConfig.

Set the logging level

By default, Ktor uses the Level.INFO logging level. To change it, use the level property:

    install(CallLogging) {
        level = Level.INFO
    }

Filter log requests

The filter property allows you to add conditions for filtering requests. In the example below, only requests made to /api/v1 get into a log:

    install(CallLogging) {
        filter { call ->
            call.request.path().startsWith("/api/v1")
        }
    }

Customize a log message format

By using the format function, you can put any data related to a request/response into a log. The example below shows how to log a response status, a request HTTP method, and the User-Agent header value for each request.

    install(CallLogging) {
        format { call ->
            val status = call.response.status()
            val httpMethod = call.request.httpMethod.value
            val userAgent = call.request.headers["User-Agent"]
            "Status: $status, HTTP method: $httpMethod, User agent: $userAgent"
        }
    }

You can find the full example here: logging.

Put call parameters in MDC

The CallLogging plugin supports MDC (Mapped Diagnostic Context). You can put a desired context value with the specified name to MDC using the mdc function. For example, in the code snippet below, a name query parameter is added to MDC:

install(CallLogging) {
    mdc("name-parameter") { call ->
        call.request.queryParameters["name"]
    }
}

You can access the added value during an ApplicationCall lifetime:

import org.slf4j.MDC
// ...
MDC.get("name-parameter")

Last modified: 08 August 2024