0
# Ktor Client Logging
1
2
Ktor Client Logging is a plugin for the Ktor HTTP client that provides comprehensive logging capabilities for HTTP requests and responses. It offers configurable log levels, multiple output formats, header sanitization for security, and custom logger implementations with full coroutine safety.
3
4
## Package Information
5
6
- **Package Name**: io.ktor:ktor-client-logging-macosx64
7
- **Package Type**: maven
8
- **Language**: Kotlin (Multiplatform - macOS x64)
9
- **Target Platform**: macOS x64 (Native compilation target)
10
- **Installation**:
11
```kotlin
12
implementation("io.ktor:ktor-client-logging:3.2.0")
13
```
14
15
## Core Imports
16
17
```kotlin
18
import io.ktor.client.plugins.logging.*
19
import io.ktor.client.*
20
import io.ktor.client.request.* // For HttpRequestBuilder (used in filters)
21
import io.ktor.http.* // For HttpMethod, ContentType (used in examples)
22
```
23
24
## Basic Usage
25
26
```kotlin
27
import io.ktor.client.*
28
import io.ktor.client.plugins.logging.*
29
import io.ktor.client.request.*
30
31
// Basic logging setup
32
val client = HttpClient {
33
install(Logging) {
34
level = LogLevel.ALL
35
logger = Logger.SIMPLE
36
}
37
}
38
39
// Make a request - will be automatically logged
40
val response = client.get("https://api.example.com/users")
41
client.close()
42
```
43
44
## Architecture
45
46
The Ktor Client Logging plugin integrates seamlessly with Ktor's client plugin architecture:
47
48
- **Plugin Installation**: Uses Ktor's standard `install()` mechanism with configuration DSL
49
- **Hook System**: Intercepts HTTP pipeline phases (Send, Receive, Response) for comprehensive logging
50
- **Logger Abstraction**: Platform-agnostic Logger interface with concrete implementations
51
- **Coroutine Safety**: Thread-safe logging operations compatible with Ktor's coroutine-based architecture
52
- **Content Handling**: Intelligent binary/text detection and streaming response support
53
54
## Capabilities
55
56
### Plugin Installation and Configuration
57
58
Install and configure the logging plugin in your HTTP client.
59
60
```kotlin { .api }
61
fun HttpClientConfig<*>.Logging(block: LoggingConfig.() -> Unit = {})
62
63
val Logging: ClientPlugin<LoggingConfig>
64
```
65
66
**Usage Example:**
67
68
```kotlin
69
val client = HttpClient {
70
install(Logging) {
71
level = LogLevel.HEADERS
72
logger = Logger.DEFAULT
73
format = LoggingFormat.Default
74
75
// Filter specific requests
76
filter { request ->
77
request.url.host == "api.example.com"
78
}
79
80
// Sanitize sensitive headers
81
sanitizeHeader { header ->
82
header == "Authorization"
83
}
84
}
85
}
86
```
87
88
### Logging Configuration
89
90
Configure logging behavior through the LoggingConfig class.
91
92
```kotlin { .api }
93
@KtorDsl
94
class LoggingConfig {
95
var format: LoggingFormat
96
var logger: Logger
97
var level: LogLevel
98
99
fun filter(predicate: (HttpRequestBuilder) -> Boolean)
100
fun sanitizeHeader(placeholder: String = "***", predicate: (String) -> Boolean)
101
}
102
```
103
104
### Logging Levels
105
106
Control the amount of information logged with different log levels.
107
108
```kotlin { .api }
109
enum class LogLevel(
110
val info: Boolean,
111
val headers: Boolean,
112
val body: Boolean
113
) {
114
ALL(true, true, true),
115
HEADERS(true, true, false),
116
BODY(true, false, true),
117
INFO(true, false, false),
118
NONE(false, false, false)
119
}
120
```
121
122
**Usage Example:**
123
124
```kotlin
125
install(Logging) {
126
level = LogLevel.ALL // Log everything
127
// level = LogLevel.HEADERS // Log info and headers only
128
// level = LogLevel.INFO // Log basic info only
129
// level = LogLevel.NONE // Disable logging
130
}
131
```
132
133
### Logging Formats
134
135
Choose between different output formats for logged information.
136
137
```kotlin { .api }
138
enum class LoggingFormat {
139
Default,
140
OkHttp
141
}
142
```
143
144
**Usage Example:**
145
146
```kotlin
147
install(Logging) {
148
format = LoggingFormat.Default // Standard Ktor format
149
// format = LoggingFormat.OkHttp // OkHttp-compatible format
150
}
151
```
152
153
### Logger Interface
154
155
Implement custom logging behavior through the Logger interface.
156
157
```kotlin { .api }
158
interface Logger {
159
fun log(message: String)
160
161
companion object
162
}
163
```
164
165
### Built-in Loggers
166
167
Platform-specific logger implementations for different environments.
168
169
```kotlin { .api }
170
// Common loggers available on all platforms
171
val Logger.Companion.SIMPLE: Logger
172
val Logger.Companion.EMPTY: Logger
173
174
// Platform-specific default logger
175
expect val Logger.Companion.DEFAULT: Logger
176
```
177
178
**For macOS (Native/POSIX platforms):**
179
```kotlin { .api }
180
actual val Logger.Companion.DEFAULT: Logger // Uses SIMPLE logger
181
```
182
183
**Note:** `Logger.DEFAULT` uses Kotlin Multiplatform's expect/actual mechanism to provide platform-specific implementations. On macOS x64 (and other POSIX platforms), it delegates to `Logger.SIMPLE` which outputs to standard output. This is different from JVM platforms which may use more sophisticated logging frameworks.
184
185
**Usage Examples:**
186
187
```kotlin
188
install(Logging) {
189
logger = Logger.SIMPLE // Prints to stdout with "HttpClient:" prefix
190
// logger = Logger.DEFAULT // Platform-specific logger
191
// logger = Logger.EMPTY // No-op logger for testing
192
193
// Custom logger
194
logger = object : Logger {
195
override fun log(message: String) {
196
println("Custom: $message")
197
}
198
}
199
}
200
```
201
202
### Request Filtering
203
204
Filter which requests should be logged based on custom criteria.
205
206
```kotlin { .api }
207
fun LoggingConfig.filter(predicate: (HttpRequestBuilder) -> Boolean)
208
```
209
210
**Usage Example:**
211
212
```kotlin
213
install(Logging) {
214
// Only log requests to specific domains
215
filter { request ->
216
request.url.host.contains("api.example.com")
217
}
218
219
// Only log POST requests
220
filter { request ->
221
request.method == HttpMethod.Post
222
}
223
224
// Multiple filters (all must pass)
225
filter { request -> request.url.protocol.isSecure() }
226
filter { request -> !request.url.pathSegments.contains("health") }
227
}
228
```
229
230
### Header Sanitization
231
232
Sanitize sensitive header values to prevent exposure in logs.
233
234
```kotlin { .api }
235
fun LoggingConfig.sanitizeHeader(
236
placeholder: String = "***",
237
predicate: (String) -> Boolean
238
)
239
```
240
241
**Note:** When using `LoggingFormat.OkHttp`, the plugin internally uses "██" as the default placeholder regardless of the configured placeholder value.
242
243
**Usage Example:**
244
245
```kotlin
246
install(Logging) {
247
// Sanitize Authorization headers
248
sanitizeHeader { header ->
249
header.equals("Authorization", ignoreCase = true)
250
}
251
252
// Sanitize multiple headers with custom placeholder
253
sanitizeHeader("████") { header ->
254
header in listOf("Authorization", "X-API-Key", "Cookie")
255
}
256
257
// Sanitize based on header patterns
258
sanitizeHeader { header ->
259
header.contains("token", ignoreCase = true) ||
260
header.contains("secret", ignoreCase = true)
261
}
262
}
263
```
264
265
## Error Handling
266
267
The logging plugin is designed to be resilient and will not throw exceptions that interrupt HTTP requests:
268
269
- **Binary Content Detection**: Automatically detects and handles binary content to avoid logging corruption
270
- **Content Length Handling**: Gracefully handles unknown content lengths and streaming responses
271
- **Encoding Support**: Properly handles different character encodings and compressed content
272
- **Exception Isolation**: Logging failures are caught and handled without affecting HTTP operations
273
274
**Common Patterns:**
275
276
```kotlin
277
install(Logging) {
278
level = LogLevel.ALL
279
280
// The plugin will automatically:
281
// - Detect binary vs text content
282
// - Handle streaming responses
283
// - Sanitize specified headers
284
// - Log request/response exceptions
285
// - Preserve original request/response data
286
}
287
```