[LOG4J2-1126] Site fixes/improvements for 2.4 release

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 2.4
• Fix Version/s: 2.4.1
• Component/s: Documentation
• Assignee: Unassigned
• Reporter: Remko Popma
• Created: 21/Sep/15 20:19
• Updated: 23/Sep/15 21:08
• Resolved: 23/Sep/15 21:05

Description

changelog.html (outdated)
-Configuration via property files is not supported.
+Configuration via property files is supported from version 2.4, but is not compatible with Log4j 1.x.

changes.xml (improvement)
-LOG4J2-952: Add ConfigurationBuilder.
+LOG4J2-952: Add ConfigurationBuilder for programmatic configuration.

faq.html (outdated, duplicate)

• Under "How do I configure log4j2 in code without a configuration file?"
  -You could use the static method #initialize(String contextName, ClassLoader loader, String configLocation) (see source code) in org.apache.logging.log4j.core.config.Configurator. (You can pass null for the class loader.) Be aware that this class is not part of the public API so your code may break with any minor release.
  +From 2.4, Log4j 2 provides an [API for programmatic configuration|manual/customconfig.html]. The new ConfigurationBuilder API allows you to create Configurations in code by constructing component definitions without requiring you to know about the internals of actual configuration objects like Loggers and Appenders.

• Merge these answers into a single Q&A entry:
  "How do I change a logger's level in code?" and
  "How do I set a logger's level programmatically?"

• Version
  -the log4j-api-2.1 and the log4j-core-2.1 jar files
  +the log4j-api-2.4 and the log4j-core-2.4 jar files

manual/appenders.html (site errors and ambiguities)
Kafka Appender

• Kafka Appender is missing from the left nav-bar in Appenders

-The KafkaAppender log events
+The KafkaAppender logs events

-lilter (Parameter Name)
+filter

-If you do not specify a layout, if not specified the formatted message as an UTF-8 encoded string will be sent to Kafka.
+If you do not specify a layout, the formatted message will be sent to Kafka as an UTF-8 encoded string.
I used the active voice (GG):
+If you do not specify a layout, the appender will send the formatted message to Kafka as a UTF-8 encoded string.

-This appender requires Kafka client library
+This appender requires Kafka client library. (add period at end)

ZeroMQ appender

• Section title and left nav-bar title should be "JeroMQ". Tweaked as "ZeroMQ/JeroMQ" because some folk may not know that the ZeroMQ Java client is "JeroMQ".
• Is a layout required? What layout is used if nothing is specified?

-The name of the Appender.
+The name of the Appender. Required.

(Parameter Name)
-Layout
+layout (lower case)

-Filters
+filters (lower case); other appenders use singular "filter" without trailing 's', but the code for JeroMQ says @PluginElement("Filters") Filter filter
Using upper case because this is an Element, not an Attribute. Normalized to singular, instead plural.

-Property, Type=Property
+properties (lower case, plural), Type=Property[] - this is consistent with docs for PropertiesRewritePolicy in RewriteAppender
ggregory: As above, leaving as upper case because this is an Element, not an Attribute. Since configurations are cases insensitive, this could be a moot point.
[e-mail]: Understood. I did fix name to plural and type to Property[]

manual/layouts.html (CsvLogEventLayout bug, site errors)

• CSV Layout is missing from the left nav-bar in Layouts
• CSV Layout section should mention dependency on Apache Commons CSV. (See JSONLayout on same page.)
• Bug: CsvLogEventLayout generates NanoTime timestamps but these are always zero.
  To fix this, add the below code to the CsvLogEventLayout constructor:

        // LOG4J2-1074 Switch to actual clock if nanosecond timestamps are required in config.
        // LoggerContext will notify known NanoClockFactory users that the configuration has changed.
        NanoClockFactory.setMode(NanoClockFactory.Mode.System);
  

• GELF Layout should be before HTML Layout in body text and in left nav-bar (alphabetical order)
• HTML Layout should be before JSON Layout in body text (alphabetical order - the nav-bar order is correct)
• (Under Location Information)
  -%C or $class - this is rendered as "%C or class java.lang.Object"
  +%C or %class

manual/customconfig.html (improvements)

• Side-nav menu title "Extending Log4j Configuration" should be "Programmatic Log4j Configuration"
• Title "Custom Configurations" -> "Programmatic Configuration"

log4j-api/dependency-convergence.html
Error: You do not have 100 % convergence. - is this a showstopper?

log4j-api/clirr-report.html
77 Clirr errors - I believe these are all expected and can be ignored.

log4j-api/checkstyle.html
122 checkstyle errors - not showstoppers

log4j-core/index.html

• Missing dependency information for JeroMQ/ZeroMQ Appender on JeroMQ library
• Missing dependency information for CSV layouts on Apache Commons CSV

log4j-core/dependency-convergence.html
Error: You do not have 100 % convergence. - Is this a showstopper?

log4j-core/checkstyle.html
1652 checkstyle errors - not showstoppers

log4j-liquibase/index.html
-due the the plugin auto discovery
+due to the plugin auto discovery

log4j-liquibase/dependency-convergence.html
Error: You do not have 100 % convergence. - Is this a showstopper?

Issue Links

• is related to: LOG4J2-1130 CsvLogEventLayout NanoTime timestamp is always zero.