Hello Fumin, There is indeed plenty of room for improvement in the Log4j documentation. We will appreciate it if you can contribute these improvements in the form of a PR. Maintainers can review and, if found to be appropriate, merge your changes.
Kind regards. On Mon, Aug 7, 2023 at 8:02 PM Fumin Zhou <fuminz...@crd.com> wrote: > Hi, > > This online doc: Log4j – Configuring Log4j 2 (apache.org)< > https://logging.apache.org/log4j/2.x/manual/configuration.html> describes > “Automatic Configuration”: > > “ > > Log4j has the ability to automatically configure itself during > initialization. When Log4j starts it will locate all the > ConfigurationFactory plugins and arrange them in weighted order from > highest to lowest. As delivered, Log4j contains four ConfigurationFactory > implementations: one for JSON, one for YAML, one for properties, and one > for XML. > 1. Log4j will inspect the "log4j2.configurationFile" system property > and, if set, will attempt to load the configuration using the > ConfigurationFactory that matches the file extension. Note that this is not > restricted to a location on the local file system and may contain a URL. > 2. If no system property is set the properties ConfigurationFactory > will look for log4j2-test.properties in the classpath. > 3. If no such file is found the YAML ConfigurationFactory will look > for log4j2-test.yaml or log4j2-test.yml in the classpath. > 4. If no such file is found the JSON ConfigurationFactory will look > for log4j2-test.json or log4j2-test.jsn in the classpath. > 5. If no such file is found the XML ConfigurationFactory will look for > log4j2-test.xml in the classpath. > 6. If a test file cannot be located the properties > ConfigurationFactory will look for log4j2.properties on the classpath. > 7. If a properties file cannot be located the YAML > ConfigurationFactory will look for log4j2.yaml or log4j2.yml on the > classpath. > 8. If a YAML file cannot be located the JSON ConfigurationFactory will > look for log4j2.json or log4j2.jsn on the classpath. > 9. If a JSON file cannot be located the XML ConfigurationFactory will > try to locate log4j2.xml on the classpath. > 10. If no configuration file could be located the DefaultConfiguration > will be used. This will cause logging output to go to the console. > ” > > This looks like a flow diagram, if one does not match, then move down to > next Decision Tree Node. > So jumping to the end, a user can easily get a feeling that if someone > made a mistake in one of the settings, then probably it would default to > the 10, a default configuration – logging to Console would be happening. > > But is it true? > If at the first Decision Tree Node, there is something set for System > Property “log4j2.configurationFile”, but for whatever reasons, typo on the > file path, incorrect format, or wrong extension, or wrong contents, > Configuration could not succeed – I guess there could be two distinct set > of situations, 1 is we could not get the configuration files; 2 is we could > get to the file, but contents of the file throws up something we do not > expect. – the 2nd set actually would not be different to any of the > subsequent decision tree nodes, - we could find a configuration file, but > we could not handle the contents, - so we will park this to a different > topic. > > Getting back to decision tree node 1, if there is something set to > “log4j2.configurationFile”, but following the value we could not locate a > file, then what happens? > Does it still move onto the next Decision Tree Node listed above? Or jump > to the Decision Tree Node 10 directly? > In “description” point of view, (some situations) could be said to be > similar to the subsequent decision node – no such file specified in > “log4j2.configurationFile” could be found, thus maybe it should move down > the next decision tree node. > > From a different angle, it could be said to be an Exceptional case within > the particular decision branch of the 1st Decision Tree Node, none of the > other Decision Tree Nodes apply anymore. > > So do we agree there is a bit ambiguity here? Would you be able to > determine what would be the behavior without reading into the source code? > > Should we refine this document section a bit to describe more clearly what > would be the behavior? > > > Fumin > > Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows > > > The information in this e-mail communication together with any attachments > is intended only for the person or entity to which it is addressed and may > contain confidential and/or privileged material. If you are not the > intended recipient of this e-mail communication, please notify us > immediately. Any views expressed in this e-mail communication are those of > the individual sender, unless otherwise specifically stated. Charles River > Development does not represent, warrant or guarantee that the integrity of > this communication has been maintained or that the communication is free of > errors, virus or interference. >
