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 99b44ed2 Improve documented configuration examples (#740)
99b44ed2 is described below
commit 99b44ed2f32726ac4b583f113a6c386dabcbafae
Author: Stephen Webb <[email protected]>
AuthorDate: Wed Aug 26 09:52:57 2026 +1000
Improve documented configuration examples (#740)
---
src/examples/cpp/CMakeLists.txt | 5 +-
src/examples/cpp/MyApp4.cpp | 33 ++++++++++++
src/examples/cpp/MyApp4.xml | 42 ++++++++++++++++
src/site/markdown/configuration-samples.md | 80 ++++++++++--------------------
4 files changed, 105 insertions(+), 55 deletions(-)
diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt
index 87dc2ec6..f9bf6536 100644
--- a/src/examples/cpp/CMakeLists.txt
+++ b/src/examples/cpp/CMakeLists.txt
@@ -15,7 +15,7 @@
# limitations under the License.
#
-set(ALL_LOG4CXX_EXAMPLES auto-configured console delayedloop stream
ndc-example custom-appender MyApp1 MyApp2)
+set(ALL_LOG4CXX_EXAMPLES auto-configured console delayedloop stream
ndc-example custom-appender MyApp1 MyApp2 MyApp4)
if(NOT LOG4CXX_DOMCONFIGURATOR_SUPPORT)
list(REMOVE_ITEM ALL_LOG4CXX_EXAMPLES delayedloop custom-appender)
endif()
@@ -41,6 +41,9 @@ foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES)
if(${exampleName} STREQUAL MyApp2)
target_sources(${PROGRAM_NAME} PRIVATE com/foo/config2.cpp
com/foo/bar.cpp)
endif()
+ if(${exampleName} STREQUAL MyApp4)
+ target_sources(${PROGRAM_NAME} PRIVATE com/foo/config4.cpp
com/foo/bar.cpp)
+ endif()
if(${exampleName} STREQUAL MyApp-qt)
target_sources(${PROGRAM_NAME} PRIVATE com/foo/config-qt.cpp
com/foo/bar-qt.cpp)
target_link_libraries(${PROGRAM_NAME} PRIVATE log4cxx-qt)
diff --git a/src/examples/cpp/MyApp4.cpp b/src/examples/cpp/MyApp4.cpp
new file mode 100644
index 00000000..f80711e3
--- /dev/null
+++ b/src/examples/cpp/MyApp4.cpp
@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "com/foo/config.h"
+#include "com/foo/bar.h"
+
+int main() {
+ int result = EXIT_SUCCESS;
+ try {
+ auto logger = com::foo::getLogger("com.MyApp");
+ LOG4CXX_INFO(logger, "Entering application.");
+ com::foo::Bar bar;
+ bar.doIt();
+ LOG4CXX_INFO(logger, "Exiting application.");
+ }
+ catch(std::exception&) {
+ result = EXIT_FAILURE;
+ }
+ return result;
+}
diff --git a/src/examples/cpp/MyApp4.xml b/src/examples/cpp/MyApp4.xml
new file mode 100644
index 00000000..9f15cd99
--- /dev/null
+++ b/src/examples/cpp/MyApp4.xml
@@ -0,0 +1,42 @@
+<?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="A1" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <param name="Threshold" value="info"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%c - %Y%m%y%n"/>
+ </layout>
+ </appender>
+
+ <appender name="A2" class="org.apache.log4j.RollingFileAppender">
+ <param name="file"
value="${LocalAppData}/${CURRENT_VENDOR_FOLDER}/${CURRENT_PRODUCT_FOLDER}/logs/${PROGRAM_FILE_PATH.STEM}.log"
/>
+ <param name="BufferedIO" value="true" />
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss.SSS}] %c
%-5p - %m%n" />
+ </layout>
+ <rollingPolicy class="org.apache.log4j.rolling.FixedWindowRollingPolicy">
+ <param name="fileNamePattern"
value="${LocalAppData}/${CURRENT_VENDOR_FOLDER}/${CURRENT_PRODUCT_FOLDER}/logs/${PROGRAM_FILE_PATH.STEM}.%i.log"/>
+ <param name="minIndex" value="0"/>
+ </rollingPolicy>
+ <triggeringPolicy
class="org.apache.log4j.rolling.SizeBasedTriggeringPolicy">
+ <param name="maxFileSize" value="4MB" />
+ </triggeringPolicy>
+ </appender>
+
+ <root asynchronous="true" >
+ <priority value="info" />
+ <appender-ref ref="A2"/>
+ </root>
+
+ <logger name="com" >
+ <priority value="debug"/>
+ <appender-ref ref="A1"/>
+ </logger>
+
+ <logger name="com.foo" >
+ <priority value="trace"/>
+ </logger>
+
+</log4j:configuration>
\ No newline at end of file
diff --git a/src/site/markdown/configuration-samples.md
b/src/site/markdown/configuration-samples.md
index e884dc98..c9e431da 100644
--- a/src/site/markdown/configuration-samples.md
+++ b/src/site/markdown/configuration-samples.md
@@ -147,10 +147,10 @@ log4j.rootCategory=INFO, A1
log4j.asynchronous.root=true
log4j.appender.A1=org.apache.log4j.RollingFileAppender
+log4j.appender.A1.BufferedIO=true
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
@@ -262,75 +262,47 @@ Sample output:
This example shows how you can configure logging for a particular category.
-Assume that our loggers are in our code as such:
-
-~~~{.cpp}
- log4cxx::LoggerPtr root = log4cxx::Logger::getRootLogger();
- log4cxx::LoggerPtr com = log4cxx::Logger::getLogger( "com" );
- log4cxx::LoggerPtr com_example = log4cxx::Logger::getLogger(
"com.example" );
-
- LOG4CXX_INFO( root, "Hello there!" );
- LOG4CXX_DEBUG( com, "com logger debug" );
- LOG4CXX_DEBUG( com_example, "com.example debug message" );
- LOG4CXX_TRACE( com, "com debug message" );
- LOG4CXX_TRACE( com_example, "com.example trace message" );
-~~~
-
-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 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:\Users\XXXXX\AppData\Local\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="%c - %Y%m%y%n"/>
- </layout>
- </appender>
+For this configuration, we have set loggers at the `com` level or below to be
a `debug` level.
+we have also set the logger `com.foo` to have the more
+verbose `trace` level to see more information from that particular logger.
+All events are sent to the `A2` appender attached to the `root` logger,
+a file appender, but the `threshold` attached to the `A1` appender
+limits events to only `info` and above appearing on standard output.
- <appender name="FileAppender" class="org.apache.log4j.FileAppender">
- <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.SSS}] %c
%-5p - %m%n" />
- </layout>
- </appender>
+The `asynchronous` attribute on the `root` logger tells Log4cxx
+to do `A2` appender output in a background thread.
+The `BufferedIO` property on the `A2` appender
+helps stop the ring-buffer from becoming full.
- <root asynchronous="true" >
- <priority value="info" />
- <appender-ref ref="ConsoleAppender"/>
- <appender-ref ref="FileAppender"/>
- </root>
+\include MyApp4.xml
- <logger name="com" >
- <priority value="debug"/>
- </logger>
+Assume that our loggers are in our code as such:
- <logger name="com.example" >
- <priority value="trace"/>
- </logger>
+~~~{.cpp}
+ log4cxx::LoggerPtr root = log4cxx::Logger::getRootLogger();
+ log4cxx::LoggerPtr com = log4cxx::Logger::getLogger( "com" );
+ log4cxx::LoggerPtr com_foo = log4cxx::Logger::getLogger( "com.foo" );
-</log4j:configuration>
+ LOG4CXX_INFO( root, "Hello there!" );
+ LOG4CXX_DEBUG( com, "some debug" );
+ LOG4CXX_DEBUG( com_foo, "another debug message" );
+ LOG4CXX_TRACE( com, "a trace message" );
+ LOG4CXX_TRACE( com_foo, "a submodule trace message" );
~~~
-Sample output:
+Sample file content:
~~~
[2020-12-24 16:05:48] root INFO - Hello there!
-[2020-12-24 16:05:48] com DEBUG - com logger debug
-[2020-12-24 16:05:48] com.example DEBUG - com.example debug message
-[2020-12-24 16:05:48] com.example TRACE - com.example trace message
+[2020-12-24 16:05:48] com DEBUG - some debug
+[2020-12-24 16:05:48] com.foo DEBUG - another debug message
+[2020-12-24 16:05:48] com.foo TRACE - a submodule trace message
~~~
### XML Example 4 {#xml-example-4}
