2024002 Logging system and logging format

Context

OmegaT previously used a direct implementation of the Java Logging API (JUL). Log file names were static or partially random, and log message entries used a random 5-digit “session ID” (known as $mark) as a prefix by default. This approach had several drawbacks:

  • Many external libraries already used SLF4J, leading to a fragmented logging configuration.

  • Multiple instances of OmegaT running simultaneously could conflict if log filenames were not unique enough. Even with timestamps, if two sessions start at the exact same millisecond, they would attempt to use the same filename, leading to file access errors or interleaved logs.

  • Users and developers (e.g., Jean-Christophe Helary in RFE #1734) found the random session ID in log entries unhelpful for debugging time-sensitive issues, such as race conditions or sequence of events across multiple log files.

  • Debugging parallel execution in CI/CD tests required thread-level information that wasn’t consistently available in the default format.

Proposal

The log filename OmegaT_YYYY-MM-DD_HH-mm_######.log includes random 5-disit number to avoid collision, but it decreases readability and removes information. JUL default FileHander has a placeholder parameter “%u” that increments a number to avoid a filename collision. By using the same logic, we can improve the filename scheme to OmegaT_YYYY-MM-DD_HH-mm_N.log where N is a number incremented from 0 if there are multiple instances of the log file created within a minute.

Current Implementation Details

PR#717 was merged in Sep 2023, and PR#1077 was merged in Jul 2024. OmegaT 6.1.0 supports users to look log messages of the current session only with “Help > Log” menu operation. The filenames are OmegaT_YYYY-MM-DD_HH-mm_######.log.

PR#717 introduced the SLF4J logging system, PR#1077 enhanced the logging system by showing only the current session log when menu item Help > Log is selected, and refined the log filename to OmegaT_YYYY-MM-DD_HH-mm_######.log. It also introduced log retention configuration (default 10 days) and refactored the LogDialog class.

Decision

We have implemented a modernized logging system and format with the following characteristics:

  1. Adopt SLF4J as a Logging Facade: OmegaT now uses SLF4J (specifically via a tokyo.northside.logging bridge to JUL) as the primary logging API. This allows for better dependency management and provides a standard, flexible interface for developers.

  2. Timestamped Log Filenames: Log files are now named using a pattern that includes both a timestamp (yyyy-MM-dd_HH-mm) and an uniqueness count: OmegaT_YYYY-MM-DD_HH-mm_#.log. This ensures that every run of OmegaT produces a unique, easily identifiable log file. The random session ID acts as a “tie-breaker” to prevent filename collisions in the rare event that multiple OmegaT instances are started at the exact same time, which would otherwise result in identical timestamped filenames.

  3. Transition from Session ID to Timestamp in Log Entries: The default log message template has been changed from using a random session ID ($mark) to a high-precision timestamp ($time). The default format is HH:mm:ss.SSS, providing millisecond precision. This allows for precise correlation of events and actions during debugging.

  4. User-Customizable Logging Configuration: OmegaT provides several ways for users to override the default logging settings:

    • Placing a logger.properties file in the user’s configuration directory (e.g., ~/.omegat/).

    • Using the -Djava.util.logging.config.file system property.

  5. Specialized Logging for CI/CD Tests: For CI/CD and automated tests, OmegaT uses a custom configuration (config/test/logger.properties) that includes the thread name ($threadName) in the log mask. This is critical for debugging failures in concurrent test execution environments.

Consequences

  • Improved Debugging: Developers and users can now accurately track the timing of events, which is essential for troubleshooting complex issues.

  • Better Instance Management: Unique log filenames prevent data loss or confusion when multiple instances of the application are running.

  • Configuration Flexibility: Users have full control over the level of detail and formatting of logs through standard property files.

  • Enhanced Test Analysis: Thread information in CI/CD logs simplifies the identification of issues in parallel test runs.

References