0
# Configuration
1

2
Comprehensive configuration options for the Ktor Client Logging plugin, including logging levels, output formats, filtering, and header sanitization.
3

4
## Capabilities
5

6
### Plugin Installation
7

8
Install and configure the logging plugin in your HttpClient.
9

10
```kotlin { .api }
11
/**
12
 * A client's plugin that provides the capability to log HTTP calls
13
 */
14
val Logging: ClientPlugin<LoggingConfig>
15

16
/**
17
 * Configures and installs Logging in HttpClient
18
 * @param block Configuration lambda for LoggingConfig
19
 */
20
fun HttpClientConfig<*>.Logging(block: LoggingConfig.() -> Unit = {})
21
```
22

23
**Usage Examples:**
24

25
```kotlin
26
import io.ktor.client.*
27
import io.ktor.client.engine.cio.*
28
import io.ktor.client.plugins.logging.*
29

30
// Basic installation
31
val client = HttpClient(CIO) {
32
    install(Logging)
33
}
34

35
// With configuration
36
val client = HttpClient(CIO) { 
37
    install(Logging) {
38
        level = LogLevel.ALL
39
        logger = Logger.SIMPLE
40
        format = LoggingFormat.OkHttp
41
    }
42
}
43

44
// Alternative syntax
45
val client = HttpClient(CIO) {
46
    Logging {
47
        level = LogLevel.HEADERS
48
    }
49
}
50
```
51

52
### Configuration Class
53

54
The main configuration class providing DSL-style configuration options.
55

56
```kotlin { .api }
57
/**
58
 * A configuration for the Logging plugin
59
 */
60
@KtorDsl
61
class LoggingConfig {
62
    /**
63
     * A general format for logging requests and responses
64
     */
65
    var format: LoggingFormat
66
    
67
    /**
68
     * Specifies a Logger instance
69
     */
70
    var logger: Logger
71
    
72
    /**
73
     * Specifies the logging level
74
     */
75
    var level: LogLevel
76
    
77
    /**
78
     * Allows you to filter log messages for calls matching a predicate
79
     * @param predicate Function that receives HttpRequestBuilder and returns Boolean
80
     */
81
    fun filter(predicate: (HttpRequestBuilder) -> Boolean)
82
    
83
    /**
84
     * Allows you to sanitize sensitive headers to avoid their values appearing in the logs
85
     * @param placeholder String to replace sensitive header values (default: "***")
86
     * @param predicate Function that receives header name and returns Boolean
87
     */
88
    fun sanitizeHeader(placeholder: String = "***", predicate: (String) -> Boolean)
89
}
90

91
/**
92
 * Internal data class for header sanitization configuration
93
 */
94
internal class SanitizedHeader(
95
    val placeholder: String,
96
    val predicate: (String) -> Boolean
97
)
98
```
99

100
### Logging Levels
101

102
Control the amount of information logged for each request/response.
103

104
```kotlin { .api }
105
/**
106
 * Logging log level
107
 * @param info Whether to log basic request/response info
108
 * @param headers Whether to log headers
109
 * @param body Whether to log request/response body
110
 */
111
enum class LogLevel(
112
    val info: Boolean,
113
    val headers: Boolean,
114
    val body: Boolean
115
) {
116
    /** Log everything: request info, headers, and body */
117
    ALL(true, true, true),
118
    /** Log request info and headers, but not body */
119
    HEADERS(true, true, false),
120
    /** Log request info and body, but not headers */
121
    BODY(true, false, true),
122
    /** Log only basic request info */
123
    INFO(true, false, false),
124
    /** Disable logging */
125
    NONE(false, false, false)
126
}
127
```
128

129
**Usage Examples:**
130

131
```kotlin
132
install(Logging) {
133
    level = LogLevel.ALL       // Log everything
134
    level = LogLevel.HEADERS   // Log info + headers (default)
135
    level = LogLevel.BODY      // Log info + body
136
    level = LogLevel.INFO      // Log basic info only
137
    level = LogLevel.NONE      // No logging
138
}
139
```
140

141
### Logging Formats
142

143
Choose between different output formats for logged information.
144

145
```kotlin { .api }
146
/**
147
 * General format for logging requests and responses
148
 */
149
enum class LoggingFormat {
150
    /** Standard Ktor logging format */
151
    Default,
152
    
153
    /**
154
     * OkHttp logging format
155
     * Writes only application-level logs because the low-level HTTP communication 
156
     * is hidden within the engine implementations
157
     */
158
    OkHttp
159
}
160
```
161

162
**Usage Examples:**
163

164
```kotlin
165
install(Logging) {
166
    format = LoggingFormat.Default  // Standard Ktor format
167
    format = LoggingFormat.OkHttp   // OkHttp-compatible format
168
}
169
```
170

171
### Request Filtering
172

173
Filter which requests should be logged based on custom criteria.
174

175
```kotlin { .api }
176
/**
177
 * Add a filter predicate to control which requests are logged
178
 * @param predicate Function receiving HttpRequestBuilder, returns true to log
179
 */
180
fun LoggingConfig.filter(predicate: (HttpRequestBuilder) -> Boolean)
181
```
182

183
**Usage Examples:**
184

185
```kotlin
186
import io.ktor.client.request.*
187
import io.ktor.http.*
188

189
install(Logging) {
190
    // Only log requests to specific host
191
    filter { request ->
192
        request.url.host == "api.example.com"
193
    }
194
    
195
    // Only log POST requests
196
    filter { request ->
197
        request.method == HttpMethod.Post
198
    }
199
    
200
    // Only log requests with specific header
201
    filter { request ->
202
        request.headers.contains("X-Debug")
203
    }
204
    
205
    // Combine multiple filters (all must return true)
206
    filter { request -> request.url.host == "api.example.com" }
207
    filter { request -> request.method == HttpMethod.Post }
208
}
209
```
210

211
### Header Sanitization
212

213
Protect sensitive header values from appearing in logs.
214

215
```kotlin { .api }
216
/**
217
 * Sanitize sensitive headers to avoid their values appearing in the logs
218
 * @param placeholder String to replace sensitive values with (default: "***")
219
 * @param predicate Function receiving header name, returns true to sanitize
220
 */
221
fun LoggingConfig.sanitizeHeader(placeholder: String = "***", predicate: (String) -> Boolean)
222
```
223

224
**Usage Examples:**
225

226
```kotlin
227
import io.ktor.http.*
228

229
install(Logging) {
230
    // Sanitize Authorization header with default placeholder
231
    sanitizeHeader { header -> 
232
        header == HttpHeaders.Authorization 
233
    }
234
    
235
    // Sanitize multiple headers with custom placeholder
236
    sanitizeHeader("██") { header ->
237
        header == "X-API-Key" || header == "X-Secret-Token"
238
    }
239
    
240
    // Sanitize headers by pattern
241
    sanitizeHeader("[REDACTED]") { header ->
242
        header.lowercase().contains("auth") || 
243
        header.lowercase().contains("key") ||
244
        header.lowercase().contains("token")
245
    }
246
    
247
    // Multiple sanitization rules
248
    sanitizeHeader("***") { it == HttpHeaders.Authorization }
249
    sanitizeHeader("██") { it.startsWith("X-Secret-") }
250
}
251
```
252

253
## Advanced Configuration Examples
254

255
### Production Configuration
256

257
```kotlin
258
val client = HttpClient(CIO) {
259
    install(Logging) {
260
        level = LogLevel.INFO  // Basic info only in production
261
        logger = Logger.DEFAULT  // Use SLF4J/platform logger
262
        
263
        // Only log failed requests
264
        filter { request ->
265
            // This would require additional logic to detect failures
266
            true
267
        }
268
        
269
        // Sanitize all sensitive headers
270
        sanitizeHeader { header ->
271
            val sensitiveHeaders = setOf(
272
                "Authorization", "X-API-Key", "X-Auth-Token",
273
                "Cookie", "Set-Cookie", "X-Secret"
274
            )
275
            header in sensitiveHeaders
276
        }
277
    }
278
}
279
```
280

281
### Development Configuration
282

283
```kotlin
284
val client = HttpClient(CIO) {
285
    install(Logging) {
286
        level = LogLevel.ALL  // Log everything for debugging
287
        logger = Logger.SIMPLE  // Console output
288
        format = LoggingFormat.OkHttp  // Readable format
289
        
290
        // Log only API calls (skip assets)
291
        filter { request ->
292
            !request.url.pathSegments.any { it.contains('.') }
293
        }
294
    }
295
}
296
```
297

298
### Testing Configuration
299

300
```kotlin
301
val client = HttpClient(CIO) {
302
    install(Logging) {
303
        level = LogLevel.HEADERS  // Good balance for test visibility
304
        logger = Logger.EMPTY  // No output during tests
305
        
306
        // Only log specific test scenarios
307
        filter { request ->
308
            request.headers.contains("X-Test-Scenario")
309
        }
310
    }
311
}
312
```