As Log4cxx was designed to be extendable, option names are not constrained by the core library. The configuration file parsers, DOMConfigurator and PropertyConfigurator, just send the key/value pair to an instance of the named appender/layout/filter class. Refer to the setOption method documentation for configurable option names and supported values. Note that a base class may implement some options while the concrete class implements others. Check the full class hierarchy when looking for a configuration option.

Default Initialization Behaviour

The Log4cxx library does not make any assumptions about its environment. In particular, when initially created the root Logger has no appender. However the library will attempt automatic configuration.

If the LoggerRepositoy is not yet configured on the first call to getLogger of LogManager, the configure method of DefaultConfigurator is called via ensureIsConfigured method of LoggerRepository. Unless the environment variable "LOG4CXX_CONFIGURATION" (or "log4j.configuration") has a value, the current directory is examined for a file with extension ".xml" or ".properties" with a base name "log4cxx" or "log4j".

To use automatic configuration with a non-standard file name create and use your own wrapper for getLogger. A full example can be seen in the com/foo/config4.cpp file.

Runtime Property Values

The value of an enviroment variable can be used in a property value. Instances of the form ${VarName} will be replaced with the value of the environment variable VarName. 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:

auto& props = log4cxx::spi::Configurator::properties();

props.setProperty(LOG4CXX_STR("VarName"), LOG4CXX_STR("my-varname-value"));

log4cxx::spi::Configurator::properties

static helpers::Properties & properties()

The key value pairs used when expanding ${varname} instances in a configuration file.

Also available in Log4cxx 1.6 are variables that hold the currently executing program file path and the std::filesystem::path 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.

To check the correct values are used when your configuration file is loaded, use Log4cxx internal debugging.

Configuration Samples

The following snippets show various ways of configuring Log4cxx.

Properties Files

Log4cxx may be configured using a Java properties (key=value) type file.

Properties Example 1

This simple example writes colored messages (a color per logging level) to stdout. If you want to send messages to stderr instead, change the 'Target' value to System.err.

# 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

The following Log4cxx 1.6 configuration file uses the variables added in the 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"

# 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

Another way of configuring Log4cxx is with an XML file. The following are some XML configuration examples.

XML Example 1

This simple example writes colored messages (a color per logging level) 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 version="1.0" encoding="UTF-8" ?>
<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="%.30c - %Y%m%y%n"/>
    </layout>
  </appender>
 
  <root>
     <priority value="info" />
     <appender-ref ref="ConsoleAppender"/>
  </root>
 
</log4j:configuration>

Sample output:

Hello there!

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 version="1.0" encoding="UTF-8" ?>
<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>
 
  <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.SSS}] %c %-5p - %m%n" />
    </layout>
  </appender>
 
  <root>
     <priority value="info" />
     <appender-ref ref="ConsoleAppender"/>
     <appender-ref ref="FileAppender"/>
  </root>
 
</log4j:configuration>

Sample output:

[2020-12-24 15:57:35] root INFO - Hello there!

XML Example 3

This example shows how you can configure logging for a particular category.

Assume that our loggers are in our code as such:

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 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 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>
 
  <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>
 
  <root>
     <priority value="info" />
     <appender-ref ref="ConsoleAppender"/>
     <appender-ref ref="FileAppender"/>
  </root>
 
  <logger name="com" >
     <priority value="debug"/>
  </logger>
 
  <logger name="com.example" >
     <priority value="trace"/>
  </logger>
 
</log4j:configuration>

Sample output:

[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

XML Example 4

This example shows how to add a filter to an appender that will accept messages that match a certain string. If our loggers are configured as such:

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, "Starting to do the thing" );
LOG4CXX_DEBUG( com_example, "A more specific logger" );
LOG4CXX_TRACE( com, "Done with the thing" );
LOG4CXX_TRACE( com_example, "A very specific message" );

and we only want to see messages that have the string "specific" in them, we can create a filter chain that will accept messages that have that, and deny everything else:

<?xml version="1.0" encoding="UTF-8" ?>
<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>
 
    <filter class="org.apache.log4j.varia.StringMatchFilter">
      <param name="StringToMatch"
             value="specific" />
      <param name="AcceptOnMatch" value="true" />
    </filter>
 
    <filter class="org.apache.log4j.varia.DenyAllFilter"/>
  </appender>
 
  <root>
     <priority value="trace" />
     <appender-ref ref="ConsoleAppender"/>
  </root>
</log4j:configuration>

Sample output:

[2021-03-26 20:20:36] com.example DEBUG - A more specific logger

[2021-03-26 20:20:36] com.example TRACE - A very specific message

Note that even though we have the root logger set to the most verbose level(trace), the only messages that we saw were the ones with "specific" in them.