Identifiers, names, refs, nightmare docs, logging hell level 999 about logging-log4j2

[rgoers]

The Log4j configuration is a tree structure organized as "Nodes" where a Node is nothing but a container of attributes and child Nodes. All the configuration dialects Log4j supports are converted into a Node tree. This works great for Yaml, JSON, and XML. Unfortunately, by their nature properties are not hierarchical. This means using properties is somewhat fitting a round peg in a square hole. For years Log4j didn't support properties due to this but we finally added it due to user's requests. We have made slight "improvements" over time at user's requests but in the end I really don't think it makes it any simpler.

As an example of how Log4j configuration works, a more complete form of your example above

appender.console.name = STDOUT
appender.console.type = Console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %m%n

appender.file.name = File
appender.file.type = File
appender.file.fileName = ${filename}
appender.file.bufferedIO = false
appender.file.layout.type = PatternLayout
appender.file.layout.pattern = %d %p %C{1.} [%t] %m%n

would correspond to:

XML

    <Console name="STDOUT">
      <PatternLayout pattern="%m%n"/>
    </Console>
    <File name="File" fileName="${filename}" bufferedIO="false">
      <PatternLayout>
        <Pattern>%d %p %C{1.} [%t] %m%n</Pattern>
      </PatternLayout>
    </File>  

JSON

        "appenders" : {
            "Console" : {
                "name" : "STDOUT",
                "PatternLayout" : {
                    "Pattern": "%m%n"
                }
            },
            "File" : {
                "name": "File",
                "fileName": "${filename}",
                "bufferedIO": false,
                "PatternLayout" : {
                    "Pattern": "%d %p %C{1.} [%t] %m%n"
                }
            }
          }

YAML

  appenders:
    Console:
      name: STDOUT
      PatternLayout:
        Pattern: "%m%n"
    File:
      name: File
      fileName: ${filename}
      bufferedIO: false
      PatternLayout:
        Pattern: "%d %p %C{1.} [%t] %m%n"

In the properties format the first identifier lets Log4j know that this is a child Appender under the Appenders node. The "console" and "file" are tokens that indicate all the properties with that token are grouped together. Finally, the final tokens represent the attributes of the appender with the exception of the "type", which indicates that it is a "Console" appender. Note that the Console appender also has a second token used for grouping; "layout". The type indicates it is a PattermLayout and the pattern is the attribute for that.

I should note that the way Log4j 1 handled configuration was completely different. Properties were the original and only format. XML was bolted on after the fact and was basically a different configuration system from using properties. In addition, Log4j 1.x didn't support the "type". It required every component have a class attribute with the fully qualified class name instead. So where you see a type in the properties configuration you would have replaced with a class token. Although in many examples the "type" and the "name" might have the same value the name used is entirely up to the user. So if your configuration has multiple File Appenders both would have a type of "File" but each would have a unique name.

I, for one, highly encourage users to use a different one of the other formats.

I should also add that anyone can write a new configuration factory. You can even replace the PropertiesConfigurationFactory with one of your own if you desire.

[ppkarwasz]

@robozb,

The identifiers in the properties format are almost useless. One of the last attempts to make the properties format more digestible (#733 and related issues) proposed to use them as default appender names, but the feature never made it out to the main code.

Such a usage would be in line with what Log4j 1.x did, but is not coherent with other formats: most formats use the identifiers/keys/element names to indicate the plugin type. You can see it in Ralph's YAML example:

 appenders:
   Console:
     name: STDOUT
     PatternLayout:
       Pattern: "%m%n"
    File:
      name: FILE
      fileName: ${filename}
      bufferedIO: false
      PatternLayout:
        Pattern: "%d %p %C{1.} [%t] %m%n"

The keys Console, File and PatternLayout associated to YAML objects are used as default values for the missing type properties.

We could probably implement something similar in the properties format:

appender.Console.name = STDOUT
appender.Console.PatternLayout.pattern = "%m%n"

appender.File.name = FILE
appender.File.fileName = ${filename}
appender.File.bufferedIO = false
appender.File.PatternLayout.pattern = %d %p %C{1.} [%t] %m%n

However there isn't much to be done if multiple appenders of the same type are required. In the YAML format we currently support the following shorthand:

Appenders:
  File:
    - name: FILE1
      fileName: file1.log
    - name: FILE2
      fileName: file2.log

(i.e. for YAML arrays the default type is the key associated to the array). I don't think anything similar would be possible for the properties format.

[robozb]

Dear @rgoers,

Thank you very much for your quick answer! You are really kind!

Best Regards: Bela

[robozb]

Dear @ppkarwasz,

Thank you for the details!

Regards: Bela