Prepare for release 2.6.1
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/278f2087 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/278f2087 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/278f2087 Branch: refs/heads/LOG4J-1181 Commit: 278f2087d25b60bdf6ef7821a67f5a8bbefd4a3d Parents: 4e71e5a Author: rgoers <[email protected]> Authored: Sun Jun 5 17:09:45 2016 -0700 Committer: rgoers <[email protected]> Committed: Sun Jun 5 17:09:45 2016 -0700 ---------------------------------------------------------------------- RELEASE-NOTES.txt | 160 +++++++------------------------ pom.xml | 4 +- src/changes/announcement.vm | 20 +++- src/site/resources/images/logo.png | Bin 0 -> 41622 bytes src/site/resources/logo/logo.jpg | Bin 0 -> 14818 bytes src/site/site.vm | 8 +- src/site/xdoc/index.xml | 142 --------------------------- src/site/xdoc/index.xml.vm | 164 ++++++++++++++++++++++++++++++++ 8 files changed, 223 insertions(+), 275 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/RELEASE-NOTES.txt ---------------------------------------------------------------------- diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt index 336bfdf..f5e7295 100644 --- a/RELEASE-NOTES.txt +++ b/RELEASE-NOTES.txt @@ -1,143 +1,57 @@ - Apache Log4j 2.6 RELEASE NOTES + Apache Log4j 2.6.1 RELEASE NOTES -The Apache Log4j 2 team is pleased to announce the Log4j 2.6 release! +The Apache Log4j 2 team is pleased to announce the Log4j 2.6.1 release! Apache log4j is a well known framework for logging application behavior. Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j 1.x, and provides many other modern features such as support for Markers, property substitution using Lookups, multiple patterns on a PatternLayout and asynchronous Loggers. In addition, Log4j 2 will not lose events while reconfiguring. -This is the tenth GA release. It contains several bugfixes and new features. The new features include -the ability to be "garbage-free" (avoid allocating temporary objects) while logging if certain conditions are met, -a new YAML Layout, the ability to merge configuration files, and documenting Log4j's performance against other logging -frameworks and in various logging configurations. More details on the features and bugfixes are itemized below. +This is the eleventh GA release. It is primarily a bugfix release. More details on the fixes are itemized below. -GA Release 2.6 +Note that subsequent to the 2.6 release a minor source incompatibility was found due to the addition of new methods to +the Logger interface. If you have code that does: + +logger.error(null, âThis is the log messageâ, throwable); + +or similar with any log level you will get a compiler error saying the reference is ambiguous. To correct this either do: + +logger.error(âThis is the log messageâ, throwable); + +or + +logger.error((Marker) null, âThis is the log messageâ, throwable); + +Log4j 2.6 maintains binary compatibility with previous releases. + +GA Release 2.6.1 Changes in this version include: New features: -o LOG4J2-1270: (GC) Added support for garbage-free logging in steady state. - This includes Async Loggers and logging synchronously to the console and to a file, - but does not include the AsyncAppender. This release makes the GelfLayout and - the main patterns in the PatternLayout garbage-free. -o LOG4J2-1297: (GC) Added manual page on garbage-free logging. -o LOG4J2-1373: (GC) Update Logger wrapper Generator tool to generate methods for the new Logger methods. -o LOG4J2-1326: (GC) Added methods to the Logger interface for logging CharSequence messages. -o LOG4J2-1344: (GC) FileAppender, RollingFileAppender and MemoryMappedFileAppender are now also garbage-free by default. -o LOG4J2-1278: (GC) Added unrolled varargs methods to Logger API, added Unbox utility to avoid auto-boxing when logging primitive values. -o LOG4J2-1271: (GC) Add MessageFactory that avoid allocation by reusing a cached ParameterizedMessage instance. -o LOG4J2-1293: (GC) Add interface StringBuilderFormattable to enable converting Messages and parameters to text without allocating temporary objects. - ParameterizedMessage, ObjectMessage, SimpleMessage and ThreadDumpMessage now implement StringBuilderFormattable. -o LOG4J2-1274: (GC) Add encode(LogEvent, ByteBufferDestination) method to Layout API to enable converting LogEvents to bytes without creating temporary objects. -o LOG4J2-1362: Added a YAML layout. Thanks to Gary Gregory. -o LOG4J2-1179: Documented benchmark results comparing Log4j 2 performance to other logging libraries. -o LOG4J2-1011: Document dependencies for layouts. -o LOG4J2-621: Pattern to drop first N package parts. Thanks to Lee Theobald, Kamal Mettananda, Gary Gregory. -o LOG4J2-494: Support merging configurations to for a composite configuration. Thanks to Philipp Knobel. -o LOG4J2-1357: Option to not log stack traces for logged Throwables in GelfLayout. -o LOG4J2-1348: Add an AutoCloseable ThreadContext class: CloseableThreadContext. Thanks to Greg Thomas, Gary Gregory. -o LOG4J2-1299: Add pattern converter for thread id and priority in PatternLayout. -o LOG4J2-124: Add shutdown methods to LogManager. -o LOG4J2-1221: Added async logger Timeout wait strategy and made this the default wait strategy for async loggers. - This prevents a rare deadlock that may occur on Solaris. Thanks to Michael Barker. -o LOG4J2-1080: Added option to discard events below a certain log level if the async logger ring buffer - or async appender queue is full. -o LOG4J2-1237: Make PatternLayout header and footer accept a pattern. Thanks to Mike Calmus, Gary Gregory. -o LOG4J2-1244: Make header and footer values customizable in JSONLayout. Thanks to Anshu Garg, Remko Popma, Gary Gregory. -o LOG4J2-1245: Make CSV Layout header and footers accept patterns. -o LOG4J2-1192: Dynamic Subject for SMTP Appender. Thanks to Jörg Bretschneider, Gary Gregory. -o LOG4J2-1277: FormattedMessage, MessageFormatMessage and StringFormattedMessage should support passing in a Locale to ensure appropriate formatting. Thanks to Gary Gregory, Ludovic Hochet. -o LOG4J2-1303: Add documentation links to runtime dependencies in each component intro page. -o LOG4J2-1252: JeroMqAppender should support layouts. -o LOG4J2-1217: PatternLayout option to limit length of text. Thanks to Thies Wellpott. -o LOG4J2-1133: Add JNDI lookup documentation. -o LOG4J2-1169: PatternLayout: Possible variable substitution in equals substitution parameter. Thanks to Gerald Kritzinger. +o LOG4J2-1411: Add documentation about plugin builders compared to factories. Fixed Bugs: -o LOG4J2-1281: (GC) LoggerConfig.getProperties() should not allocate on each call. -o LOG4J2-1269: (GC) AsyncLogger should use thread-local translator by default. -o LOG4J2-623: Generate MDC properties as a JSON map in JSONLayout, with option to output as list of map entries. -o LOG4J2-1387: Fixed memory leak related to shutdown hook. -o LOG4J2-1382: Copying a MutableLogEvent using Log4jLogEvent.Builder should not unnecessarily obtain caller location information. -o LOG4J2-1372: XMLLayout indents, but not the first child tag (Event). Thanks to Kamal Mettananda, Gary Gregory. -o LOG4J2-1363: Properties Configuration did not support includeLocation attribute on Loggers. -o LOG4J2-1263: The ConfigurationSource was not saved for BuiltConfigurations so monitor interval had no effect. -o LOG4J2-1369: "xz" compression results in plaintext, uncompressed files. Thanks to Alex Birch, Gary Gregory. -o LOG4J2-1368: (Log4j-internal) StatusLogger dropped exceptions when logging parameterized messages. -o LOG4J2-1336: LoggerFactory in 1.2 API module is not compatible with 1.2. Thanks to Zbynek Vyskovsky. -o LOG4J2-1354: No configuration reload is triggered under Windows when replacing the configuration file with one that has older last modified date. Thanks to Arkadiusz Adolph. -o LOG4J2-1346: Exception from Log4jServletContextListener prevents jetty-maven-plugin run-forked. -o LOG4J2-1339: (Perf) AsyncLogger performance optimization: avoid calling instanceof TimestampMessage in hot path. -o LOG4J2-1324: Improve error handling in the Async Logger background thread: the new default exception handler no longer rethrows the error. -o LOG4J2-1309: Configuration file error does not show cause exception. -o LOG4J2-1289: Change flow logging text from "entry' to "Enter" and "exit" to "Exit". -o LOG4J2-1284: Made default MessageFactory configurable. -o LOG4J2-1280: Deprecate org.apache.logging.log4j.util.MessageSupplier. -o LOG4J2-1280: Logger methods taking Supplier parameters now correctly handle cases where the supplied value is a Message. -o LOG4J2-1268: FixedDateFormat was incorrect for formats having MMM with the French locale. -o LOG4J2-1222: Creation of a LoggerContext will fail if shutdown is in progress. LogManager will default to SimpleLogger instead. -o LOG4J2-1260: TlsSyslogFrame calculates message length incorrectly. Thanks to Blake Day, Gary Gregory. -o LOG4J2-1258: Async DynamicThresholdFilter does not use the log event's context map. Thanks to Francis Lalonde. -o LOG4J2-1232: Incorrect log rotation in last week of year. Thanks to Nikolai. -o LOG4J2-1248: Fixed broken nanotime in pattern layout. -o LOG4J2-908: JSONLayout doesn't add a comma between log events. Thanks to Konstantinos Liakos, Patrick Flaherty, Robin Coe, Gary Gregory. -o LOG4J2-1230: Don't concatenate SYSLOG Messages. Thanks to Vladimir Hudec, Ralph Goers, Gary Gregory. -o LOG4J2-1238: org.apache.logging.log4j.core.net.TcpSocketManager and other classes does not report internal exceptions to the status logger. -o LOG4J2-1212: Fix documentation to specify the correct default wait strategy used by async loggers. -o LOG4J2-1215: Documentation/XSD inconsistencies. Thanks to Erik Kemperman. -o LOG4J2-1276: LoggerMessageSupplierTest and LoggerSupplierTest are Locale sensitive. Thanks to Ludovic Hochet. -o LOG4J2-1251: Fix JUL bridge issue where LogRecord.getParameters() is used when null. Thanks to Romain Manni-Bucau. -o LOG4J2-1254: Fix typo in Flow Tracing documentation. Thanks to Josh Trow. -o LOG4J2-920: ClassNotFoundException for BundleContextSelector when initialising in an OSGi environment. Thanks to Ludovic Hochet. -o LOG4J2-1275: Fix RollingAppenderNoUnconditionalDeleteTest repeat test runs from failing. Thanks to Ludovic Hochet. -o LOG4J2-1262: Stop throwing unnecessary exception in Log4jServletContextListener.contextDestroyed(). -o LOG4J2-1227: NullPointerException in MapLookup.lookup if the event is null. Thanks to Olivier Lemasle. -o LOG4J2-1050: Add a Log4jLookup class to help write log files relative to log4j2.xml. Thanks to Adam Retter. -o LOG4J2-1310: JndiLookup mindlessly casts to String and should use String.valueOf(). -o LOG4J2-248: Log4jWebInitializerImpl: Use Thread instead of Class for fallback classloader. -o LOG4J2-1330: Fix NoClassDefFoundError in ReflectionUtil on Google App Engine. +o LOG4J2-1405: OnStartupTriggeringPolicy was forcing a rollover of empty files at startup and would append a + second footer that was added by the prior shutdown. +o LOG4J2-1406: Fixed bug in ReusableParameterizedMessage where Throwable was never updated so first error was logged over + and over again and subsequent errors were not logged. Thanks to Trask Stalnaker. +o LOG4J2-1409: Fixed ArrayIndexOutOfBoundsException that may occur in ReusableParameterizedMessage. Thanks to Shahan. +o LOG4J2-997: Add filter and remove filter were not working properly in AbstractFilterable. Thanks to Maytee Chinavanichkit. +o LOG4J2-1032: Change RenameAction to use java.nio to better report rename failures. +o LOG4J2-1407: Misleading WARN log events from Log4j about message factories and unexpected formatting. Thanks to Gary Gregory. +o LOG4J2-1408: The module log4j-liquibase is missing from BOM POM. Thanks to Gary Gregory. +o LOG4J2-1180: Logger cache does not account for message factory. Thanks to Gary Gregory. +o LOG4J2-1402: Fix regression in properties configuration to support arbitrary component ids. Changes: -o LOG4J2-1356: (GC) GelfLayout does now support garabage-free logging (with compressionType=OFF). -o LOG4J2-1343: (GC) ConsoleAppender is now garbage-free by default. This logic is reusable for all AbstractOutputStreamAppender subclasses. -o LOG4J2-1318: (GC) Avoid allocating unnecessary temporary objects in LoggerContext's getLogger methods. -o LOG4J2-1333: (GC) Avoid allocating unnecessary temporary objects in MarkerManager's getMarker methods. -o LOG4J2-1321: (GC) Avoid allocating unnecessary temporary objects in PatternLayout's NamePatternConverter and ClassNamePatternConverter. -o LOG4J2-1271: (GC) ParameterizedMessage optimizations to avoid or at least postpone allocating temporary objects. -o LOG4J2-1283: (GC) Provide ThreadLocal-based gc-free caching mechanism in DatePatternConverter for non-webapps. -o LOG4J2-1291: (GC) Update PatternLayout to utilize gc-free mechanism for LogEvent processing. -o LOG4J2-1292: (GC) Update RandomAccessFileAppender and RollingRandomAccessFileAppender to utilize gc-free Layout.encode() method. -o LOG4J2-1272: (GC) Improve LoggerConfig's data structure for AppenderControl objects to avoid allocating temporary objects during - traversal for each log event. -o LOG4J2-1375: Update SLF4J from 1.7.13 to 1.7.21. -o LOG4J2-1374: Migrate tests from Logback 1.1.3 to 1.1.7. -o LOG4J2-1384: Update Apache Commons CSV from 1.2 to 1.3. -o LOG4J2-1365: (Log4j-internal) Provide message text as CharSequence for some message types to optimize some layouts. -o LOG4J2-1345: (Doc) Clarify documentation for properties that control Log4j behaviour. -o LOG4J2-1255: Add enhanced entry and exit methods. -o LOG4J2-1380: Update Jackson from 2.7.3 to 2.7.4. -o LOG4J2-1304: Update Jackson from 2.7.0 to 2.7.2. -o LOG4J2-1253: Update LMAX Disruptor from 3.3.2 to 3.3.4. -o LOG4J2-1219: Update SLF4J from 1.7.12 to 1.7.13. -o LOG4J2-1239: Update Jackson from 2.6.3 to 2.6.4. -o LOG4J2-1249: Update Jackson from 2.6.4 to 2.7.0. -o LOG4J2-1351: Update Jackson from 2.7.2 to 2.7.3. -o LOG4J2-1240: Update Liquibase from 3.3.5 to 3.4.2. -o LOG4J2-1294: Update Kafka client from 0.9.0.0 to 0.9.0.1. -o LOG4J2-1352: Update javax.mail from 1.5.4 to 1.5.5. -o LOG4J2-1358: Update Apache Commons Compress from 1.10 to 1.11. -o LOG4J2-1388: Update Google java-allocation-instrumenter from 3.0 to 3.0.1. -o LOG4J2-1233: Misleading Value In Properties Example. Thanks to Bahri Gencsoy. -o LOG4J2-1300: Remove serializability from classes that don't need it. -o LOG4J2-1306: JeroMqAppender should use ShutdownCallbackRegistry instead of runtime hooks. -o LOG4J2-1308: Remove need to pre-specify appender et al. identifiers in property file config format. -o LOG4J2-1206: org.apache.logging.log4j.core.LoggerContext#updateLoggers should call firePropertyChangeEvent. -o LOG4J2-1322: Update Log4j 1.x migration guide to include information about system property lookup syntax changes. - - -Apache Log4j 2.6 requires a minimum of Java 7 to build and run. Log4j 2.3 was the last release that +o LOG4J2-1385: (GC) CSV layouts should not create a new CSVPrinter for each log event. Requires Apache Commons CSV 1.4. +o LOG4J2-1398: Update liquibase-core from 3.4.2 to 3.5.1. +o LOG4J2-1399: Update Apache Commons CSV from 1.3 to 1.4. + + +Apache Log4j 2.6.1 requires a minimum of Java 7 to build and run. Log4j 2.3 was the last release that supported Java 6. Basic compatibility with Log4j 1.x is provided through the log4j-1.2-api component, however it does not implement some of the http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 552a330..b8a45cd 100644 --- a/pom.xml +++ b/pom.xml @@ -182,8 +182,8 @@ <properties> <!-- make sure to update these for each release! --> <log4jParentDir>${basedir}</log4jParentDir> - <Log4jReleaseVersion>2.6</Log4jReleaseVersion> - <Log4jReleaseCount>tenth</Log4jReleaseCount> + <Log4jReleaseVersion>2.6.1</Log4jReleaseVersion> + <Log4jReleaseCount>eleventh</Log4jReleaseCount> <Log4jReleaseManager>Ralph Goers</Log4jReleaseManager> <Log4jReleaseKey>B3D8E1BA</Log4jReleaseKey> <!-- <Log4jReleaseManager>Matt Sicker</Log4jReleaseManager> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/changes/announcement.vm ---------------------------------------------------------------------- diff --git a/src/changes/announcement.vm b/src/changes/announcement.vm index 07544e5..84e50c9 100644 --- a/src/changes/announcement.vm +++ b/src/changes/announcement.vm @@ -26,10 +26,22 @@ Log4j that provides significant improvements over its predecessor, Log4j 1.x, an many other modern features such as support for Markers, property substitution using Lookups, multiple patterns on a PatternLayout and asynchronous Loggers. In addition, Log4j 2 will not lose events while reconfiguring. -This is the ${relCount} GA release. It contains several bugfixes and new features. The new features include -the ability to be "garbage-free" (avoid allocating temporary objects) while logging if certain conditions are met, -a new YAML Layout, the ability to merge configuration files, and documenting Log4j's performance against other logging -frameworks and in various logging configurations. More details on the features and bugfixes are itemized below. +This is the ${relCount} GA release. It is primarily a bugfix release. More details on the fixes are itemized below. + +Note that subsequent to the 2.6 release a minor source incompatibility was found due to the addition of new methods to +the Logger interface. If you have code that does: + +logger.error(null, âThis is the log messageâ, throwable); + +or similar with any log level you will get a compiler error saying the reference is ambiguous. To correct this either do: + +logger.error(âThis is the log messageâ, throwable); + +or + +logger.error((Marker) null, âThis is the log messageâ, throwable); + +Log4j 2.6 maintains binary compatibility with previous releases. ## Hack to improve layout: replace all pairs of spaces with a single new-line $release.description.replaceAll(" ", " http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/site/resources/images/logo.png ---------------------------------------------------------------------- diff --git a/src/site/resources/images/logo.png b/src/site/resources/images/logo.png new file mode 100644 index 0000000..7c30e4c Binary files /dev/null and b/src/site/resources/images/logo.png differ http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/site/resources/logo/logo.jpg ---------------------------------------------------------------------- diff --git a/src/site/resources/logo/logo.jpg b/src/site/resources/logo/logo.jpg new file mode 100644 index 0000000..ca9b019 Binary files /dev/null and b/src/site/resources/logo/logo.jpg differ http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/site/site.vm ---------------------------------------------------------------------- diff --git a/src/site/site.vm b/src/site/site.vm index 8148b8e..a5659ac 100644 --- a/src/site/site.vm +++ b/src/site/site.vm @@ -200,9 +200,9 @@ #if ($thisProjectDir == $PathTool.getDirectoryComponent( $item.href )) #set ($active = " active") #end - #if (${project.artifactId} != "log4j" && $isComponentDocumentation && - ($item.href == "team-list.html" || $item.href == "mail-lists.html" - || $item.href == "issue-tracking.html" || $item.href == "license.html" + #if (${project.artifactId} != "log4j" && $isComponentDocumentation && + ($item.href == "team-list.html" || $item.href == "mail-lists.html" + || $item.href == "issue-tracking.html" || $item.href == "license.html" || $item.href == "source-repository.html")) <!-- Removing overall project item $item.name from component-specific menu --> #else @@ -474,7 +474,7 @@ <a href="https://logging.apache.org/";> <img class="logo-left" src="$relativePath/images/ls-logo.jpg" alt="Apache logging services logo" /> </a> - <img class="logo-right" src="$relativePath/images/logo.jpg" alt="Apache log4j logo" /> + <img class="logo-right" src="$relativePath/images/logo.png" alt="Apache log4j logo" /> <div class="clear"></div> <div class="navbar"> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/site/xdoc/index.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml deleted file mode 100644 index cb5fb34..0000000 --- a/src/site/xdoc/index.xml +++ /dev/null @@ -1,142 +0,0 @@ -<?xml version="1.0"?> -<!-- - 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. ---> - -<document xmlns="http://maven.apache.org/XDOC/2.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd";> - <properties> - <title>Log4j 2 Guide</title> - <author email="[email protected]">Ralph Goers</author> - <author email="[email protected]">Gary Gregory</author> - <author email="[email protected]">Scott Deboy</author> - </properties> - - <body> - <section name="Apache Log4j 2"> - - <p> - Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j - 1.x, and provides many of the improvements available in Logback while fixing some inherent problems in - Logback's architecture. - </p> - - <p>Some of the features and improvements in Log4j 2 are:</p> - - <dl> - <dt>API Separation</dt> - <dd> - The API for Log4j is separate from the implementation making it clear for application developers - which classes and methods they can use while ensuring forward compatibility. This allows the - Log4j team to improve the implementation safely and in a compatible manner. - </dd> - <dt>Improved Performance</dt> - <dd> - Log4j 2 contains next-generation Asynchronous Loggers based - on the LMAX Disruptor library. In multi-threaded scenarios - Asynchronous Loggers have 18 times higher throughput and - orders of magnitude lower latency than Log4j 1.x and Logback. - See <a href="manual/async.html#Performance">Asynchronous Logging Performance</a> - for details. - Otherwise, Log4j 2 significantly outperforms Log4j 1.x, Logback and java.util.logging, - especially in multi-threaded applications. - See <a href="performance.html">Performance</a> for more information. - </dd> - <dt>Support for multiple APIs</dt> - <dd> - While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the - Log4j 1.2, SLF4J, Commons Logging and java.util.logging (JUL) APIs. - </dd> - <dt>Avoid lock-in</dt> - <dd> - Applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant - library as their logger implementation with the log4j-to-slf4j adapter. - </dd> - <dt>Automatic Reloading of Configurations</dt> - <dd> - Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, - it will do so without losing log events while reconfiguration is taking place. - </dd> - <dt>Advanced Filtering</dt> - <dd> - Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, - and other components in the Log event. Filtering can be specified to apply to all events - before being passed to Loggers or as they pass through Appenders. In addition, filters can also - be associated with Loggers. Unlike Logback, you can use a common Filter class in any of these - circumstances. - </dd> - <dt>Plugin Architecture</dt> - <dd> - Log4j uses the plugin pattern to configure components. As such, you do not need to write code - to create and configure an Appender, Layout, Pattern Converter, and so on. Log4j automatically - recognizes plugins and uses them when a configuration references them. - </dd> - <dt>Property Support</dt> - <dd> - You can reference properties in a configuration, Log4j will directly replace them, or Log4j will - pass them to an underlying component that will dynamically resolve them. Properties come from values - defined in the configuration file, system properties, environment variables, the ThreadContext - Map, and data present in the event. Users can further customize the property providers by - adding their own <a href="manual/lookups.html">Lookup</a> Plugin. - </dd> - <dt>Java 8 Lambda Support</dt> - <dd> - Previously, if a log message was expensive to construct, you would often explicitly check if the - requested log level is enabled before constructing the message. - Client code running on Java 8 can benefit from Log4j's <a href="manual/api.html#LambdaSupport">lambda - support</a>. Since Log4j will not evaluate a lambda - expression if the requested log level is not enabled, the same effect can be achieved with less code. - </dd> - <dt>Custom Log Levels</dt> - <dd> - In Log4j 2, <a href="manual/customloglevels.html">custom log levels</a> can easily be defined in code - or in configuration. No subclassing is required. - </dd> - <dt>Garbage-free</dt> - <dd> - During steady state logging, Log4j 2 is <a href="manual/garbagefree.html">garbage-free</a> - in stand-alone applications, and low garbage in web applications. - This reduces pressure on the garbage collector and can give better response time performance. - </dd> - </dl> - - <subsection name="Documentation"> - <p> - The Log4j 2 User's Guide is available on this <a href="manual/index.html">site</a> or as a downloadable - <a href="log4j-users-guide.pdf">PDF</a>. - </p> - </subsection> - - <subsection name="Requirements"> - <p> - Log4j 2.4 and greater requires Java 7, versions 2.0-alpha1 to 2.3 required Java 6. - Some features require optional dependencies; the documentation for these features specifies the - dependencies. - </p> - </subsection> - - <subsection name="News"> - <p> - Log4j 2 is now available for production. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter - is available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for - Apache Commons Logging and SLF4J. - </p> - </subsection> - </section> - </body> -</document> - http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/278f2087/src/site/xdoc/index.xml.vm ---------------------------------------------------------------------- diff --git a/src/site/xdoc/index.xml.vm b/src/site/xdoc/index.xml.vm new file mode 100644 index 0000000..6d7f824 --- /dev/null +++ b/src/site/xdoc/index.xml.vm @@ -0,0 +1,164 @@ +<?xml version="1.0"?> +<!-- + 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. +--> + +<document xmlns="http://maven.apache.org/XDOC/2.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd";> + <properties> + <title>Log4j 2 Guide</title> + <author email="[email protected]">Ralph Goers</author> + <author email="[email protected]">Gary Gregory</author> + <author email="[email protected]">Scott Deboy</author> + </properties> + + <body> + <section name="Apache Log4j 2"> + + <p> + Apache Log4j 2 is an upgrade to Log4j that provides significant improvements over its predecessor, Log4j + 1.x, and provides many of the improvements available in Logback while fixing some inherent problems in + Logback's architecture. + </p> + + <p>Some of the features and improvements in Log4j 2 are:</p> + + <dl> + <dt>API Separation</dt> + <dd> + The API for Log4j is separate from the implementation making it clear for application developers + which classes and methods they can use while ensuring forward compatibility. This allows the + Log4j team to improve the implementation safely and in a compatible manner. + </dd> + <dt>Improved Performance</dt> + <dd> + Log4j 2 contains next-generation Asynchronous Loggers based + on the LMAX Disruptor library. In multi-threaded scenarios + Asynchronous Loggers have 18 times higher throughput and + orders of magnitude lower latency than Log4j 1.x and Logback. + See <a href="manual/async.html#Performance">Asynchronous Logging Performance</a> + for details. + Otherwise, Log4j 2 significantly outperforms Log4j 1.x, Logback and java.util.logging, + especially in multi-threaded applications. + See <a href="performance.html">Performance</a> for more information. + </dd> + <dt>Support for multiple APIs</dt> + <dd> + While the Log4j 2 API will provide the best performance, Log4j 2 provides support for the + Log4j 1.2, SLF4J, Commons Logging and java.util.logging (JUL) APIs. + </dd> + <dt>Avoid lock-in</dt> + <dd> + Applications coded to the Log4j 2 API always have the option to use any SLF4J-compliant + library as their logger implementation with the log4j-to-slf4j adapter. + </dd> + <dt>Automatic Reloading of Configurations</dt> + <dd> + Like Logback, Log4j 2 can automatically reload its configuration upon modification. Unlike Logback, + it will do so without losing log events while reconfiguration is taking place. + </dd> + <dt>Advanced Filtering</dt> + <dd> + Like Logback, Log4j 2 supports filtering based on context data, markers, regular expressions, + and other components in the Log event. Filtering can be specified to apply to all events + before being passed to Loggers or as they pass through Appenders. In addition, filters can also + be associated with Loggers. Unlike Logback, you can use a common Filter class in any of these + circumstances. + </dd> + <dt>Plugin Architecture</dt> + <dd> + Log4j uses the plugin pattern to configure components. As such, you do not need to write code + to create and configure an Appender, Layout, Pattern Converter, and so on. Log4j automatically + recognizes plugins and uses them when a configuration references them. + </dd> + <dt>Property Support</dt> + <dd> + You can reference properties in a configuration, Log4j will directly replace them, or Log4j will + pass them to an underlying component that will dynamically resolve them. Properties come from values + defined in the configuration file, system properties, environment variables, the ThreadContext + Map, and data present in the event. Users can further customize the property providers by + adding their own <a href="manual/lookups.html">Lookup</a> Plugin. + </dd> + <dt>Java 8 Lambda Support</dt> + <dd> + Previously, if a log message was expensive to construct, you would often explicitly check if the + requested log level is enabled before constructing the message. + Client code running on Java 8 can benefit from Log4j's <a href="manual/api.html#LambdaSupport">lambda + support</a>. Since Log4j will not evaluate a lambda + expression if the requested log level is not enabled, the same effect can be achieved with less code. + </dd> + <dt>Custom Log Levels</dt> + <dd> + In Log4j 2, <a href="manual/customloglevels.html">custom log levels</a> can easily be defined in code + or in configuration. No subclassing is required. + </dd> + <dt>Garbage-free</dt> + <dd> + During steady state logging, Log4j 2 is <a href="manual/garbagefree.html">garbage-free</a> + in stand-alone applications, and low garbage in web applications. + This reduces pressure on the garbage collector and can give better response time performance. + </dd> + </dl> + + <subsection name="Documentation"> + <p> + The Log4j 2 User's Guide is available on this <a href="manual/index.html">site</a> or as a downloadable + <a href="log4j-users-guide.pdf">PDF</a>. + </p> + </subsection> + + <subsection name="Requirements"> + <p> + Log4j 2.4 and greater requires Java 7, versions 2.0-alpha1 to 2.3 required Java 6. + Some features require optional dependencies; the documentation for these features specifies the + dependencies. + </p> + </subsection> + + <subsection name="News"> + <p> + Log4j ${Log4jReleaseVersion} is now available for production. The API for Log4j 2 is not compatible with Log4j 1.x, however an adapter + is available to allow applications to continue to use the Log4j 1.x API. Adapters are also available for + Apache Commons Logging and SLF4J. + </p> + <p> + Log4j ${Log4jReleaseVersion} is the latest release of Log4j and contains several bug fixes that were + found after the release of Log4j 2.6. The list of fixes can be found in the latest + <a href="changes-report.html#a2.6.1">changes report</a>. + </p> + <p> + Note that subsequent to the release of Log4j 2.6 a minor source incompatibility with prior releass was + found due to the addition of new methods to the Logger interface. If you have code that does:</p> + <pre> + logger.error(null, "This is the log message", throwable); + </pre> + <p> + or similar with any log level you will get a compiler error saying the reference is ambiguous. To correct this either do:</p> + <pre> + logger.error("This is the log message", throwable); + </pre> + <p>or</p> + <pre> + logger.error((Marker) null, "This is the log message", throwable); + </pre> + <p>Log4j ${Log4jReleaseVersion} maintains binary compatibility with previous releases.</p> + + </subsection> + </section> + </body> +</document> +
