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 2018/08/03 15:34:36 UTC
logging-log4j2 git commit: Add documentation
Repository: logging-log4j2
Updated Branches:
refs/heads/master cb41936b2 -> 9ecca9def
Add documentation
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/9ecca9de
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/9ecca9de
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/9ecca9de
Branch: refs/heads/master
Commit: 9ecca9defbfebf7e8b070df02d47f313eee63e1c
Parents: cb41936
Author: Ralph Goers <rg...@apache.org>
Authored: Fri Aug 3 08:33:27 2018 -0700
Committer: Ralph Goers <rg...@apache.org>
Committed: Fri Aug 3 08:33:27 2018 -0700
----------------------------------------------------------------------
src/site/asciidoc/manual/usage.adoc | 230 +++++++++++++++++++++++++++++++
src/site/site.xml | 6 +-
2 files changed, 235 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/9ecca9de/src/site/asciidoc/manual/usage.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/usage.adoc b/src/site/asciidoc/manual/usage.adoc
new file mode 100644
index 0000000..10ce8d2
--- /dev/null
+++ b/src/site/asciidoc/manual/usage.adoc
@@ -0,0 +1,230 @@
+////
+ 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
+
+ https://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.
+////
+
+= Usage
+
+[#Static_vs_Non_Static]
+== Static vs Non-Static Loggers
+As with any variable in Java, Loggers may be declared as static variables or class member variables. However,
+there are a few factors to consider when choosing to delare a logger as static vs non-static. Generally, it
+is better to declare Loggers as static.
+
+1. Instantiation of a new Logger is a fairly expensive operation when using the default ContextSelector,
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html[ClassLoaderContextSelector].
+When the Logger is created the `ClassLoaderContextSelector` will locate the ClassLoader for the Class the Logger
+is associated with and add the Logger to the LoggerContext associated with that ClassLoader.
+2. Once a Logger is created it will not be deleted until the `LoggerContext` it is associated with
+is deleted. Typically, this will only happen when the application is shut down or un-deployed. Each call
+to getLogger with the same logger name will return the same Logger instance. Thus, there is very little
+difference between a static or non-static Logger.
+3. There is no behavioral difference between a static and non-static Logger. Both will have the Logger name
+assigned when they are created, which usually will be the name of the class they are associated with. See
+the discussion below on logger names vs class names and the example for more information.
+
+== Logging the Logger name vs the Class name
+The logger name of a Logger is specified when the Logger is created. When a log method is called the
+class name value in the log event will reflect the name of the class the log method was called from, which is
+not necessarily the same as the class that created the Logger. The following example illustrations this.
+
+The base class creates a static Logger and a logger variable that is initialized as that same Logger.
+ It has two methods that perform logging, once that uses the static logger and one that uses a Logger that
+ can be overridden.
+
+
+[source]
+----
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.LogManager;
+ import org.apache.logging.log4j.Logger;
+ import org.apache.logging.log4j.Marker;
+
+ /**
+ *
+ */
+ public abstract class MySuperClass {
+
+ // The name of this Logger will be "org.apache.logging.MySuperClass"
+ protected static final Logger LOGGER = LogManager.getLogger();
+
+ private Logger logger = LOGGER;
+
+ protected Logger getLogger() {
+ return logger;
+ }
+
+ protected void setLogger(Logger logger) {
+ this.logger = logger;
+ }
+
+
+ protected void demoLog(Marker marker) {
+ logger.debug(marker,"MySuperClass log message");
+ }
+ }
+----
+
+This class extends the base class. It provides its own logger and has two methods, one that uses the
+logger in this class and one that uses the static logger from the base class.
+
+[source]
+----
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.LogManager;
+ import org.apache.logging.log4j.Logger;
+ import org.apache.logging.log4j.Marker;
+
+ /**
+ *
+ */
+ public class MyClass extends MySuperClass {
+
+ // The name of this Logge will be "org.apache.logging.MyClass"
+ public Logger logger = LogManager.getLogger();
+
+ public void log1(Marker marker) {
+ logger.debug(marker,"MyClass logger message");
+ }
+
+ public void log2(Marker marker) {
+ LOGGER.debug(marker,"MySuperClass logger message from MyClass");
+ }
+ }
+----
+
+The application exercises all the logging methods four times. The first two times the Logger in the base
+class is set to the static Logger. The second two times the Logger in the base class is set to use the
+Logger in the subclass. In the first and third invocation of each method a null Marker is passed. In the
+second and fourth a Marker named "CLASS" is passed.
+
+[source]
+----
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.Marker;
+ import org.apache.logging.log4j.MarkerManager;
+
+ public class App {
+
+ public static void main( String[] args ) {
+ Marker marker = MarkerManager.getMarker("CLASS");
+ MyClass myclass = new MyClass();
+
+ System.out.println("------- MySuperClass Logger ----------");
+ myclass.demoLog(null);
+ myclass.demoLog(marker);
+ myclass.log1(null);
+ myclass.log1(marker);
+ myclass.log2(null);
+ myclass.log2(marker);
+
+ myclass.setLogger(myclass.logger);
+
+ System.out.println("------- MySuperClass Logger set to MyClass Logger ----------");
+ myclass.demoLog(null);
+ myclass.demoLog(marker);
+ myclass.log1(null);
+ myclass.log1(marker);
+ myclass.log2(null);
+ myclass.log2(marker);
+ }
+ }
+----
+
+The configuration takes advantage of Log4j's ability to select a pattern based upon attributes of the log event.
+In this case %C, the class name pattern, is used when the CLASS Marker is present, and %c, the logger name
+is used when the CLASS marker is not present.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT">
+ <PatternLayout>
+ <MarkerPatternSelector defaultPattern="%sn. Logger name %c %msg%n">
+ <PatternMatch key="CLASS" pattern="%sn. Class name %C %msg%n"/>
+ </MarkerPatternSelector>
+ </PatternLayout>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="TRACE">
+ <AppenderRef ref="Console" />
+ </Root>
+ </Loggers>
+</Configuration>
+----
+
+The output below illustrates the difference between using the Logger name and the Class name in the pattern. All
+the odd numbered items print the name of the logger (%c) while all the even numbered items print the
+name of the class that called the logging method (%C). The numbers in the description of the outcomes in the
+following list match the corresponding numbers shown in the output.
+
+1. Logging is performed in the base class using the static logger with the Logger name pattern. The
+logger name matches the name of the base class.
+2. Logging is performed in the base class using the static logger with the Class name pattern. Although
+the method was called against the MyClass instance it is implemented in MySuperClass so that is what appears.
+3. Logging is performed in the subclass using the logger in the subclass, so the name of the
+subclass is printed as the logger name.
+4. Logging is performed in the subclass using the logger in the subclass, so the name of the subclass
+is printed since that is where the method exists.
+5. Logging is performed in the subclass with the static logger of the base class. Thus the name
+of the base class Logger is printed.</li>
+6. Logging is performed in the subclass with the static logger of the base class, so the name
+of the subclass is printed since that is where the method performing the logging exists.
+7. Logging is performed in the base class using the logger of the subclass. The logger name matches the name of the
+subclass and so is printed.
+8. Logging is performed in the base class using the logger of the subclass. Although the method was called against
+the MyClass instance it is implemented in MySuperClass so that is what appears as the class name.
+9. Logging is performed in the subclass using the logger in the subclass, so the name of the
+subclass is printed as the logger name.
+10. Logging is performed in the subclass using the logger in the subclass, so the name of the subclass
+is printed since that is where the method exists.</li>
+11. Logging is performed in the subclass with the logger of the base class. Thus the name of the base class Logger is
+printed.
+12. Logging is performed in the subclass with the static logger of the base class, so the name
+of the subclass is printed since that is where the method performing the logging exists.
+
+[source]
+----
+ ------- MySuperClass Logger ----------
+ 1. Logger name org.apache.logging.MySuperClass MySuperClass log message
+ 2. Class name org.apache.logging.MySuperClass MySuperClass log message
+ 3. Logger name org.apache.logging.MyClass MyClass logger message
+ 4. Class name org.apache.logging.MyClass MyClass logger message
+ 5. Logger name org.apache.logging.MySuperClass MySuperClass logger message from MyClass
+ 6. Class name org.apache.logging.MyClass MySuperClass logger message from MyClass
+ ------- MySuperClass Logger set to MyClass Logger ----------
+ 7. Logger name org.apache.logging.MyClass MySuperClass log message
+ 8. Class name org.apache.logging.MySuperClass MySuperClass log message
+ 9. Logger name org.apache.logging.MyClass MyClass logger message
+ 10. Class name org.apache.logging.MyClass MyClass logger message
+ 11. Logger name org.apache.logging.MySuperClass MySuperClass logger message from MyClass
+ 12. Class name org.apache.logging.MyClass MySuperClass logger message from MyClass
+----
+
+In the example above there are two Loggers declared. One is static and one is non-static. When looking at
+the results it is clear that the outcomes would be exactly the same regardless of whether how the loggers
+are declared. The name of the logger will always originate from the class in which it is created and the
+Class name in each log event will always reflect the Class from which the logging method was called.
+
+It should be noted that there is a substantial performance penalty for printing the location information
+(class name, method name, and line number). If the method name and line number are not important it is
+usually better to make sure that each class has its own Logger so the logger name accurately reflects the
+class performing the logging.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/9ecca9de/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 66841fa..173ed53 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -108,6 +108,11 @@
<item name="System Properties" href="/manual/configuration.html#SystemProperties"/>
</item>
+ <item name="Usage" href="/manual/usage.html" collapse="true">
+ <item name="Static vs non-Static Loggers"/>
+ <item name="Logger Name vs Class Name"/>
+ </item>
+
<item name="Web Applications and JSPs" href="/manual/webapp.html" collapse="true">
<item name="Servlet 3.0 and Newer" href="/manual/webapp.html#Servlet-3.0" />
<item name="Servlet 2.5" href="/manual/webapp.html#Servlet-2.5" />
@@ -293,7 +298,6 @@
</menu>
<menu name="Project Information" img="icon-info-sign">
- <item name="Dependencies" href="/dependencies.html" />
<item name="Dependency Convergence" href="/dependency-convergence.html" />
<item name="Dependency Management" href="/dependency-management.html" />
<item name="Project Team" href="/team-list.html" />