This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 01d417ee Add a properties file example to configuration documentation
(#524)
01d417ee is described below
commit 01d417ee658fd9ec72278640288821d1ff39aa4f
Author: Stephen Webb <[email protected]>
AuthorDate: Fri Aug 22 11:10:43 2025 +1000
Add a properties file example to configuration documentation (#524)
* Use the new Log4cxx 1.6 features in samples
* Add configuration variable documentation
* Improve auto-configured example description
* Link from 'Quick Start' to 'Configuration Samples'
* Prevent an uncaught 'missing brace' exception when using
DefaultConfigurator
* Suggest 'Internal Debugging' when using runtime values in a configuration
file
* Use color in console output and milliseconds in file output in
configuration examples
---------
Co-authored-by: Stephen Webb <[email protected]>
---
src/examples/cpp/com/foo/config4.cpp | 3 +
src/main/cpp/defaultconfigurator.cpp | 10 +-
src/site/markdown/concepts.md | 28 ++++--
src/site/markdown/configuration-samples.md | 148 +++++++++++++++++++++++++----
src/site/markdown/example-programs.md | 6 +-
src/site/markdown/internal-debugging.md | 18 ++--
6 files changed, 182 insertions(+), 31 deletions(-)
diff --git a/src/examples/cpp/com/foo/config4.cpp
b/src/examples/cpp/com/foo/config4.cpp
index 5aea98ec..28bd4181 100644
--- a/src/examples/cpp/com/foo/config4.cpp
+++ b/src/examples/cpp/com/foo/config4.cpp
@@ -38,6 +38,9 @@ auto getLogger(const std::string& name) -> LoggerPtr {
// Allow expansion of ${CURRENT_VENDOR_FOLDER} and
${CURRENT_PRODUCT_FOLDER}
// when loading a configuration from a file
auto& props = spi::Configurator::properties();
+#ifndef WIN32
+ props.setProperty(LOG4CXX_STR("LocalAppData"),
LOG4CXX_STR("/var/local"));
+#endif
props.setProperty(LOG4CXX_STR("CURRENT_VENDOR_FOLDER"),
lsVendorFolder);
props.setProperty(LOG4CXX_STR("CURRENT_PRODUCT_FOLDER"), lsProductFolder);
diff --git a/src/main/cpp/defaultconfigurator.cpp
b/src/main/cpp/defaultconfigurator.cpp
index b0888fd2..fe19df32 100644
--- a/src/main/cpp/defaultconfigurator.cpp
+++ b/src/main/cpp/defaultconfigurator.cpp
@@ -161,7 +161,15 @@ const LogString
DefaultConfigurator::getConfigurationFileName()
if (isEnvVar)
return configurationFileName;
#endif
- return OptionConverter::substVars(configurationFileName, props);
+ try
+ {
+ return OptionConverter::substVars(configurationFileName, props);
+ }
+ catch (IllegalArgumentException& e)
+ {
+ LogLog::warn(LOG4CXX_STR("Could not perform variable
substitution."), e);
+ return configurationFileName;
+ }
}
diff --git a/src/site/markdown/concepts.md b/src/site/markdown/concepts.md
index c4249e61..6533788c 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..ee1446fd 100644
--- a/src/site/markdown/configuration-samples.md
+++ b/src/site/markdown/configuration-samples.md
@@ -40,19 +40,118 @@ 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.
+
+# Runtime Property Values {#runtime-property-values}
+
+The value of an enviroment variable can be used in a property value.
+Instances of the form <b>${VarName}</b> will be replaced
+with the value of the environment variable <b>VarName</b>.
+A warning message is output to stderr if the closing brace is absent.
+
+As of version 1.6, Log4cxx allows you to define configuration variables
programmatically.
+Extra key value pairs may be added prior to loading a configuration file using
code such as:
+~~~{.cpp}
+auto& props = log4cxx::spi::Configurator::properties();
+props.setProperty(LOG4CXX_STR("VarName"), LOG4CXX_STR("my-varname-value"));
+~~~
+
+Also available in Log4cxx 1.6 are variables that hold the currently executing
program file path
+and the
[std::filesystem::path](https://en.cppreference.com/w/cpp/filesystem/path.html)
+decomposition of the currently executing program file path.
+These allow you to specify a log file location
+relative to the executable location,
+not just the current working directory.
+The variable names are [documented here](@ref
log4cxx.spi.Configurator.properties).
+
+To check the corrent values are used when your configuration file is loaded,
+use [Log4cxx internal debugging].
+
+# Properties Files {#properties}
+
+Log4cxx may be configured using a Java properties (key=value) type file.
+
+## Properties Example 1 {#properties-example-1}
+
+This simple example writes messages to stdout.
+If you want to send messages to stderr instead,
+change the 'Target' value to `System.err`.
+
+~~~{.properties}
+# Set root logger level to DEBUG and its only appender to A1.
+log4j.rootLogger=DEBUG, A1
+
+# A1 is set to be a ConsoleAppender.
+log4j.appender.A1=org.apache.log4j.ConsoleAppender
+log4j.appender.A1.Target=System.out
+
+# The color of the message text shows the logging level.
+log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+log4j.appender.A1.layout.ConversionPattern=%.30c - %Y%m%y%n
+~~~
+
+## Properties Example 2 {#properties-example-2}
+
+The following Log4cxx 1.6 configuration file uses
+the variables added in the \ref com/foo/config4.cpp example
+to store a log file per executable in a product related logs directory:
+- Windows, "C:\ProgramData\CompanyName\ProductName\Logs"
+- Non-Windows, "/var/local/companyName/productName/Logs"
+
+~~~{.properties}
+# 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=${LocalAppData}/${CURRENT_VENDOR_FOLDER}/${CURRENT_PRODUCT_FOLDER}/Logs/${PROGRAM_FILE_PATH.STEM}.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 - %Y%m%y%n
+
+log4j.appender.csvData=org.apache.log4j.FileAppender
+log4j.appender.csvData.File=${LocalAppData}/${CURRENT_VENDOR_FOLDER}/${CURRENT_PRODUCT_FOLDER}/MessageData.csv
+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
+
+# Log4cxx internal debugging
+#log4j.debug=true
+~~~
# 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}
-This simple example simply writes messages to stdout.
-If you want to send messages to stderr instead, simply change the 'Target'
value
-to `System.err`.
-
+This simple example writes messages to stdout.
+If you want to send messages to stderr instead,
+change the 'Target' value to `System.err`.
+The color of the message text shows the logging level.
~~~{.xml}
<?xml version="1.0" encoding="UTF-8" ?>
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";>
@@ -60,7 +159,7 @@ to `System.err`.
<appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%m%n"/>
+ <param name="ConversionPattern" value="%.30c - %Y%m%y%n"/>
</layout>
</appender>
@@ -80,6 +179,7 @@ Hello there!
## XML Example 2 {#xml-example-2}
This example sends data to both stdout, as well as to a file.
+
With this configuration the "example.log" file will be created in our working
directory.
~~~{.xml}
@@ -89,14 +189,14 @@ With this configuration the "example.log" file will be
created in our working di
<appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p
- %m%n"/>
+ <param name="ConversionPattern" value="%c - %Y%m%y%n"/>
</layout>
</appender>
<appender name="FileAppender" class="org.apache.log4j.FileAppender">
<param name="file" value="example.log" />
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p
- %m%n" />
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss.SSS}] %c
%-5p - %m%n" />
</layout>
</appender>
@@ -135,23 +235,31 @@ Assume that our loggers are in our code as such:
For this configuration, we have set any logger that is at the `com` level or
below
to be debug. However, we have also set the logger `com.example` to have a more
verbose `trace` level to see more information from that particular logger.
-The "example.log" file will be created in our temporary directory.
+The log file will be created in a program data directory
+where the path uses the program vendor and product name.
+
+The following Log4cxx 1.6 configuration file uses
+the variables added in the \ref com/foo/config4.cpp example
+to store a log file per executable in a product related logs directory:
+- Windows, "C:\ProgramData\CompanyName\ProductName\Logs"
+- Non-Windows, "/var/local/companyName/productName/Logs"
~~~{.xml}
<?xml version="1.0" encoding="UTF-8" ?>
+<!--log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";
debug="true" -->
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";>
<appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p
- %m%n"/>
+ <param name="ConversionPattern" value="%c - %Y%m%y%n"/>
</layout>
</appender>
<appender name="FileAppender" class="org.apache.log4j.FileAppender">
- <param name="file" value="${TMP}/example.log" />
+ <param name="file"
value="${LocalAppData}/${CURRENT_VENDOR_FOLDER}/${CURRENT_PRODUCT_FOLDER}/Logs/${PROGRAM_FILE_PATH.STEM}.log"
/>
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p
- %m%n" />
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss.SSS}] %c
%-5p - %m%n" />
</layout>
</appender>
@@ -207,7 +315,7 @@ everything else:
<appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
<param name="Target" value="System.out"/>
<layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p
- %m%n"/>
+ <param name="ConversionPattern" value="[%c - %Y%m%y%n"/>
</layout>
<filter class="org.apache.log4j.varia.StringMatchFilter">
@@ -238,4 +346,12 @@ the only messages that we saw were the ones with
"specific" in them.
\example auto-configured.cpp
This is an example of logging in static initialization code and
-using the current module name to select the Log4cxx configuration file.
+using the current module name (auto-configured) to select the Log4cxx
configuration file.
+In this example Log4cxx is configured by loading \ref auto-configured.xml.
+The function <code>com::foo::getLogger()</code>, which is called during
initialization,
+is implemented in the \ref com/foo/config4.cpp file.
+
+\example auto-configured.xml
+This is the configuration file used by the \ref auto-configured.cpp example.
+
+[Log4cxx internal debugging]:internal-debugging.html#internal-debugging
\ No newline at end of file
diff --git a/src/site/markdown/example-programs.md
b/src/site/markdown/example-programs.md
index 5ad3d527..344686f7 100644
--- a/src/site/markdown/example-programs.md
+++ b/src/site/markdown/example-programs.md
@@ -188,6 +188,8 @@ forwarded logging events to a remote Log4cxx server, which
would log
according to local server policy, for example by forwarding the log
event to a second Log4cxx server.
+For more runtime configuration examples, see [Configuration Samples].
+
\example com/foo/config.h
This header file is for encapsulating Log4cxx configuration.
@@ -198,4 +200,6 @@ This file is a simplified example of encapsulated Log4cxx
configuration.
This file is an example of how to use the current module name to select the
Log4cxx configuration file.
\example com/foo/config4.cpp
-This file is a simpler example of how to use the current module name to select
the Log4cxx configuration file.
\ No newline at end of file
+This file is a simpler example of how to use the current module name to select
the Log4cxx configuration file.
+
+[Configuration Samples]:configuration-samples.html
diff --git a/src/site/markdown/internal-debugging.md
b/src/site/markdown/internal-debugging.md
index bc592514..4e317d7d 100644
--- a/src/site/markdown/internal-debugging.md
+++ b/src/site/markdown/internal-debugging.md
@@ -18,13 +18,17 @@ Internal Debugging {#internal-debugging}
-->
Because Log4cxx is a logging library, we can't use it to output errors from
-the library itself. There are several ways to activate internal logging:
+the library itself.
-1. Configure the library directly by calling the
+There are several ways to activate internal debug logging:
+-# Setting the environment variable <code>LOG4CXX_DEBUG</code> to the value
<code>true</code>
+-# If using a properties file, add the line <code>log4j.debug=true</code> to
your file
+-# If using an XML file, add the <code>debug="true"</code> attribute in the
<code>log4j.configuration</code> element
+-# Configure the library programmatically by calling
[LogLog::setInternalDebugging](@ref
log4cxx.helpers.LogLog.setInternalDebugging)
-method
-2. If using a properties file, set the value `log4j.debug=true` in your
configuration file
-3. If using an XML file, set the attribute `internalDebug=true` in the root
node
-4. From the environment: `LOG4CXX_DEBUG=true`
-All error and warning messages are sent to stderr.
+To disable all messages, including error and warning messages,
+call [LogLog::setQuietMode(true)](@ref log4cxx.helpers.LogLog.setQuietMode).
+
+All Log4cxx internal logging messages are sent to stderr,
+with each line prefixed by <code>log4cxx:</code>.
