This is an automated email from the ASF dual-hosted git repository. swebb2066 pushed a commit to branch improve_properties_file_documentation in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit 5cc727a4bf6b9933e39e6388e93a9fcc5e9533b1 Author: Stephen Webb <[email protected]> AuthorDate: Wed Aug 20 12:19:17 2025 +1000 Add a properties file example to configuration documentation --- src/site/markdown/concepts.md | 28 ++++++++++++---- src/site/markdown/configuration-samples.md | 51 ++++++++++++++++++++++++++++-- 2 files changed, 70 insertions(+), 9 deletions(-) diff --git a/src/site/markdown/concepts.md b/src/site/markdown/concepts.md index c4249e61..0e199ecc 100644 --- a/src/site/markdown/concepts.md +++ b/src/site/markdown/concepts.md @@ -474,16 +474,30 @@ See \ref async-example.xml for a configuration file example. ## Additivity {#appender-additivity} -Each enabled logging request for a given logger will be forwarded to all the appenders in -that logger as well as the appenders higher in the hierarchy. -In other words, appenders are inherited additively from the logger hierarchy. +The logger used in each enabled logging request sends a logging event +to the all the appenders attached to it. +The logger also forwards the event to loggers higher in the hierarchy, +and therefore the event is also sent to the appenders attached to those loggers. For example, if a console appender is added to the root logger, then all enabled logging requests will at least print on the console. If in addition a file appender is added to a logger, say *C*, then enabled logging requests for *C* and *C*'s children will print on a file *and* -on the console. It is possible to override this default behavior so that -appender accumulation is no longer additive by -[setting the additivity flag](@ref log4cxx.Logger.setAdditivity) to `false`. +on the console. + +It is possible to override this default behavior +by setting the additivity flag to `false`. +This can be done: +- programmatically using +<pre>Logger::getLogger("MyLogger")->setLevel(Level::getDebug()); +Logger::getLogger("MyLogger")->setAdditivity(false);</pre> +- in [a properties configuration file] using +<pre>log4j.logger.MyLogger=debug +log4j.logger.MyLogger.additivity=false</pre> +- in [an XML configuration file] using +<pre><logger name="MyLogger" > + <priority value="debug"/> + <additivity value="false"/> +</logger></pre> The rules governing appender additivity are summarized below. @@ -620,3 +634,5 @@ This example shows a configuration using the [asynchronous appender](@ref log4cx [Custom_levels]:faq.html#custom_levels [Runtime Configuration]:quick-start.html#configuration +[an XML configuration file]:configuration-samples.html#xmlfiles +[a properties configuration file]:configuration-samples.html#properties diff --git a/src/site/markdown/configuration-samples.md b/src/site/markdown/configuration-samples.md index cdecdae8..dc211fa0 100644 --- a/src/site/markdown/configuration-samples.md +++ b/src/site/markdown/configuration-samples.md @@ -40,12 +40,57 @@ of [LoggerRepository](@ref log4cxx.spi.LoggerRepository). To use automatic configuration with a non-standard file name create and use your own wrapper for [getLogger](@ref log4cxx.LogManager.getLogger). -A full example can be seen in the \ref com/foo/config3.cpp file. +A full example can be seen in the \ref com/foo/config4.cpp file. + +# Properties Files {#properties} + +Log4cxx may be configured using a Java properties (key=value) type file. + +The following is an example of a properties file. +~~~ +# Uncomment a line to enable debugging for a category +log4j.rootCategory=INFO, A1 + +log4j.appender.A1=org.apache.log4j.RollingFileAppender +log4j.appender.A1.MaxFileSize=5MB +log4j.appender.A1.MaxBackupIndex=12 +log4j.appender.A1.File=${TEMP}/URControlTests.log +log4j.appender.A1.Append=true +log4j.appender.A1.layout=org.apache.log4j.PatternLayout +log4j.appender.A1.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5p %.30c - %m%n + +log4j.appender.console=org.apache.log4j.ConsoleAppender +log4j.appender.console.layout=org.apache.log4j.PatternLayout +log4j.appender.console.layout.ConversionPattern=%.30c - %m%n + +log4j.appender.csvData=org.apache.log4j.FileAppender +log4j.appender.csvData.File=${TEMP}/MessageData.csvData +log4j.appender.csvData.Append=false +log4j.appender.csvData.layout=org.apache.log4j.PatternLayout +log4j.appender.csvData.layout.ConversionPattern=%m,%d{yyyy-MM-dd,HH:mm,ss.SSS}%n + +#log4j.logger.csv.URCommunicationPort=DEBUG, csvData +#log4j.logger.csv.URCommunicationPort.additivity=false + +# UnitTests +#log4j.logger.MockArmTests=DEBUG +#log4j.logger.RTDEMessageTests=DEBUG +#log4j.logger.RTDEMessagePortTests=DEBUG +#log4j.logger.URCommunicationPortTests=DEBUG + +# URControl classes +#log4j.logger.Dashboard=DEBUG +#log4j.logger.RTDEMessage=DEBUG +#log4j.logger.RTDEMessagePort=DEBUG +#log4j.logger.MockArm=DEBUG +#log4j.logger.MockURController=DEBUG +#log4j.logger.URCommunicationPort=DEBUG +~~~ # XML Files {#xmlfiles} -One way of configuring Log4cxx is with XML files. The following are some examples -on various ways of using an XML file to configure the logging. +Another way of configuring Log4cxx is with an XML file. +The following are some XML configuration examples. ## XML Example 1 {#xml-example-1}
