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/04/14 23:05:12 UTC
[logging-log4cxx] branch master updated: MapFilter documentation in
Markdown (#61)
This is an automated email from the ASF dual-hosted git repository.
rmiddleton 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 79352bd MapFilter documentation in Markdown (#61)
79352bd is described below
commit 79352bd0160866d06b61414f2dc83d1f71b44335
Author: pm-cfs <59...@users.noreply.github.com>
AuthorDate: Wed Apr 14 19:04:25 2021 -0400
MapFilter documentation in Markdown (#61)
* Markdown documentation for mapfilter
* Update to use backticks for code instead of italices
Remove html encoding and use code blocks to preserve semantics.
* One backtick for inline code only.
* Unnecessary tabs in table.
* Improved readability of XML.
Co-authored-by: Thorsten Schöning <62...@users.noreply.github.com>
---
src/site/markdown/filters/MapFilter.md | 127 +++++++++++++++++++++++++++++++++
1 file changed, 127 insertions(+)
diff --git a/src/site/markdown/filters/MapFilter.md b/src/site/markdown/filters/MapFilter.md
new file mode 100644
index 0000000..afad44d
--- /dev/null
+++ b/src/site/markdown/filters/MapFilter.md
@@ -0,0 +1,127 @@
+# MapFilter
+
+The MapFilter allows filtering against data elements that are in the Mapped Diagnostic Context (MDC).
+
+| **Parameter Name** | **Type** | **Description** |
+|:-------------------|:----------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Operator | LogString | If the operator is `AND` then all the key/value pairs must match; any other value is implicitly an `OR` and a match by any one of the key/value pairs will be considered to be a match. The default value is `OR`. |
+| AcceptOnMatch | LogString | Action to take when the filter matches. May be `true` or `false`. The default value is `false`. |
+| MDC key | LogString | Any name other than `Operator` or `AcceptOnMatch` is considered a key to the MDC along with the value to match on. Keys may only be specified once; duplicate keys will replace earlier ones. |
+
+In this configuration, the MapFilter can be used to filter based on system inserted values such as IP address and/or Username. In this example, we assume that the program has inserted appropriate values for `user.ip` and `user.name` into the MDC. In this case, when both the IP address is `127.0.0.1` and the Username is `test`, the entry will not be logged.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<log4j:configuration xmlns:log4j="http://logging.apache.org/">
+ <appender name="SIMPLE" class="log4cxx.FileAppender">
+ <layout class="log4cxx.SimpleLayout">
+ <param name="File"
+ value="logs/app.log"
+ />
+ <param name="Append"
+ value="true"
+ />
+ </layout>
+
+ <filter class="log4cxx.MapFilter">
+ <param name="user.ip"
+ value="127.0.0.1"
+ />
+ <param name="user.name"
+ value="test"
+ />
+ <param name="Operator"
+ value="AND"
+ />
+ <param name="AcceptOnMatch"
+ value="false"
+ />
+ </filter>
+ </appender>
+
+ <root>
+ <priority value="all" />
+ <appender-ref ref="SIMPLE" />
+ </root>
+</log4j:configuration>
+```
+
+If we wanted to exclude multiple IP addresses from the log, we need to define a separate filter for each one as we don’t support wildcards. Since the default `AcceptOnMatch` value is `false`, we can simplify to a single line per filter. In the configuration below we would skip logs for IP addresses matching 192.168.0.5 - 7.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<log4j:configuration xmlns:log4j="http://logging.apache.org/">
+ <appender name="SIMPLE" class="log4cxx.FileAppender">
+ <layout class="log4cxx.SimpleLayout">
+ <param name="File"
+ value="logs/app.log"
+ />
+ <param name="Append"
+ value="true"
+ />
+ </layout>
+
+ <filter class="MapFilter">
+ <param name="user.ip"
+ value="192.168.0.5"
+ />
+ </filter>
+ <filter class="MapFilter">
+ <param name="user.ip"
+ value="192.168.0.6"
+ />
+ </filter>
+ <filter class="MapFilter">
+ <param name="user.ip"
+ value="192.168.0.7"
+ />
+ </filter>
+ </appender>
+
+ <root>
+ <priority value="all" />
+ <appender-ref ref="SIMPLE" />
+ </root>
+</log4j:configuration>
+```
+
+In the case where we only want to log entries from a particular set of IP addresses (**not recommended** as this could be a security vulnerability), we need to have a final `DenyAllFilter` to catch the fall through. In this configuration, we would **only** log entries from 192.168.0.251 and 192.168.0.252.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<log4j:configuration xmlns:log4j="http://logging.apache.org/">
+ <appender name="SIMPLE" class="log4cxx.FileAppender">
+ <layout class="log4cxx.SimpleLayout">
+ <param name="File"
+ value="logs/app.log"
+ />
+ <param name="Append"
+ value="true"
+ />
+ </layout>
+
+ <filter class="MapFilter">
+ <param name="user.ip"
+ value="192.168.0.251"
+ />
+ <param name="AcceptOnMatch"
+ value="true"
+ />
+ </filter>
+ <filter class="MapFilter">
+ <param name="user.ip"
+ value="192.168.0.252"
+ />
+ <param name="AcceptOnMatch"
+ value="true"
+ />
+ </filter>
+ <filter class="DenyAllFilter" />
+ </appender>
+
+ <root>
+ <priority value="all" />
+ <appender-ref ref="SIMPLE" />
+ </root>
+</log4j:configuration>
+```