[MS25 & MS26] Unified date & time formatting

[vy]

In #3121, date & time formatting of both Pattern Layout and JSON Template Layout has been rewritten to be served from a unified utility using Java's DateTimeFormatter under the hood with some caching for extra efficiency.

Historical account

MS25, MS26, MS27 had the following sequence of goals:

• [MS25] Move the InstantFormatter (used for formatting log event instants) of log4j-layout-template-json to log4j-core
• [MS26] Use the InstantFormatter moved to log4j-core in both JSON Template Layout and Pattern Layout
• [MS27] Use the InstantFormatter moved to log4j-core in other places where date & time formatting is needed

We encountered several blockers while executing this plan. Some highlights from the thinking process that led us to the current plan are shared below – see this dev@ discussion for details.

• Log4j contains two custom date & time formatting utilities for performance reasons: FixedDateFormat and FastDateFormat.
• InstantFormatter leverages these two for date & time formatters for patterns they support, otherwise it falls back to DateTimeFormatter.
• Once InstantFormatter is moved to log4j-core and wired to Pattern Layout, several tests started failing, because previously employed FixedDateFormat is
  • incorrectly handling n and x directives
  • incorrectly calculating DST (FixedDateFormat incorrectly calculates DST for America/Santiago time zone #2943)
• FastDateFormat was copied from Commons Lang in 2015
• No other logging frameworks (Logback, Tinylog, etc.) had similar date & time formatting optimizations

In short, FixedDateFormat and FastDateFormat are liabilities (containing incorrect behaviour and bugs!) that once made sense for performance reasons. Though as shown with performance figures in #3121, the efficiency offered by this liability burden is negligible in the big picture of an end-to-end logging scenario. Eventually, we decided to

• Use Java's DateTimeFormatter for date & time formatting
• Introduce caching for extra efficiency (e.g., if user needs to format log events in 2024-10-29T14:49:53.997Z form, we only need to generate 53.997 each time and the rest can be precomputed per minute, cached, and reused)
• Deprecate all legacy classes, i.e., FixedDateFormat and FastDateFormat et al.
• Thoroughly test the new instant formatters to avoid issues like FixedDateFormat incorrectly calculates DST for America/Santiago time zone #2943

Log4j 3

#3150 ports #3121 from 2.x to main, the Log4j 3 branch.