0
# Log Levels and Formats
1

2
The Ktor Client Logging plugin provides fine-grained control over what information gets logged and how it's formatted.
3

4
## Required Imports
5

6
```kotlin
7
import io.ktor.client.*
8
import io.ktor.client.plugins.logging.*
9
```
10

11
## Log Levels
12

13
```kotlin { .api }
14
enum class LogLevel(
15
    val info: Boolean,
16
    val headers: Boolean,
17
    val body: Boolean
18
) {
19
    ALL(true, true, true),
20
    HEADERS(true, true, false),
21
    BODY(true, false, true),
22
    INFO(true, false, false),
23
    NONE(false, false, false)
24
}
25
```
26

27
The `LogLevel` enum controls the verbosity of logging output with boolean flags indicating what information categories are included.
28

29
### Level Properties
30

31
Each log level has three boolean properties that determine what gets logged:
32

33
- `info: Boolean` - Basic request/response information (URL, method, status, timing)
34
- `headers: Boolean` - HTTP headers for requests and responses
35
- `body: Boolean` - Request and response body content
36

37
### Available Levels
38

39
#### ALL
40
```kotlin
41
LogLevel.ALL(true, true, true)
42
```
43
Logs everything: basic info, headers, and body content. Most verbose option.
44

45
**Example Output:**
46
```
47
REQUEST: https://api.example.com/users
48
METHOD: POST
49
COMMON HEADERS
50
-> Content-Type: application/json
51
-> Authorization: ***
52
CONTENT HEADERS
53
-> Content-Length: 156
54
BODY Content-Type: application/json
55
BODY START
56
{"name":"John Doe","email":"john@example.com"}
57
BODY END
58

59
RESPONSE: 201 Created
60
METHOD: POST
61
FROM: https://api.example.com/users
62
COMMON HEADERS
63
-> Content-Type: application/json
64
-> Server: nginx/1.18.0
65
BODY Content-Type: application/json
66
BODY START
67
{"id":123,"name":"John Doe","email":"john@example.com","created":"2023-01-01T00:00:00Z"}
68
BODY END
69
```
70

71
#### HEADERS
72
```kotlin
73
LogLevel.HEADERS(true, true, false)
74
```
75
Logs basic info and headers but not body content. Good balance for debugging without exposing sensitive payloads.
76

77
**Example Output:**
78
```
79
REQUEST: https://api.example.com/users
80
METHOD: POST
81
COMMON HEADERS
82
-> Content-Type: application/json
83
-> Authorization: ***
84
CONTENT HEADERS
85
-> Content-Length: 156
86

87
RESPONSE: 201 Created
88
METHOD: POST
89
FROM: https://api.example.com/users
90
COMMON HEADERS
91
-> Content-Type: application/json
92
-> Server: nginx/1.18.0
93
```
94

95
#### BODY
96
```kotlin
97
LogLevel.BODY(true, false, true)
98
```
99
Logs basic info and body content but not headers. Useful when headers are not relevant but payload content is important.
100

101
**Example Output:**
102
```
103
REQUEST: https://api.example.com/users
104
METHOD: POST
105
BODY Content-Type: application/json
106
BODY START
107
{"name":"John Doe","email":"john@example.com"}
108
BODY END
109

110
RESPONSE: 201 Created
111
METHOD: POST
112
FROM: https://api.example.com/users
113
BODY Content-Type: application/json
114
BODY START
115
{"id":123,"name":"John Doe","email":"john@example.com"}
116
BODY END
117
```
118

119
#### INFO
120
```kotlin
121
LogLevel.INFO(true, false, false)
122
```
123
Logs only basic request/response information. Minimal logging for production environments.
124

125
**Example Output:**
126
```
127
REQUEST: https://api.example.com/users
128
METHOD: POST
129

130
RESPONSE: 201 Created
131
METHOD: POST
132
FROM: https://api.example.com/users
133
```
134

135
#### NONE
136
```kotlin
137
LogLevel.NONE(false, false, false)
138
```
139
Disables all logging. No output is generated.
140

141
### Usage Examples
142

143
```kotlin
144
// Maximum verbosity
145
Logging {
146
    level = LogLevel.ALL
147
}
148

149
// Production-friendly logging
150
Logging {
151
    level = LogLevel.INFO
152
}
153

154
// Debug headers without exposing payloads
155
Logging {
156
    level = LogLevel.HEADERS
157
}
158

159
// Disable logging entirely
160
Logging {
161
    level = LogLevel.NONE
162
}
163
```
164

165
## Logging Formats
166

167
```kotlin { .api }
168
enum class LoggingFormat {
169
    Default,
170
    OkHttp
171
}
172
```
173

174
The `LoggingFormat` enum controls the overall structure and style of logged output.
175

176
### Available Formats
177

178
#### Default Format
179
```kotlin
180
LoggingFormat.Default
181
```
182

183
Standard Ktor logging format with structured request/response sections and detailed information layout.
184

185
**Characteristics:**
186
- Multi-line structured format
187
- Separate REQUEST and RESPONSE sections
188
- Detailed header and body sections
189
- Clear separation between different information types
190

191
**Example:**
192
```
193
REQUEST: https://api.example.com/users/123
194
METHOD: GET
195
COMMON HEADERS
196
-> Authorization: ***
197
-> User-Agent: Ktor-Client
198

199
RESPONSE: 200 OK
200
METHOD: GET
201
FROM: https://api.example.com/users/123
202
COMMON HEADERS
203
-> Content-Type: application/json
204
-> Content-Length: 87
205
BODY START
206
{"id":123,"name":"John Doe","email":"john@example.com"}
207
BODY END
208
```
209

210
#### OkHttp Format
211
```kotlin
212
LoggingFormat.OkHttp
213
```
214

215
OkHttp-compatible logging format that mimics the popular OkHttp logging interceptor output style. More concise than Default format.
216

217
**Characteristics:**
218
- Single-line start/end markers with timing information
219
- Compact header format
220
- Request/response correlation with timing
221
- Application-level logging only (no low-level HTTP details)
222

223
**Example:**
224
```
225
--> POST /users (156-byte body)
226
Content-Type: application/json
227
Authorization: ██
228

229
{"name":"John Doe","email":"john@example.com"}
230
--> END POST
231

232
<-- 201 Created /users (342ms, 87-byte body)
233
Content-Type: application/json
234
Server: nginx/1.18.0
235

236
{"id":123,"name":"John Doe","email":"john@example.com","created":"2023-01-01T00:00:00Z"}
237
<-- END HTTP (342ms, 87-byte body)
238
```
239

240
### Format-Specific Features
241

242
#### Default Format Features
243
- **Structured Sections**: Clear REQUEST/RESPONSE boundaries
244
- **Header Categorization**: Separates common headers from content headers
245
- **Detailed Body Information**: Explicit BODY START/END markers with content type
246
- **Method Repetition**: Shows HTTP method in both request and response sections
247

248
#### OkHttp Format Features
249
- **Timing Information**: Shows request duration in milliseconds
250
- **Body Size Indication**: Shows expected or actual body sizes
251
- **Compact Headers**: Single-line header format
252
- **Direction Indicators**: `-->` for outgoing, `<--` for incoming
253
- **Binary Detection**: Indicates when binary or encoded content is omitted
254

255
### Binary Content Handling
256

257
Both formats automatically detect and handle binary content:
258

259
**Text Content:**
260
```
261
BODY START
262
{"message": "Hello, World!"}
263
BODY END
264
```
265

266
**Binary Content:**
267
```
268
--> END POST (binary 1024-byte body omitted)
269
```
270

271
**Encoded Content:**
272
```
273
<-- END HTTP (342ms, encoded 2048-byte body omitted)
274
```
275

276
### Format Selection Guidelines
277

278
| Use Case | Recommended Format | Reason |
279
|----------|-------------------|---------|
280
| Development & Debugging | `Default` | More detailed, structured output |
281
| Integration with OkHttp tools | `OkHttp` | Compatible with existing tooling |
282
| Performance monitoring | `OkHttp` | Includes timing information |
283
| Production logging | `OkHttp` | More compact output |
284
| Log analysis | `Default` | Easier to parse structured sections |
285
286
### Combined Configuration Example
287

288
```kotlin
289
Logging {
290
    // Detailed logging for development
291
    level = LogLevel.ALL
292
    format = LoggingFormat.Default
293
}
294

295
// vs
296

297
Logging {
298
    // Production-friendly logging
299
    level = LogLevel.INFO
300
    format = LoggingFormat.OkHttp
301
}
302
```