Add Documentation on how to mitigate potential date filter parsing issues when migrating to a logstash using JDK 21

[robbavey]

Between JDK17 and JDK21, a change was made in the internal CLDR locale provider which changed the abbreviation of September from Sep. to Sept. in certain locales, en_GB and en_AU amongst them.

This has the side effect of causing various breakages, typically because the MMM date format may actually be 4 characters instead of 3 - reported in the CLDR project itself, and in the JDK.

This issue will arise when there is a locale mismatch between the systems sending dates to Logstash and Logstash itself.

If the systems running Logstash are running with either an en_AU or en_GB locale, they will expect dates including September to use the Sept abbreviated form, even when the format states MMM. If the systems generating these dates are creating dates with a Sep abbreviation, the parsing will fail.

There are a few mitigations for this issue:

• Ensure that the date formats from the source and Logstash are using the same abbreviated form.
• Change the locale in the date filter to a locale that still uses Sep as an abbreviation for September, such as en_US.
• Switch out the locale provider from CLDR to compat by setting -Djava.locale.providers=COMPAT,SPI in jvm.options.
  • Note that this will fail for anyone using JDK23 and above, which drops support for the compat locale provider
• Before using the date filter, add Logstash filters to replace uses of Sept with Sep.

This information should be added to the date filter, and the Logstash troubleshooting guide.