You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rm...@apache.org on 2021/03/27 00:45:55 UTC
[logging-log4cxx] branch filter-docs created (now 9c3614c)
This is an automated email from the ASF dual-hosted git repository.
rmiddleton pushed a change to branch filter-docs
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git.
at 9c3614c Added some documentation on how to use filters
This branch includes the following new commits:
new 9c3614c Added some documentation on how to use filters
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[logging-log4cxx] 01/01: Added some documentation on how to use
filters
Posted by rm...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
rmiddleton pushed a commit to branch filter-docs
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit 9c3614c3d2e17ecd452e085c8439c7b480895290
Author: Robert Middleton <ro...@rm5248.com>
AuthorDate: Fri Mar 26 20:45:39 2021 -0400
Added some documentation on how to use filters
---
src/site/markdown/configuration-samples.md | 55 ++++++++++++++++++++++++++++++
src/site/markdown/usage.md | 19 +++++++++++
2 files changed, 74 insertions(+)
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 @@ Sample output:
[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 @@ the non-FMT macros.
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