0
# Ktor Client Logging
1

2
Ktor Client Logging is a multiplatform plugin that provides comprehensive HTTP request and response logging capabilities for Ktor HTTP clients. It offers configurable logging levels, multiple output formats, header sanitization for security, and platform-specific logger implementations.
3

4
## Package Information
5

6
- **Package Name**: ktor-client-logging  
7
- **Package Type**: maven
8
- **Language**: Kotlin (Multiplatform)
9
- **Installation**: `implementation("io.ktor:ktor-client-logging:3.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.client.plugins.logging.*
15
```
16

17
For HttpClient configuration:
18

19
```kotlin
20
import io.ktor.client.*
21
import io.ktor.client.plugins.logging.*
22
```
23

24
## Basic Usage
25

26
### Simple Setup
27

28
```kotlin
29
import io.ktor.client.*
30
import io.ktor.client.engine.cio.*
31
import io.ktor.client.plugins.logging.*
32

33
val client = HttpClient(CIO) {
34
    install(Logging) {
35
        level = LogLevel.HEADERS
36
        logger = Logger.DEFAULT
37
    }
38
}
39
```
40

41
### Advanced Configuration
42

43
```kotlin
44
val client = HttpClient(CIO) {
45
    install(Logging) {
46
        level = LogLevel.ALL
47
        logger = Logger.DEFAULT
48
        format = LoggingFormat.OkHttp
49
        
50
        // Filter specific requests
51
        filter { request ->
52
            request.url.host == "api.example.com"
53
        }
54
        
55
        // Sanitize sensitive headers
56
        sanitizeHeader { header ->
57
            header == "Authorization" || header == "X-API-Key"
58
        }
59
    }
60
}
61
```
62

63
## Architecture
64

65
The Ktor Client Logging plugin is built around several key components:
66

67
- **Plugin System**: Integrates with Ktor's client plugin architecture through `ClientPlugin<LoggingConfig>`
68
- **Configuration DSL**: Type-safe configuration using `LoggingConfig` class with `@KtorDsl` annotation
69
- **Logging Levels**: Enum-based level system (`LogLevel`) controlling what information is logged
70
- **Logger Interface**: Abstracted logging through `Logger` interface with platform-specific implementations
71
- **Content Handling**: Smart content detection and logging for different `OutgoingContent` types
72
- **Pipeline Integration**: Hooks into Ktor's request/response pipeline for comprehensive monitoring
73
- **Security Features**: Built-in header sanitization and request filtering capabilities
74

75
## Capabilities
76

77
### Plugin Installation and Configuration
78

79
Core plugin installation and configuration functionality with comprehensive options for customizing logging behavior.
80

81
```kotlin { .api }
82
/**
83
 * A client's plugin that provides the capability to log HTTP calls
84
 */
85
val Logging: ClientPlugin<LoggingConfig>
86

87
/**
88
 * Configures and installs Logging in HttpClient
89
 */
90
fun HttpClientConfig<*>.Logging(block: LoggingConfig.() -> Unit = {})
91
```
92

93
[Configuration](./configuration.md)
94

95
### Logging Levels and Control
96

97
Granular control over what information gets logged, from basic request info to full request/response bodies.
98

99
```kotlin { .api }
100
enum class LogLevel(
101
    val info: Boolean,
102
    val headers: Boolean,  
103
    val body: Boolean
104
) {
105
    ALL(true, true, true),
106
    HEADERS(true, true, false),
107
    BODY(true, false, true), 
108
    INFO(true, false, false),
109
    NONE(false, false, false)
110
}
111

112
enum class LoggingFormat {
113
    Default,
114
    OkHttp
115
}
116
```
117

118
[Configuration](./configuration.md)
119

120
### Logger Interface and Implementations
121

122
Abstracted logging interface with platform-specific implementations supporting SLF4J, Android Logcat, console logging, and custom loggers.
123

124
```kotlin { .api }
125
interface Logger {
126
    fun log(message: String)
127
    
128
    companion object
129
}
130

131
val Logger.Companion.DEFAULT: Logger
132
val Logger.Companion.SIMPLE: Logger  
133
val Logger.Companion.EMPTY: Logger
134
```
135

136
Platform-specific (JVM only):
137

138
```kotlin { .api }
139
val Logger.Companion.ANDROID: Logger
140

141
class MessageLengthLimitingLogger(
142
    private val maxLength: Int = 4000,
143
    private val minLength: Int = 3000,
144
    private val delegate: Logger = Logger.DEFAULT
145
) : Logger
146
```
147

148
[Loggers](./loggers.md)
149

150
### Utilities and Internal Components
151

152
Internal utility functions and components for content handling, binary detection, and log formatting.
153

154
```kotlin { .api }
155
internal class HttpClientCallLogger(private val logger: Logger)
156

157
internal suspend fun ByteReadChannel.tryReadText(charset: Charset): String?
158

159
internal fun Appendable.logHeaders(
160
    headers: Set<Map.Entry<String, List<String>>>,
161
    sanitizedHeaders: List<SanitizedHeader>
162
)
163
```
164

165
[Utilities](./utilities.md)
166

167
## Core Types
168

169
```kotlin { .api }
170
@KtorDsl
171
class LoggingConfig {
172
    /**
173
     * A general format for logging requests and responses
174
     */
175
    var format: LoggingFormat
176
    
177
    /**
178
     * Specifies a Logger instance
179
     */
180
    var logger: Logger
181
    
182
    /**
183
     * Specifies the logging level
184
     */
185
    var level: LogLevel
186
    
187
    /**
188
     * Allows you to filter log messages for calls matching a predicate
189
     */
190
    fun filter(predicate: (HttpRequestBuilder) -> Boolean)
191
    
192
    /**
193
     * Allows you to sanitize sensitive headers to avoid their values appearing in the logs
194
     */
195
    fun sanitizeHeader(placeholder: String = "***", predicate: (String) -> Boolean)
196
}
197
```