This is an automated email from the ASF dual-hosted git repository. swebb2066 pushed a commit to branch improve_configuration_examples in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit 2edde143eabc2bd83e9f942ec7665cf4e5687b02 Author: Stephen Webb <[email protected]> AuthorDate: Tue Aug 25 16:15:42 2026 +1000 Improve documented configuration examples --- 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}
