You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rg...@apache.org on 2012/01/07 10:57:07 UTC
svn commit: r1228586 - in
/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual:
plugins.xml thread-context.xml
Author: rgoers
Date: Sat Jan 7 09:57:06 2012
New Revision: 1228586
URL: http://svn.apache.org/viewvc?rev=1228586&view=rev
Log:
Document plugins and ThreadContext
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/plugins.xml
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/plugins.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/plugins.xml?rev=1228586&r1=1228585&r2=1228586&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/plugins.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/plugins.xml Sat Jan 7 09:57:06 2012
@@ -24,17 +24,81 @@
<body>
<section name="Plugins">
+ <a name="Introduction"/>
+ <subsection name="Introduction">
+ <p>
+ Log4j 1.x allowed for extension by requiring class attributes on most of the configuration
+ declarations. In the case of some elements, notably the PatternLayout, the only way to add
+ new pattern converters was to extend the PatternLayout class and add them via code. One of
+ goals of Log4j 2 is to make extending it extremely easy through the use of plugins.
+ </p>
+ <p>
+ In Log4j 2 a plugin is declared by adding a Plugin annotation to the class declaration. During
+ initialization the Configuration will invoke the PluginManager to locate all the Log4j plugins
+ that are located in the declared <a href="./configuration.html#ConfigurationSyntax">packages</a>.
+ As the configuration is processed the appropriate plugins will be automatically configured and
+ initialized. Log4j 2 utilizes a few different types of plugins which are described in the follownig
+ sections.
+ </p>
+ </subsection>
<a name="Core"/>
<subsection name="Core">
-
+ <p>
+ Core plugins are those that are directly represented by an element in a configuration file, such as an
+ Appender, Logger or Filter. Custom plugins that conform to the rules laid out in the next paragraph
+ may simply be referenced in the configuration, provided they are appropriate configured to be
+ loaded by the PluginManager.
+ </p>
+ <p>
+ Every Core plugin must declare a static method that is marked with a PluginFactory annotation. To
+ allow the Configuration to pass the correct parameters to the method, every
+ parameter to the method must be annotated as one of the following attribute types. Each
+ attribute or element annotation must include the name that must be present in the configuration
+ in order to match the configuration item to its respective parameter.
+ </p>
+ <h4>Attribute Types</h4>
+ <dl>
+ <dt>PluginAttr</dt>
+ <dd>The parameter must resolve to a String, although it can be the String representation of a
+ boolean. numeric value, or any other Object that can be created from a String value.</dd>
+ <dt>PluginElement</dt>
+ <dd>The parameter may represent a complex object that itself has parameters that can be configured.</dd>
+ <dt>PluginConfiguration</dt>
+ <dd>The current Configuration object will be passed to the plugin as a parameter.</dd>
+ </dl>
</subsection>
<a name="Converters"/>
<subsection name="Converters">
-
+ <p>
+ Converters are used by
+ <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
+ to render the elements identified by the conversion pattern. Every converter must specify its type as
+ "Converter" on the Plugin attribute, have a static newInstance method that accepts an array of Strings as
+ its only parameter and returns an instance of the Converter, and must have a ConverterKeys annotation
+ present that contains the array of converter patterns that will cause the Converter to be selected.
+ Converters that are meant to handle LogEvents must extend the LogEventPatternConverter class and
+ must implement a format method that accepts a LogEvent and a StringBuilder as arguments. The Converter
+ should append the result of its operation to the StringBuilder.
+ </p>
+ <p>
+ A second type of Converter is the FileConverter - which must have "FileConverter" specified in the
+ type attribute of the Plugin annotation. While similar to a LogEventPatternConverter, instead
+ of a single format method these Converters will have two variations; one that takes an Object and
+ one that takes an array of Objects instead of the LogEvent. Both append to the provided StringBuilder
+ in the same fashion as a LogEventPatternConverter. These Converters are typically used by the
+ RollingFileAppender to construct the name of the file to log to.
+ </p>
</subsection>
<a name="Lookups"/>
<subsection name="Lookups">
-
+ <p>
+ Lookups are perhaps the simplest plugins of all. They must declare their type as "Lookup" on the
+ plugin annotation and must implement the StrLookup interface. They will have two methods; a
+ lookup method that accepts a String key and returns a String value and a second lookup method that
+ accepts both a LogEvent and a String key and returns a String. Lookups may be referenced by
+ specifying ${<i>name</i>:key} where <i>name</i> is the name specified in the Plugin annotation and
+ key is the name of the item to locate.
+ </p>
</subsection>
</section>
</body>
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml?rev=1228586&r1=1228585&r2=1228586&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml Sat Jan 7 09:57:06 2012
@@ -24,7 +24,99 @@
<body>
<section name="Thread Context">
+ <subsection name="Introduction">
+ <p>Log4j introduced the concept of the Mapped Diagnostic Context or MDC. It has been documented and
+ discussed in numerous places including
+ <a href="http://veerasundar.com/blog/2009/10/log4j-mdc-mapped-diagnostic-context-what-and-why/">Log4j MDC: What and Why</a> and
+ <a href="http://blog.f12.no/wp/2004/12/09/log4j-and-the-mapped-diagnostic-context/">Log4j and the Mappend Diagnostic Context</a>.
+ In addition, Log4j 1.x provides support for a Nested Diagnostic Context or NDC. It too has been documented
+ and discussed in various places such as
+ <a href="http://lstierneyltd.com/blog/development/log4j-nested-diagnostic-contexts-ndc/">Log4j NDC</a>.
+ SLF4J/Logback followed with its own implementation of the MDC, which is documented very well at
+ <a href="http://logback.qos.ch/manual/mdc.html">Mapped Diagnostic Context</a>.
+ </p>
+ <p>Log4j 2 continues with the idea of the MDC and the NDC but merges them into a single Thread Context.
+ The Thread Context Map is the equivalent of the MDC and the Thread Context Stack is the equivalent of the
+ NDC. Although these are frequently used for purposes other than diagnosing problems, they are still
+ frequently referred to as the MDC and NDC in Log4j 2 since they are already well known by those acronyms.
+ </p>
+ </subsection>
+ <subsection name="Fish Tagging">
+ <p>Most real-world systems have to deal with multiple clients simultaneously. In a typical multithreaded
+ implementation of such asystem, different threads will handle different clients. Logging is
+ especially well suited to trace and debug complex distributed applications. A common approach to
+ differentiate the logging output of one client from another is to instantiate a new separate logger for
+ each client. This promotes the proliferation of loggers and increases the management overhead of logging.
+ </p>
+ <p>A lighter technique is to uniquely stamp each log request initiated from the same client interaction.
+ Neil Harrison described this method in the book "Patterns for Logging Diagnostic Messages," in <em>Pattern
+ Languages of Program Design 3</em>, edited by R. Martin, D. Riehle, and F. Buschmann
+ (Addison-Wesley, 1997). Just as a fish can be tagged and have its movement tracked, stamping log
+ events with a common tag or set of data elements allows the complete flow of a transaction or a request
+ to be tracked. We call this <i>Fish Tagging</i>.
+ </p>
+ <p>Log4j provides two mechanisms for performing Fish Tagging; the Thread Context Map and the Thread
+ Context Stack. The Thread Context Map allows any number of items to be added and be identified
+ using key/value pairs. The Thread Context Stack allows one or more items to be pushed on the
+ Stack and then be identified by their order in the Stack or by the data itself. Since key/value
+ pairs are more flexible, the Thread Context Map is recommended when data items may be added during
+ the processing of the request or when there are more than one or two items.
+ </p>
+ <p>To uniquely stamp each request using the Thread Context Stack, the user pushes contextual information
+ on to the Stack.
+ </p>
+ <pre>
+ ThreadContext.push(UUID.randomUUID().toString()); // Add the fishtag;
+ logger.debug("Message 1");
+ .
+ .
+ .
+ logger.debug("Message 2");
+ .
+ .
+ ThreadContext.pop();</pre>
+ <p>
+ The alternative to the Thread Context Stack is the Thread Context Map. In this case, attributes
+ associated with the request being processed are adding at the beginning and removed at the end
+ as follows:
+ </p>
+ <pre>
+ ThreadContext.put("id", UUID.randomUUID().toString(); // Add the fishtag;
+ ThreadContext.put("ipAddress", request.getRemoteAddr());
+ ThreadContext.put("loginId", session.getAttribute("loginId"));
+ ThreadContext.put("hostName", request.getServerName());
+ .
+ logger.debug("Message 1");
+ .
+ .
+ logger.debug("Message 2");
+ .
+ .
+ ThreadContext.clear();</pre>
+ <p>The Stack and the Map are managed per thread and is based on
+ <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/InheritableThreadLocal.html">InheritableThreadLocal</a>.
+ Thus, in many cases the contents of the Stack and Map will be passed to child threads. However, as
+ discussed in the
+ <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/Executors.html#privilegedThreadFactory()">Executors</a>
+ class and in other cases where thread pooling is utilized, the ThreadContext may not always be
+ automatically passed to worker threads. In those cases the pooling mechanism should provide a means for
+ doing so. The getContext() and cloneStack() methods can be used to obtain copies of the Map and Stack
+ respectively.
+ </p>
+ <p>
+ Note that all methods of the
+ <a href="../log4j2-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
+ class are static.
+ </p>
+ </subsection>
+ <subsection name="Including the ThreadContext when writing logs">
+ <p>
+ The PatternLayout provides mechanisms to print the contents of the ThreadContext Map and Stack. Using
+ %X by itself will cause the full contents of the Map to be included while %X{key} will cause the value
+ of the specified key to be included. %x will include the full contents of the Stack.
+ </p>
+ </subsection>
</section>
</body>
</document>
\ No newline at end of file