0
# Format Patterns
1

2
Format patterns in tinylog-impl provide a flexible way to define the layout and format of log entries. The pattern system uses tokens to represent different components of log entries, allowing customizable output formatting across all writers.
3

4
## Capabilities
5

6
### Token Interface
7

8
Base interface for all pattern tokens that render parts of log entries.
9

10
```java { .api }
11
/**
12
 * Interface for tokens that render log entry components as text
13
 */
14
interface Token {
15
    /**
16
     * Get the required log entry values for this token
17
     * @return Collection of required LogEntryValue enums
18
     */
19
    Collection<LogEntryValue> getRequiredLogEntryValues();
20
    
21
    /**
22
     * Render the token using log entry data
23
     * @param logEntry Log entry to render
24
     * @param builder StringBuilder to append output to
25
     */
26
    void render(LogEntry logEntry, StringBuilder builder);
27
    
28
    /**
29
     * Apply token value to prepared statement for JDBC writer
30
     * @param logEntry Log entry data
31
     * @param statement JDBC PreparedStatement
32
     * @param index Parameter index in statement
33
     * @throws SQLException if database operation fails
34
     */
35
    void apply(LogEntry logEntry, PreparedStatement statement, int index) throws SQLException;
36
}
37
```
38

39
### Format Pattern Parser
40

41
Parser that converts format pattern strings into collections of tokens for rendering.
42

43
```java { .api }
44
/**
45
 * Parser for format patterns producing collections of tokens
46
 */
47
class FormatPatternParser {
48
    /**
49
     * Create parser with throwable filter support
50
     * @param filters Comma-separated list of throwable filters
51
     */
52
    public FormatPatternParser(String filters);
53
    
54
    /**
55
     * Parse format pattern into tokens
56
     * @param pattern Format pattern string
57
     * @return Collection of tokens representing the pattern
58
     */
59
    public Collection<Token> parse(String pattern);
60
    
61
    /**
62
     * Parse format pattern for JDBC usage
63
     * @param pattern Format pattern string
64
     * @return Collection of tokens for JDBC statements
65
     */
66
    public Collection<Token> parseForJdbc(String pattern);
67
}
68
```
69

70
## Date and Time Tokens
71

72
### Date Token
73

74
Renders timestamps in configurable date/time formats.
75

76
```java { .api }
77
/**
78
 * Token for rendering timestamps with customizable format
79
 */
80
class DateToken implements Token {
81
    /**
82
     * Create date token with specified format
83
     * @param pattern Date format pattern (SimpleDateFormat syntax)
84
     */
85
    public DateToken(String pattern);
86
    
87
    /**
88
     * Create date token with format and timezone
89
     * @param pattern Date format pattern
90
     * @param timeZone Timezone for rendering
91
     */
92
    public DateToken(String pattern, TimeZone timeZone);
93
}
94
```
95

96
**Pattern Examples:**
97
- `{date}` - Default format: `yyyy-MM-dd HH:mm:ss`
98
- `{date:HH:mm:ss}` - Time only: `14:30:25`
99
- `{date:yyyy-MM-dd}` - Date only: `2023-12-25`
100
- `{date:yyyy-MM-dd HH:mm:ss.SSS}` - With milliseconds
101

102
### Uptime Token
103

104
Renders application uptime since startup.
105

106
```java { .api }
107
/**
108
 * Token for rendering application uptime
109
 */
110
class UptimeToken implements Token {
111
    /**
112
     * Create uptime token with default format
113
     */
114
    public UptimeToken();
115
    
116
    /**
117
     * Create uptime token with custom format
118
     * @param pattern Format pattern for uptime display
119
     */
120
    public UptimeToken(String pattern);
121
}
122
```
123

124
## Thread Information Tokens
125

126
### Thread Token
127

128
Renders thread name and ID information.
129

130
```java { .api }
131
/**
132
 * Token for rendering thread information
133
 */
134
class ThreadToken implements Token {
135
    /**
136
     * Create thread token with default format (thread name)
137
     */
138
    public ThreadToken();
139
    
140
    /**
141
     * Create thread token with custom format
142
     * @param pattern Format for thread info (name, id, or both)
143
     */
144
    public ThreadToken(String pattern);
145
}
146
```
147

148
### Process ID Token
149

150
Renders the current process ID.
151

152
```java { .api }
153
/**
154
 * Token for rendering process ID
155
 */
156
class ProcessIdToken implements Token {
157
    /**
158
     * Create process ID token
159
     */
160
    public ProcessIdToken();
161
}
162
```
163

164
## Message and Content Tokens
165

166
### Message Token
167

168
Renders the formatted log message.
169

170
```java { .api }
171
/**
172
 * Token for rendering formatted log messages
173
 */
174
class MessageToken implements Token {
175
    /**
176
     * Create message token
177
     */
178
    public MessageToken();
179
}
180
```
181

182
### Exception Token
183

184
Renders exception information with configurable formatting.
185

186
```java { .api }
187
/**
188
 * Token for rendering exception information
189
 */
190
class ExceptionToken implements Token {
191
    /**
192
     * Create exception token with default formatting
193
     */
194
    public ExceptionToken();
195
    
196
    /**
197
     * Create exception token with throwable filters
198
     * @param filters Comma-separated list of throwable filters
199
     */
200
    public ExceptionToken(String filters);
201
}
202
```
203

204
## Source Code Tokens
205

206
### Class Name Token
207

208
Renders the class name where logging occurred.
209

210
```java { .api }
211
/**
212
 * Token for rendering class names
213
 */
214
class ClassNameToken implements Token {
215
    /**
216
     * Create class name token with default format (full class name)
217
     */
218
    public ClassNameToken();
219
    
220
    /**
221
     * Create class name token with custom format
222
     * @param pattern Format pattern (full, simple, package)
223
     */
224
    public ClassNameToken(String pattern);
225
}
226
```
227

228
### Method Token
229

230
Renders the method name where logging occurred.
231

232
```java { .api }
233
/**
234
 * Token for rendering method names
235
 */
236
class MethodToken implements Token {
237
    /**
238
     * Create method token
239
     */
240
    public MethodToken();
241
}
242
```
243

244
### File Token
245

246
Renders the source file name where logging occurred.
247

248
```java { .api }
249
/**
250
 * Token for rendering source file names
251
 */
252
class FileToken implements Token {
253
    /**
254
     * Create file token
255
     */
256
    public FileToken();
257
}
258
```
259

260
### Line Token
261

262
Renders the line number where logging occurred.
263

264
```java { .api }
265
/**
266
 * Token for rendering source line numbers
267
 */
268
class LineToken implements Token {
269
    /**
270
     * Create line token
271
     */
272
    public LineToken();
273
}
274
```
275

276
## Level and Tag Tokens
277

278
### Level Token
279

280
Renders the log level with configurable formatting.
281

282
```java { .api }
283
/**
284
 * Token for rendering log levels
285
 */
286
class LevelToken implements Token {
287
    /**
288
     * Create level token with default format
289
     */
290
    public LevelToken();
291
    
292
    /**
293
     * Create level token with custom format
294
     * @param pattern Format pattern (full, short, numeric)
295
     */
296
    public LevelToken(String pattern);
297
}
298
```
299

300
### Tag Token
301

302
Renders log tags for categorized logging.
303

304
```java { .api }
305
/**
306
 * Token for rendering log tags
307
 */
308
class TagToken implements Token {
309
    /**
310
     * Create tag token
311
     */
312
    public TagToken();
313
}
314
```
315

316
## Context and Special Tokens
317

318
### Context Token
319

320
Renders thread-local context values.
321

322
```java { .api }
323
/**
324
 * Token for rendering context values
325
 */
326
class ContextToken implements Token {
327
    /**
328
     * Create context token for specific key
329
     * @param key Context key to render
330
     */
331
    public ContextToken(String key);
332
    
333
    /**
334
     * Create context token with key and default value
335
     * @param key Context key to render
336
     * @param defaultValue Default value if key not found
337
     */
338
    public ContextToken(String key, String defaultValue);
339
}
340
```
341

342
### Plain Text Token
343

344
Renders literal text strings within patterns.
345

346
```java { .api }
347
/**
348
 * Token for rendering literal text
349
 */
350
class PlainTextToken implements Token {
351
    /**
352
     * Create plain text token
353
     * @param text Literal text to render
354
     */
355
    public PlainTextToken(String text);
356
}
357
```
358

359
### Newline Token
360

361
Renders platform-appropriate line separators.
362

363
```java { .api }
364
/**
365
 * Token for rendering newlines
366
 */
367
class NewLineToken implements Token {
368
    /**
369
     * Create newline token
370
     */
371
    public NewLineToken();
372
}
373
```
374

375
## Usage Examples
376

377
**Basic Pattern Usage:**
378

379
```properties
380
# Simple console format
381
writer=console
382
writer.format={date: HH:mm:ss} {level}: {message}
383

384
# Detailed file format
385
writer=file
386
writer.file=app.log
387
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} [{level}] [{thread}] {class}.{method}(): {message}
388
```
389

390
**Advanced Pattern Examples:**
391

392
```properties
393
# Development format with full source information
394
writer=console
395
writer.format={date: HH:mm:ss.SSS} {level} [{thread}] {class}.{method}({file}:{line}): {message}{newline}{exception}
396

397
# Production format with minimal information
398
writer=file
399
writer.format={date} {level}: {message}
400

401
# JSON-like structured format
402
writer=file
403
writer.format={"timestamp":"{date:yyyy-MM-dd'T'HH:mm:ss.SSSZ}","level":"{level}","thread":"{thread}","message":"{message}"}
404
```
405

406
**Context Integration:**
407

408
```properties
409
# Include context values in log format
410
writer=console
411
writer.format={date: HH:mm:ss} [{level}] [user:{context:userId}] [session:{context:sessionId}] {message}
412

413
# Context with defaults
414
writer=file
415
writer.format={date} {level} [user:{context:userId:-unknown}] {class}: {message}
416
```
417

418
**Exception Formatting:**
419

420
```properties
421
# Full exception details
422
writer=file
423
writer.format={date} {level}: {message}{newline}{exception}
424
writer.exception=keep
425

426
# Minimal exception info
427
writer=console  
428
writer.format={date: HH:mm:ss} {level}: {message} [{exception}]
429
writer.exception=strip
430
```
431

432
**Multi-line Formats:**
433

434
```properties
435
# Multi-line detailed format
436
writer=file
437
writer.format=== {date: yyyy-MM-dd HH:mm:ss.SSS} ==={newline}Level: {level}{newline}Thread: {thread}{newline}Location: {class}.{method}({file}:{line}){newline}Message: {message}{newline}{exception}{newline}
438

439
# Compact single-line format
440
writer=console
441
writer.format={date: HH:mm:ss} {level} {class}: {message}
442
```
443

444
**Performance-Optimized Patterns:**
445

446
```properties
447
# Minimal pattern for high-volume logging
448
writer=file
449
writer.format={date: HH:mm:ss} {level}: {message}
450

451
# No source code information for better performance
452
writer=console
453
writer.format={date: HH:mm:ss} {level} [{thread}]: {message}
454
```