Merge pull request #57 from apache/building-instructions
Updated documentation on building log4cxx
diff --git a/src/site/markdown/configuration-samples.md b/src/site/markdown/configuration-samples.md
index 611ac81..413b003 100644
--- a/src/site/markdown/configuration-samples.md
+++ b/src/site/markdown/configuration-samples.md
@@ -212,3 +212,58 @@
[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 {#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:
+
+~~~{.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, "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}
+<?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="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%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.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index e3c0eb7..c110b98 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -831,6 +831,25 @@
A full example can be seen in the src/examples/cpp/format-string.cpp file.
+# Filtering Messages {#filtering}
+
+When dealing with large amounts of logging information, it can be useful
+to filter on messages that we are interested in. This filtering only
+takes places after determining that the level of the current logger would
+log the message in the first place. When defining filters, note that
+they can only be defined on a per-appender basis, they do not globally
+affect anything.
+
+The filtering system is similar in concept to Linux iptables rules, in
+that there is a chain of filters that can accept a log message, deny the
+log message, or pass the message on to the next filter. Accepting a log
+message means that the message will be logged immediately without
+consulting other filters. Denying has the opposite affect, immediately
+dropping the log message and not consulting any other filters.
+
+See the documentation for [Filter](@ref log4cxx.Filter) for some more
+information, or view a [configuration sample](@ref configuration-samples).
+
# Conclusions {#conclusions}
Apache Log4cxx is a popular logging package written in C++. One of its
