0
# File Converters
1

2
File converters in tinylog-impl provide transformation capabilities for completed log files, typically used with RollingFileWriter to compress or process archived log files. Converters operate asynchronously to minimize impact on logging performance.
3

4
## Capabilities
5

6
### File Converter Interface
7

8
Base interface for all file converters that transform completed log files.
9

10
```java { .api }
11
/**
12
 * Interface for converters that transform log files
13
 */
14
interface FileConverter {
15
    /**
16
     * Get the backup suffix that will be appended to converted files
17
     * @return File suffix (e.g., ".gz" for GZIP compression)
18
     */
19
    String getBackupSuffix();
20
    
21
    /**
22
     * Open/initialize the converter for a specific file
23
     * @param fileName Path to the file that will be converted
24
     */
25
    void open(String fileName);
26
    
27
    /**
28
     * Convert/transform the provided data
29
     * @param data Original file data to convert
30
     * @return Converted data
31
     */
32
    byte[] write(byte[] data);
33
    
34
    /**
35
     * Close the converter and finalize the conversion
36
     */
37
    void close();
38
    
39
    /**
40
     * Shutdown the converter and clean up resources
41
     * @throws InterruptedException if shutdown is interrupted
42
     */
43
    void shutdown() throws InterruptedException;
44
}
45
```
46

47
### No-Operation Converter
48

49
A pass-through converter that preserves original files without any transformation.
50

51
```java { .api }
52
/**
53
 * Converter that performs no transformation, keeping original data and files
54
 */
55
class NopFileConverter implements FileConverter {
56
    /**
57
     * Default constructor for no-operation conversion
58
     */
59
    public NopFileConverter();
60
    
61
    /**
62
     * Returns null as no suffix is added
63
     * @return null
64
     */
65
    public String getBackupSuffix();
66
    
67
    /**
68
     * No-op implementation
69
     * @param fileName Ignored
70
     */
71
    public void open(String fileName);
72
    
73
    /**
74
     * Returns data unchanged
75
     * @param data Original data
76
     * @return Same data unchanged
77
     */
78
    public byte[] write(byte[] data);
79
    
80
    /**
81
     * No-op implementation
82
     */
83
    public void close();
84
    
85
    /**
86
     * No-op implementation
87
     */
88
    public void shutdown() throws InterruptedException;
89
}
90
```
91

92
**Configuration Examples:**
93

94
```properties
95
# Explicitly use no-operation converter (default behavior)
96
writer=rolling file
97
writer.file=application.log
98
writer.policies=daily
99
writer.converter=nop
100
```
101

102
### GZIP Converter
103

104
Compresses completed log files using GZIP compression to save disk space.
105

106
```java { .api }
107
/**
108
 * Converter that compresses log files using GZIP compression asynchronously
109
 */
110
class GzipFileConverter implements FileConverter {
111
    /**
112
     * Default constructor for GZIP compression
113
     */
114
    public GzipFileConverter();
115
    
116
    /**
117
     * Returns ".gz" as backup suffix for compressed files
118
     * @return ".gz" suffix
119
     */
120
    public String getBackupSuffix();
121
    
122
    /**
123
     * Initialize GZIP compression for the specified file
124
     * @param fileName Path to file being compressed
125
     */
126
    public void open(String fileName);
127
    
128
    /**
129
     * Compress data using GZIP algorithm
130
     * @param data Original uncompressed data
131
     * @return GZIP compressed data
132
     */
133
    public byte[] write(byte[] data);
134
    
135
    /**
136
     * Finalize GZIP compression and close streams
137
     */
138
    public void close();
139
    
140
    /**
141
     * Shutdown compression threads and clean up resources
142
     * @throws InterruptedException if shutdown is interrupted
143
     */
144
    public void shutdown() throws InterruptedException;
145
}
146
```
147

148
**Configuration Examples:**
149

150
```properties
151
# Basic GZIP compression for rolled files
152
writer=rolling file
153
writer.file=application.log
154
writer.policies=daily
155
writer.converter=gzip
156

157
# Size-based rolling with compression
158
writer=rolling file
159
writer.file=large-app.log
160
writer.policies=size:100MB
161
writer.converter=gzip
162

163
# Multiple policies with compression
164
writer=rolling file
165
writer.file=/var/log/myapp.log
166
writer.policies=daily,size:500MB
167
writer.converter=gzip
168
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} [{level}] {message}
169
```
170

171
## Converter Integration
172

173
File converters work exclusively with RollingFileWriter and are applied after file rollover occurs.
174

175
### Rollover Process with Converters
176

177
1. **Normal Logging**: Log entries written to current file
178
2. **Rollover Trigger**: Policy condition met (size, time, etc.)
179
3. **File Rotation**: Current file closed and renamed
180
4. **Converter Processing**: Converter transforms the completed file
181
5. **Cleanup**: Original file removed, converted file remains
182

183
### File Naming with Converters
184

185
When converters are used, the backup suffix is automatically appended:
186

187
- **Without converter**: `application.log` → `application.log.1`
188
- **With GZIP converter**: `application.log` → `application.log.1.gz`
189
- **With daily policy**: `application.log` → `application.2023-12-25.log.gz`
190

191
## Usage Examples
192

193
**Daily Rollover with Compression:**
194

195
```properties
196
writer=rolling file
197
writer.file=daily-app.log
198
writer.policies=daily
199
writer.converter=gzip
200
writer.format={date: yyyy-MM-dd HH:mm:ss} {level}: {message}
201
```
202

203
This configuration creates:
204
- `daily-app.log` (current file)
205
- `daily-app.2023-12-25.log.gz` (previous day, compressed)
206
- `daily-app.2023-12-24.log.gz` (day before, compressed)
207

208
**Size-Based Rollover with Compression:**
209

210
```properties
211
writer=rolling file
212
writer.file=/var/log/application.log
213
writer.policies=size:50MB
214
writer.converter=gzip
215
writer.charset=UTF-8
216
writer.buffered=true
217
```
218

219
This configuration creates:
220
- `/var/log/application.log` (current file, up to 50MB)
221
- `/var/log/application.log.1.gz` (previous file, compressed)
222
- `/var/log/application.log.2.gz` (older file, compressed)
223

224
**Complex Rollover Strategy:**
225

226
```properties
227
writer=rolling file
228
writer.file=enterprise-app.log
229
writer.policies=startup,daily:UTC,size:200MB
230
writer.converter=gzip
231
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} {level} [{thread}] {class}: {message}
232
writer.exception=keep
233
```
234

235
**High-Volume Logging with Compression:**
236

237
```properties
238
# Main application log with frequent rollover
239
writer=rolling file
240
writer.file=high-volume.log
241
writer.policies=size:25MB
242
writer.converter=gzip
243
writer.buffered=true
244
writer.writingthread=true
245

246
# Error log with different rollover strategy
247
writer2=rolling file
248
writer2.file=errors.log
249
writer2.level=ERROR
250
writer2.policies=daily,size:10MB
251
writer2.converter=gzip
252
writer2.format={date} ERROR: {class}.{method}(): {message}{newline}{exception}
253
```
254

255
**Environment-Specific Configuration:**
256

257
```properties
258
# Development - no compression for easy reading
259
writer=rolling file
260
writer.file=dev-app.log
261
writer.policies=startup,size:10MB
262
# No converter specified = no compression
263

264
# Production - compression for space efficiency
265
writer=rolling file
266
writer.file=/var/log/prod-app.log
267
writer.policies=daily,size:100MB
268
writer.converter=gzip
269
```
270

271
**Multiple Writers with Different Conversion:**
272

273
```properties
274
# Console writer - no files, no conversion
275
writer=console
276
writer.format={date: HH:mm:ss} {level}: {message}
277

278
# Debug file - frequent rollover, compressed
279
writer2=rolling file
280
writer2.file=debug.log
281
writer2.level=DEBUG
282
writer2.policies=size:20MB
283
writer2.converter=gzip
284

285
# Audit file - daily rollover, no compression for compliance
286
writer3=rolling file
287
writer3.file=audit.log
288
writer3.tag=audit
289
writer3.policies=daily
290
# No converter = no compression for audit requirements
291
writer3.format={date: yyyy-MM-dd HH:mm:ss.SSS} AUDIT: {message}
292
```
293

294
## Performance Considerations
295

296
### GZIP Converter Performance
297

298
- **Compression Ratio**: Typically 70-90% size reduction for text logs
299
- **CPU Impact**: Minimal due to asynchronous processing
300
- **Memory Usage**: Small buffer for compression streams
301
- **I/O Impact**: Reduced disk usage, slightly increased processing time
302

303
### Best Practices
304

305
**High-Volume Applications:**
306
```properties
307
writer=rolling file
308
writer.file=high-volume.log
309
writer.policies=size:100MB  # Larger files = better compression ratio
310
writer.converter=gzip
311
writer.buffered=true       # Reduce I/O overhead
312
writer.writingthread=true  # Asynchronous processing
313
```
314

315
**Low-Disk-Space Environments:**
316
```properties
317
writer=rolling file
318
writer.file=space-constrained.log
319
writer.policies=size:50MB  # More frequent rollover
320
writer.converter=gzip      # Aggressive compression
321
```
322

323
**Audit/Compliance Scenarios:**
324
```properties
325
writer=rolling file
326
writer.file=compliance.log
327
writer.policies=daily      # Regular archival
328
# No converter to maintain original format for compliance
329
```
330

331
## Custom Converter Implementation
332

333
While tinylog-impl provides built-in converters, custom converters can be implemented:
334

335
```java
336
// Example custom converter interface
337
public class CustomFileConverter implements FileConverter {
338
    public String getBackupSuffix() {
339
        return ".custom";
340
    }
341
    
342
    public void open(String fileName) {
343
        // Initialize custom processing
344
    }
345
    
346
    public byte[] write(byte[] data) {
347
        // Apply custom transformation
348
        return transformedData;
349
    }
350
    
351
    public void close() {
352
        // Finalize custom processing
353
    }
354
    
355
    public void shutdown() throws InterruptedException {
356
        // Cleanup custom resources
357
    }
358
}
359
```
360

361
Register custom converters through the service provider mechanism in `META-INF/services/org.tinylog.converters.FileConverter`.