tessl/maven-org-tinylog--tinylog-impl

tinylog native logging implementation providing writers, policies, converters, and core logging functionality

Overview

Eval results

Files

File Converters

Name: tessl/maven-org-tinylog--tinylog-impl
Author: tessl

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.

Capabilities

File Converter Interface

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

/**
 * Interface for converters that transform log files
 */
interface FileConverter {
    /**
     * Get the backup suffix that will be appended to converted files
     * @return File suffix (e.g., ".gz" for GZIP compression)
     */
    String getBackupSuffix();
    
    /**
     * Open/initialize the converter for a specific file
     * @param fileName Path to the file that will be converted
     */
    void open(String fileName);
    
    /**
     * Convert/transform the provided data
     * @param data Original file data to convert
     * @return Converted data
     */
    byte[] write(byte[] data);
    
    /**
     * Close the converter and finalize the conversion
     */
    void close();
    
    /**
     * Shutdown the converter and clean up resources
     * @throws InterruptedException if shutdown is interrupted
     */
    void shutdown() throws InterruptedException;
}

No-Operation Converter

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

/**
 * Converter that performs no transformation, keeping original data and files
 */
class NopFileConverter implements FileConverter {
    /**
     * Default constructor for no-operation conversion
     */
    public NopFileConverter();
    
    /**
     * Returns null as no suffix is added
     * @return null
     */
    public String getBackupSuffix();
    
    /**
     * No-op implementation
     * @param fileName Ignored
     */
    public void open(String fileName);
    
    /**
     * Returns data unchanged
     * @param data Original data
     * @return Same data unchanged
     */
    public byte[] write(byte[] data);
    
    /**
     * No-op implementation
     */
    public void close();
    
    /**
     * No-op implementation
     */
    public void shutdown() throws InterruptedException;
}

Configuration Examples:

# Explicitly use no-operation converter (default behavior)
writer=rolling file
writer.file=application.log
writer.policies=daily
writer.converter=nop

GZIP Converter

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

/**
 * Converter that compresses log files using GZIP compression asynchronously
 */
class GzipFileConverter implements FileConverter {
    /**
     * Default constructor for GZIP compression
     */
    public GzipFileConverter();
    
    /**
     * Returns ".gz" as backup suffix for compressed files
     * @return ".gz" suffix
     */
    public String getBackupSuffix();
    
    /**
     * Initialize GZIP compression for the specified file
     * @param fileName Path to file being compressed
     */
    public void open(String fileName);
    
    /**
     * Compress data using GZIP algorithm
     * @param data Original uncompressed data
     * @return GZIP compressed data
     */
    public byte[] write(byte[] data);
    
    /**
     * Finalize GZIP compression and close streams
     */
    public void close();
    
    /**
     * Shutdown compression threads and clean up resources
     * @throws InterruptedException if shutdown is interrupted
     */
    public void shutdown() throws InterruptedException;
}

Configuration Examples:

# Basic GZIP compression for rolled files
writer=rolling file
writer.file=application.log
writer.policies=daily
writer.converter=gzip

# Size-based rolling with compression
writer=rolling file
writer.file=large-app.log
writer.policies=size:100MB
writer.converter=gzip

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

Converter Integration

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

Rollover Process with Converters

Normal Logging: Log entries written to current file
Rollover Trigger: Policy condition met (size, time, etc.)
File Rotation: Current file closed and renamed
Converter Processing: Converter transforms the completed file
Cleanup: Original file removed, converted file remains

File Naming with Converters

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

Without converter: application.log → application.log.1
With GZIP converter: application.log → application.log.1.gz
With daily policy: application.log → application.2023-12-25.log.gz

Usage Examples

Daily Rollover with Compression:

writer=rolling file
writer.file=daily-app.log
writer.policies=daily
writer.converter=gzip
writer.format={date: yyyy-MM-dd HH:mm:ss} {level}: {message}

This configuration creates:

daily-app.log (current file)
daily-app.2023-12-25.log.gz (previous day, compressed)
daily-app.2023-12-24.log.gz (day before, compressed)

Size-Based Rollover with Compression:

writer=rolling file
writer.file=/var/log/application.log
writer.policies=size:50MB
writer.converter=gzip
writer.charset=UTF-8
writer.buffered=true

This configuration creates:

/var/log/application.log (current file, up to 50MB)
/var/log/application.log.1.gz (previous file, compressed)
/var/log/application.log.2.gz (older file, compressed)

Complex Rollover Strategy:

writer=rolling file
writer.file=enterprise-app.log
writer.policies=startup,daily:UTC,size:200MB
writer.converter=gzip
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} {level} [{thread}] {class}: {message}
writer.exception=keep

High-Volume Logging with Compression:

# Main application log with frequent rollover
writer=rolling file
writer.file=high-volume.log
writer.policies=size:25MB
writer.converter=gzip
writer.buffered=true
writer.writingthread=true

# Error log with different rollover strategy
writer2=rolling file
writer2.file=errors.log
writer2.level=ERROR
writer2.policies=daily,size:10MB
writer2.converter=gzip
writer2.format={date} ERROR: {class}.{method}(): {message}{newline}{exception}

Environment-Specific Configuration:

# Development - no compression for easy reading
writer=rolling file
writer.file=dev-app.log
writer.policies=startup,size:10MB
# No converter specified = no compression

# Production - compression for space efficiency
writer=rolling file
writer.file=/var/log/prod-app.log
writer.policies=daily,size:100MB
writer.converter=gzip

Multiple Writers with Different Conversion:

# Console writer - no files, no conversion
writer=console
writer.format={date: HH:mm:ss} {level}: {message}

# Debug file - frequent rollover, compressed
writer2=rolling file
writer2.file=debug.log
writer2.level=DEBUG
writer2.policies=size:20MB
writer2.converter=gzip

# Audit file - daily rollover, no compression for compliance
writer3=rolling file
writer3.file=audit.log
writer3.tag=audit
writer3.policies=daily
# No converter = no compression for audit requirements
writer3.format={date: yyyy-MM-dd HH:mm:ss.SSS} AUDIT: {message}

Performance Considerations

GZIP Converter Performance

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

Best Practices

High-Volume Applications:

writer=rolling file
writer.file=high-volume.log
writer.policies=size:100MB  # Larger files = better compression ratio
writer.converter=gzip
writer.buffered=true       # Reduce I/O overhead
writer.writingthread=true  # Asynchronous processing

Low-Disk-Space Environments:

writer=rolling file
writer.file=space-constrained.log
writer.policies=size:50MB  # More frequent rollover
writer.converter=gzip      # Aggressive compression

Audit/Compliance Scenarios:

writer=rolling file
writer.file=compliance.log
writer.policies=daily      # Regular archival
# No converter to maintain original format for compliance

Custom Converter Implementation

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

// Example custom converter interface
public class CustomFileConverter implements FileConverter {
    public String getBackupSuffix() {
        return ".custom";
    }
    
    public void open(String fileName) {
        // Initialize custom processing
    }
    
    public byte[] write(byte[] data) {
        // Apply custom transformation
        return transformedData;
    }
    
    public void close() {
        // Finalize custom processing
    }
    
    public void shutdown() throws InterruptedException {
        // Cleanup custom resources
    }
}

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

Install with Tessl CLI

npx tessl i tessl/maven-org-tinylog--tinylog-impl

docs

converters.md

core.md

exception-handling.md