| //// |
| 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. |
| //// |
| = Log4j 2 API |
| |
| == Overview |
| |
| The Log4j 2 API provides the interface that applications should code to |
| and provides the adapter components required for implementers to create |
| a logging implementation. Although Log4j 2 is broken up between an API |
| and an implementation, the primary purpose of doing so was not to allow |
| multiple implementations, although that is certainly possible, but to |
| clearly define what classes and methods are safe to use in "normal" |
| application code. |
| |
| === Hello World! |
| |
| No introduction would be complete without the customary Hello, World |
| example. Here is ours. First, a Logger with the name "HelloWorld" is |
| obtained from the |
| link:../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html[`LogManager`]. |
| Next, the logger is used to write the "Hello, World!" message, however |
| the message will be written only if the Logger is configured to allow |
| informational messages. |
| |
| [source,java] |
| ---- |
| import org.apache.logging.log4j.LogManager; |
| import org.apache.logging.log4j.Logger; |
| |
| public class HelloWorld { |
| private static final Logger logger = LogManager.getLogger("HelloWorld"); |
| public static void main(String[] args) { |
| logger.info("Hello, World!"); |
| } |
| } |
| ---- |
| |
| The output from the call to `logger.info()` will vary significantly |
| depending on the configuration used. See the |
| link:configuration.html[Configuration] section for more details. |
| |
| === Substituting Parameters |
| |
| Frequently the purpose of logging is to provide information about what |
| is happening in the system, which requires including information about |
| the objects being manipulated. In Log4j 1.x this could be accomplished |
| by doing: |
| |
| [source,java] |
| ---- |
| if (logger.isDebugEnabled()) { |
| logger.debug("Logging in user " + user.getName() + " with birthday " + user.getBirthdayCalendar()); |
| } |
| ---- |
| |
| Doing this repeatedly has the effect of making the code feel like it is |
| more about logging than the actual task at hand. In addition, it results |
| in the logging level being checked twice; once on the call to |
| isDebugEnabled and once on the debug method. A better alternative would |
| be: |
| |
| [source,java] |
| ---- |
| logger.debug("Logging in user {} with birthday {}", user.getName(), user.getBirthdayCalendar()); |
| ---- |
| |
| With the code above the logging level will only be checked once and the |
| String construction will only occur when debug logging is enabled. |
| |
| === Formatting Parameters |
| |
| Formatter Loggers leave formatting up to you if `toString()` is not what |
| you want. To facilitate formatting, you can use the same format strings |
| as Java's |
| http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax[`Formatter`]. |
| For example: |
| |
| [source,java] |
| ---- |
| public static Logger logger = LogManager.getFormatterLogger("Foo"); |
| |
| logger.debug("Logging in user %s with birthday %s", user.getName(), user.getBirthdayCalendar()); |
| logger.debug("Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar()); |
| logger.debug("Integer.MAX_VALUE = %,d", Integer.MAX_VALUE); |
| logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE); |
| ---- |
| |
| To use a formatter Logger, you must call one of the `LogManager` |
| link:../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getFormatterLogger(java.lang.Class)[`getFormatterLogger`] |
| methods. The output for this example shows that `Calendar::toString` is |
| verbose compared to custom formatting: |
| |
| [source,java] |
| ---- |
| 2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCalendar[time=?,areFieldsSet=false,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id="America/New_York",offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=America/New_York,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=1995,MONTH=4,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=23,DAY_OF_YEAR=?,DAY_OF_WEEK=?,DAY_OF_WEEK_IN_MONTH=?,AM_PM=0,HOUR=0,HOUR_OF_DAY=0,MINUTE=0,SECOND=0,MILLISECOND=?,ZONE_OFFSET=?,DST_OFFSET=?] |
| 2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995 |
| 2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647 |
| 2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807 |
| ---- |
| |
| === Mixing Loggers with Formatter Loggers |
| |
| Formatter loggers give fine-grained control over the output format, but |
| have the drawback that the correct type must be specified (for example, |
| passing anything other than a decimal integer for a %d format parameter |
| gives an exception). |
| |
| If your main usage is to use \{}-style parameters, but occasionally you |
| need fine-grained control over the output format, you can use the |
| `printf` method: |
| |
| [source,java] |
| ---- |
| public static Logger logger = LogManager.getLogger("Foo"); |
| |
| logger.debug("Opening connection to {}...", someDataSource); |
| logger.printf(Level.INFO, "Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar()); |
| ---- |
| |
| [#LambdaSupport] |
| === Java 8 lambda support for lazy logging |
| |
| In release 2.4, the `Logger` interface added support for lambda |
| expressions. This allows client code to lazily log messages without |
| explicitly checking if the requested log level is enabled. For example, |
| previously you would write: |
| |
| [source,java] |
| ---- |
| // pre-Java 8 style optimization: explicitly check the log level |
| // to make sure the expensiveOperation() method is only called if necessary |
| if (logger.isTraceEnabled()) { |
| logger.trace("Some long-running operation returned {}", expensiveOperation()); |
| } |
| ---- |
| |
| With Java 8 you can achieve the same effect with a lambda expression. |
| You no longer need to explicitly check the log level: |
| |
| [source,java] |
| ---- |
| // Java-8 style optimization: no need to explicitly check the log level: |
| // the lambda expression is not evaluated if the TRACE level is not enabled |
| logger.trace("Some long-running operation returned {}", () -> expensiveOperation()); |
| ---- |
| |
| === Logger Names |
| |
| Most logging implementations use a hierarchical scheme for matching |
| logger names with logging configuration. In this scheme, the logger name |
| hierarchy is represented by `'.'` characters in the logger name, in a |
| fashion very similar to the hierarchy used for Java package names. For |
| example, `org.apache.logging.appender` and `org.apache.logging.filter` |
| both have `org.apache.logging` as their parent. In most cases, |
| applications name their loggers by passing the current class's name to |
| `LogManager.getLogger(...)`. Because this usage is so common, Log4j 2 |
| provides that as the default when the logger name parameter is either |
| omitted or is null. For example, in all examples below the Logger will |
| have a name of `"org.apache.test.MyTest"`. |
| |
| [source,java] |
| ---- |
| package org.apache.test; |
| |
| public class MyTest { |
| private static final Logger logger = LogManager.getLogger(MyTest.class); |
| } |
| ---- |
| |
| [source,java] |
| ---- |
| package org.apache.test; |
| |
| public class MyTest { |
| private static final Logger logger = LogManager.getLogger(MyTest.class.getName()); |
| } |
| ---- |
| |
| [source,java] |
| ---- |
| package org.apache.test; |
| |
| public class MyTest { |
| private static final Logger logger = LogManager.getLogger(); |
| } |
| ---- |