This is an automated email from the ASF dual-hosted git repository.
swebb2066 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 9388393a Rearrange the website index layout (#383)
9388393a is described below
commit 9388393a0352488daa7e65f6d9d14f05f7a6a706
Author: Stephen Webb <[email protected]>
AuthorDate: Sat May 11 10:44:07 2024 +1000
Rearrange the website index layout (#383)
* Merge filter configuration documentation into a single page
* Modernize Log4cxx customization example code
---
src/main/include/log4cxx/logger.h | 7 +-
src/site/doxy/DoxygenLayout.xml | 46 ++--
src/site/markdown/{0-community.md => community.md} | 0
src/site/markdown/extending.md | 23 +-
src/site/markdown/filters.md | 278 +++++++++++++++++++++
src/site/markdown/filters/LocationInfoFilter.md | 74 ------
src/site/markdown/filters/MapFilter.md | 148 -----------
src/site/markdown/filters/filters.md | 97 -------
src/site/markdown/index.md | 8 +-
9 files changed, 328 insertions(+), 353 deletions(-)
diff --git a/src/main/include/log4cxx/logger.h
b/src/main/include/log4cxx/logger.h
index de3e5ef4..3dd553e5 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -2042,10 +2042,6 @@ class LOG4CXX_EXPORT Logger :
LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
}
-/** @addtogroup LoggingMacros Logging macros
-@{
-*/
-
#if !defined(LOG4CXX_UNLIKELY)
#if __GNUC__ >= 3
/**
@@ -2093,6 +2089,9 @@ LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
#endif
#endif
+/** @addtogroup LoggingMacros Logging macros
+@{
+*/
/**
Add a new logging event containing \c message to attached appender(s) if this
logger is enabled for \c events.
diff --git a/src/site/doxy/DoxygenLayout.xml b/src/site/doxy/DoxygenLayout.xml
index b51cbac9..0b142e51 100644
--- a/src/site/doxy/DoxygenLayout.xml
+++ b/src/site/doxy/DoxygenLayout.xml
@@ -2,27 +2,35 @@
<!-- Generated by doxygen 1.8.13 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
- <tab type="mainpage" visible="yes" title=""/>
- <tab type="pages" visible="yes" title="" intro=""/>
- <tab type="modules" visible="yes" title="" intro=""/>
- <tab type="namespaces" visible="yes" title="">
- <tab type="namespacelist" visible="yes" title="" intro=""/>
- <tab type="namespacemembers" visible="yes" title="" intro=""/>
+ <tab type="mainpage" visible="yes" title="Introduction"/>
+ <tab type="pages" visible="yes" title="Usage Guide" intro="These pages
cover usage, concepts, examples and customising the behavior of the Log4cxx
library"/>
+ <tab type="usergroup" visible="yes" title="Reference Material" intro="">
+ <tab type="user" url="@ref LoggingMacros" visible="yes" title="Logging
macros" intro=""/>
+ <tab type="namespaces" visible="yes" title="">
+ <tab type="namespacelist" visible="yes" title="" intro=""/>
+ <tab type="namespacemembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="classes" visible="yes" title="">
+ <tab type="classlist" visible="yes" title="" intro=""/>
+ <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+ <tab type="hierarchy" visible="yes" title="" intro=""/>
+ <tab type="classmembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="files" visible="yes" title="">
+ <tab type="filelist" visible="yes" title="" intro=""/>
+ <tab type="globals" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="examples" visible="yes" title="" intro=""/>
</tab>
- <tab type="classes" visible="yes" title="">
- <tab type="classlist" visible="yes" title="" intro=""/>
- <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
- <tab type="hierarchy" visible="yes" title="" intro=""/>
- <tab type="classmembers" visible="yes" title="" intro=""/>
+ <tab type="usergroup" visible="yes" title="Other Information" intro="">
+ <tab type="user" url="https://github.com/apache/logging-log4cxx";
title="Source code repository"/>
+ <tab type="user" url="https://www.apache.org"; title="Apache"/>
+ <tab type="user" url="https://logging.apache.org"; title="Logging
Services">
+ <tab type="user" url="https://logging.apache.org/security.html";
visible="yes" title="Security"/>
+ <tab type="user" url="https://logging.apache.org/support.html";
visible="yes" title="Support"/>
+ <tab type="user" url="https://logging.apache.org/download.html";
visible="yes" title="Downloads"/>
+ </tab>
</tab>
- <tab type="files" visible="yes" title="">
- <tab type="filelist" visible="yes" title="" intro=""/>
- <tab type="globals" visible="yes" title="" intro=""/>
- </tab>
- <tab type="examples" visible="yes" title="" intro=""/>
- <tab type="user" url="https://www.apache.org"; title="Apache"/>
- <tab type="user" url="https://logging.apache.org"; title="Logging
Services"/>
- <tab type="user" url="https://github.com/apache/logging-log4cxx";
title="Github"/>
</navindex>
<!-- Layout definition for a class page -->
diff --git a/src/site/markdown/0-community.md b/src/site/markdown/community.md
similarity index 100%
rename from src/site/markdown/0-community.md
rename to src/site/markdown/community.md
diff --git a/src/site/markdown/extending.md b/src/site/markdown/extending.md
index 1e826363..218971a9 100644
--- a/src/site/markdown/extending.md
+++ b/src/site/markdown/extending.md
@@ -34,7 +34,7 @@ the virtual methods that are defined in log4cxx.Appender:
~~~{.cpp}
namespace log4cxx {
-class NullWriterAppender : public log4cxx::AppenderSkeleton {
+class NullWriterAppender : public AppenderSkeleton {
};
}
@@ -46,7 +46,7 @@ our new appender with Log4cxx:
~~~{.cpp}
namespace log4cxx {
-class NullWriterAppender : public log4cxx::AppenderSkeleton {
+class NullWriterAppender : public AppenderSkeleton {
public:
DECLARE_LOG4CXX_OBJECT(NullWriterAppender)
BEGIN_LOG4CXX_CAST_MAP()
@@ -80,23 +80,28 @@ These are basically stub methods, with a few comments on
their use:
~~~{.cpp}
NullWriterAppender(){}
- virtual void close(){}
+ void close() override {}
- virtual bool requiresLayout() const {
+ bool requiresLayout() const override {
return false;
}
- virtual void append(const spi::LoggingEventPtr& event,
log4cxx::helpers::Pool& p){
+ void append(const spi::LoggingEventPtr& event, helpers::Pool& p)
override {
// This gets called whenever there is a valid event for our
appender.
}
- virtual void activateOptions(log4cxx::helpers::Pool& /* pool */) {
+ void activateOptions(helpers::Pool& pool) override {
// Given all of our options, do something useful(e.g. open a
file)
}
- virtual void setOption(const LogString& option, const LogString& value){
- if (helpers::StringHelper::equalsIgnoreCase(option,
- LOG4CXX_STR("SOMEVALUE"), LOG4CXX_STR("somevalue"))){
+ void setOption(const LogString& option, const LogString& value)
override {
+ if (helpers::StringHelper::equalsIgnoreCase
+ ( option
+ , LOG4CXX_STR("SOMEVALUE")
+ , LOG4CXX_STR("somevalue")
+ )
+ )
+ {
// Do something with the 'value' here.
}
}
diff --git a/src/site/markdown/filters.md b/src/site/markdown/filters.md
new file mode 100644
index 00000000..1f14a6b5
--- /dev/null
+++ b/src/site/markdown/filters.md
@@ -0,0 +1,278 @@
+Filtering Log Messages {#filters}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+[TOC]
+
+
+# Labeling Log Output {#labeling-log-output}
+
+To uniquely stamp each request to relate it to a particular source,
+you can push contextual information
+into the *Nested Diagnostic Context* (NDC) using the *log4cxx::NDC* class
+or the *Mapped Diagnostic Context* provided by *log4cxx::MDC* class.
+For an example using log4cxx::NDC refer to \ref ndc-example.cpp.
+
+The NDC is managed per thread as a *stack* of contextual information.
+When the layout specifies that the NDC is to be included,
+each log entry will include the entire stack for the current thread.
+A log4cxx::PatternLayout allows named entries of the MDC
+to be included in the log message.
+The user is responsible for placing the correct information in the NDC/MDC
+by creating a *log4cxx::NDC* or *log4cxx::MDC* stack variable at
+a few well-defined points in the code. In contrast, the per-client
+logger approach commands extensive changes in the code.
+
+To illustrate this point, let us take the example of a servlet
+delivering content to numerous clients. The servlet can build the NDC at
+the very beginning of the request before executing other code. The
+contextual information can be the client's host name and other
+information inherent to the request, typically information contained in
+cookies. Hence, even if the servlet is serving multiple clients
+simultaneously, the logs initiated by the same code, i.e. belonging to
+the same logger, can still be distinguished because each client request
+will have a different NDC stack. Contrast this with the complexity of
+passing a freshly instantiated logger to all code exercised during the
+client's request.
+
+Nevertheless, some sophisticated applications, such as virtual hosting
+web servers, must log differently depending on the virtual host context
+and also depending on the software component issuing the request. Recent
+Log4cxx releases support multiple hierarchy trees. This enhancement
+allows each virtual host to possess its own copy of the logger
+hierarchy.
+
+# Excluding Log Output {#excluding-log-output}
+
+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.spi.Filter) for some more
+information, or view a [configuration sample](@ref configuration-samples).
+
+The following filters are available:
+* [AndFilter](@ref log4cxx.filter.AndFilter) - Takes in a list of filters that
must all match
+* [DenyAllFilter](@ref log4cxx.filter.DenyAllFilter) - Drops all log messages
that reach it
+* [LevelMatchFilter](@ref log4cxx.filter.LevelMatchFilter) - Filter log
messages based off of their level
+* [LevelRangeFilter](@ref log4cxx.filter.LevelRangeFilter) - Filter log
messages based off of their level in a given range
+* [LocationInfoFilter](@ref log4cxx.filter.LocationInfoFilter) - Filter log
messages based off of their location(line number and/or method name)
+* [LoggerMatchFilter](@ref log4cxx.filter.LoggerMatchFilter) - Accept or deny
depending on the logger that generated the message
+* [MapFilter](@ref log4cxx.filter.MapFilter) - Based off of the log messages
MDC, accept or deny the message
+* [StringMatchFilter](@ref log4cxx.filter.StringMatchFilter) - If the given
substring is found in the message, accept or deny
+
+# Runtime Configuration {#configure-filter}
+
+## Using MDC Values {#map-filter}
+
+The [MapFilter](@ref log4cxx.filter.MapFilter) allows filtering against data
elements that are in the *Mapped Diagnostic Context* (*log4cxx::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](@ref log4cxx.filter.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>
+```
+
+## Using the Request Location {#location-info-filter}
+
+The [LocationInfoFilter](@ref log4cxx.filter.LocationInfoFilter) allows
filtering against the location in the file that
+the log statement was made. Location information must not be disabled in order
+for this filter to be effective. Location information is disabled with the
+`LOG4CXX_DISABLE_LOCATION_INFO` macro.
+
+| **Parameter Name** | **Type** | **Description**
|
+|:-------------------|:----------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Operator | LogString | If the operator is `AND` then all the parts
of the location(line number and method name) must match. If set to `OR` then
only one needs to match. The default value is `OR`. |
+| AcceptOnMatch | bool | If `true`, accept the message when it matches
the parameters. If `false`, deny the message when it matches the parameters. |
+| LineNumber | int | The line number to match on. The default line
number is -1. |
+| Method | LogString | The method to match on. The method name
may be compiler-specific. On GCC, the method name will look like
`Class::methodName` |
+
+Assume that our code looks something like the following:
+
+~~~{.cpp}
+ LOG4CXX_TRACE(logger, "About to do something!");
+ for( int x = 0; x < 100; x++ ){
+ LOG4CXX_TRACE(logger, "Do something number " << x);
+ }
+~~~
+
+For various reasons, we may want to know that we are about to do something, but
+we don't want to know each iteration of the loop. In order to filter out this
+one message we can create a LocationInfoFilter in order to specifiy the line
+number that this message is on in order to filter it out:
+
+~~~{.xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<log4j:configuration xmlns:log4j="http://logging.apache.org/";>
+ <appender name="SIMPLE" class="ConsoleAppender">
+ <param name="Target" value="System.err"/>
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%p - %m%n"/>
+ </layout>
+
+ <filter class="LocationInfoFilter">
+ <param name="LineNumber" value="182" />
+ <param name="Operator" value="OR" />
+ <param name="AcceptOnMatch" value="false" />
+ </filter>
+ </appender>
+ <root>
+ <priority value="all" />
+ <appender-ref ref="SIMPLE" />
+ </root>
+</log4j:configuration>
+~~~
+
+Doing this allows us to still see the "About to do something!" message, but
+ignore each iteration of the loop.
+
+
+\example ndc-example.cpp
+This example shows how to add a context string to each logging message using
the NDC.
diff --git a/src/site/markdown/filters/LocationInfoFilter.md
b/src/site/markdown/filters/LocationInfoFilter.md
deleted file mode 100644
index 049cc130..00000000
--- a/src/site/markdown/filters/LocationInfoFilter.md
+++ /dev/null
@@ -1,74 +0,0 @@
-LocationInfoFilter {#location-info-filter}
-===
-<!--
- Note: License header cannot be first, as doxygen does not generate
- cleanly if it before the '==='
--->
-<!--
- 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.
--->
-
-The LocationInfoFilter allows filtering against the location in the file that
-the log statement was made. Location information must not be disabled in order
-for this filter to be effective. Location information is disabled with the
-`LOG4CXX_DISABLE_LOCATION_INFO` macro.
-
-| **Parameter Name** | **Type** | **Description**
|
-|:-------------------|:----------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Operator | LogString | If the operator is `AND` then all the parts
of the location(line number and method name) must match. If set to `OR` then
only one needs to match. The default value is `OR`. |
-| AcceptOnMatch | bool | If `true`, accept the message when it matches
the parameters. If `false`, deny the message when it matches the parameters. |
-| LineNumber | int | The line number to match on. The default line
number is -1. |
-| Method | LogString | The method to match on. The method name
may be compiler-specific. On GCC, the method name will look like
`Class::methodName` |
-
-Assume that our code looks something like the following:
-
-~~~{.cpp}
- LOG4CXX_TRACE(logger, "About to do something!");
- for( int x = 0; x < 100; x++ ){
- LOG4CXX_TRACE(logger, "Do something number " << x);
- }
-~~~
-
-For various reasons, we may want to know that we are about to do something, but
-we don't want to know each iteration of the loop. In order to filter out this
-one message we can create a LocationInfoFilter in order to specifiy the line
-number that this message is on in order to filter it out:
-
-~~~{.xml}
-<?xml version="1.0" encoding="UTF-8"?>
-<log4j:configuration xmlns:log4j="http://logging.apache.org/";>
- <appender name="SIMPLE" class="ConsoleAppender">
- <param name="Target" value="System.err"/>
-
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%p - %m%n"/>
- </layout>
-
- <filter class="LocationInfoFilter">
- <param name="LineNumber" value="182" />
- <param name="Operator" value="OR" />
- <param name="AcceptOnMatch" value="false" />
- </filter>
- </appender>
- <root>
- <priority value="all" />
- <appender-ref ref="SIMPLE" />
- </root>
-</log4j:configuration>
-~~~
-
-Doing this allows us to still see the "About to do something!" message, but
-ignore each iteration of the loop.
diff --git a/src/site/markdown/filters/MapFilter.md
b/src/site/markdown/filters/MapFilter.md
deleted file mode 100644
index 6ef96b41..00000000
--- a/src/site/markdown/filters/MapFilter.md
+++ /dev/null
@@ -1,148 +0,0 @@
-MapFilter {#map-filter}
-===
-<!--
- Note: License header cannot be first, as doxygen does not generate
- cleanly if it before the '==='
--->
-<!--
- 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.
--->
-
-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>
-```
diff --git a/src/site/markdown/filters/filters.md
b/src/site/markdown/filters/filters.md
deleted file mode 100644
index 4e3ab354..00000000
--- a/src/site/markdown/filters/filters.md
+++ /dev/null
@@ -1,97 +0,0 @@
-Filtering Log Messages {#filters}
-===
-<!--
- Note: License header cannot be first, as doxygen does not generate
- cleanly if it before the '==='
--->
-<!--
- 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.
--->
-[TOC]
-
-## Labeling Log Output {#labeling-log-output}
-
-To uniquely stamp each request to relate it to a particular source,
-you can push contextual information
-into the *Nested Diagnostic Context* (NDC) using the *log4cxx::NDC* class
-or the *Mapped Diagnostic Context* provided by *log4cxx::MDC* class.
-For an example using log4cxx::NDC refer to \ref ndc-example.cpp.
-
-The NDC is managed per thread as a *stack* of contextual information.
-When the layout specifies that the NDC is to be included,
-each log entry will include the entire stack for the current thread.
-A log4cxx::PatternLayout allows named entries of the MDC
-to be included in the log message.
-The user is responsible for placing the correct information in the NDC/MDC
-by creating a *log4cxx::NDC* or *log4cxx::MDC* stack variable at
-a few well-defined points in the code. In contrast, the per-client
-logger approach commands extensive changes in the code.
-
-To illustrate this point, let us take the example of a servlet
-delivering content to numerous clients. The servlet can build the NDC at
-the very beginning of the request before executing other code. The
-contextual information can be the client's host name and other
-information inherent to the request, typically information contained in
-cookies. Hence, even if the servlet is serving multiple clients
-simultaneously, the logs initiated by the same code, i.e. belonging to
-the same logger, can still be distinguished because each client request
-will have a different NDC stack. Contrast this with the complexity of
-passing a freshly instantiated logger to all code exercised during the
-client's request.
-
-Nevertheless, some sophisticated applications, such as virtual hosting
-web servers, must log differently depending on the virtual host context
-and also depending on the software component issuing the request. Recent
-Log4cxx releases support multiple hierarchy trees. This enhancement
-allows each virtual host to possess its own copy of the logger
-hierarchy.
-
-## Excluding Log Output {#excluding-log-output}
-
-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.spi.Filter) for some more
-information, or view a [configuration sample](@ref configuration-samples).
-
-The following filters are available:
-* [AndFilter](@ref log4cxx.filter.AndFilter) - Takes in a list of filters that
must all match
-* [DenyAllFilter](@ref log4cxx.filter.DenyAllFilter) - Drops all log messages
that reach it
-* [LevelMatchFilter](@ref log4cxx.filter.LevelMatchFilter) - Filter log
messages based off of their level
-* [LevelRangeFilter](@ref log4cxx.filter.LevelRangeFilter) - Filter log
messages based off of their level in a given range
-* [LocationInfoFilter](@ref log4cxx.filter.LocationInfoFilter) - Filter log
messages based off of their location(line number and/or method name)
-* [LoggerMatchFilter](@ref log4cxx.filter.LoggerMatchFilter) - Accept or deny
depending on the logger that generated the message
-* [MapFilter](@ref log4cxx.filter.MapFilter) - Based off of the log messages
MDC, accept or deny the message
-* [StringMatchFilter](@ref log4cxx.filter.StringMatchFilter) - If the given
substring is found in the message, accept or deny
-
-The following pages have information on specific filters:
-
-* @subpage map-filter
-* @subpage location-info-filter
-
-\example ndc-example.cpp
-This example shows how to add a context string to each logging message using
the NDC.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 510ae002..e3650301 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,3 +1,9 @@
+Introduction {#introduction}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -15,8 +21,6 @@
limitations under the License.
-->
-# Short introduction to Apache Log4cxx
-
Apache Log4cxx is a logging framework for C++ patterned after [Apache log4j],
which uses [Apache Portable Runtime] for most platform-specific code and should
be usable on any platform supported by APR. Apache Log4cxx is licensed under
