Repository: logging-log4j2 Updated Branches: refs/heads/master 54ee74c6d -> d29dea42b
Normalize use of markdown headers This backports the velocity variables used for markdown headers from the release notes template which would otherwise be special syntax in velocity. Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/d29dea42 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/d29dea42 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/d29dea42 Branch: refs/heads/master Commit: d29dea42bf02f2d8e7fcb277f860553b33d4e667 Parents: 54ee74c Author: Matt Sicker <boa...@gmail.com> Authored: Sun Jan 29 11:46:21 2017 -0600 Committer: Matt Sicker <boa...@gmail.com> Committed: Sun Jan 29 11:46:21 2017 -0600 ---------------------------------------------------------------------- src/site/markdown/build.md | 6 ++---- src/site/markdown/download.md.vm | 14 +++++--------- src/site/markdown/faq.md.vm | 36 ++++++++++++++++++----------------- src/site/markdown/index.md.vm | 35 ++++++++++++++++++---------------- 4 files changed, 45 insertions(+), 46 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/d29dea42/src/site/markdown/build.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/build.md b/src/site/markdown/build.md index b4e91b5..fa1e27a 100644 --- a/src/site/markdown/build.md +++ b/src/site/markdown/build.md @@ -16,8 +16,7 @@ limitations under the License. --> -Building and Installing Log4j -============================= +# Building and Installing Log4j *The information below is for developers who want to modify Log4j or contribute to Log4j. If your goal is to add logging to your application you don't need to @@ -53,7 +52,6 @@ To rebuild only what's changed and execute the tests, run: `mvn test` To rebuild from scratch, add "clean", for example: `mvn clean test` -Releasing Log4j ---------------- +## Releasing Log4j Please see the wiki [Log4j2ReleaseGuide](https://wiki.apache.org/logging/Log4j2ReleaseGuide). http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/d29dea42/src/site/markdown/download.md.vm ---------------------------------------------------------------------- diff --git a/src/site/markdown/download.md.vm b/src/site/markdown/download.md.vm index 0332bb2..3ed0fe6 100644 --- a/src/site/markdown/download.md.vm +++ b/src/site/markdown/download.md.vm @@ -15,12 +15,10 @@ See the License for the specific language governing permissions and limitations under the License. --> -<!-- -Do note that since this is also a Velocity template, normal # headings do not work properly. Use the =/- versions. ---> +#set($h1='#') +#set($h2='##') -Download Apache Log4j 2 -======================= +$h1 Download Apache Log4j 2 Apache Log4j 2 is distributed under the [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). @@ -65,8 +63,7 @@ Apache Log4j ${Log4jReleaseVersion} is signed by ${Log4jReleaseManager} (${Log4j Alternatively, you can verify the MD5 signature on the files. A unix program called md5 or md5sum is included in many unix distributions. -Previous Releases ------------------ +$h2 Previous Releases Log4j 2.3 was the last 2.x release to support Java 6. Those artifacts can be found at: @@ -93,8 +90,7 @@ Log4j 2.3 was the last 2.x release to support Java 6. Those artifacts can be fou All previous releases of Apache log4j can be found in the [archive repository](https://archive.apache.org/dist/logging/log4j/). -Using Log4j on your classpath ------------------------------ +$h2 Using Log4j on your classpath To use Log4j 2 in your application make sure that both the API and Core jars are in the application's classpath. Add the dependencies listed below to your classpath. http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/d29dea42/src/site/markdown/faq.md.vm ---------------------------------------------------------------------- diff --git a/src/site/markdown/faq.md.vm b/src/site/markdown/faq.md.vm index 0b159bb..ece776b 100644 --- a/src/site/markdown/faq.md.vm +++ b/src/site/markdown/faq.md.vm @@ -16,8 +16,10 @@ limitations under the License. --> #set($dollar = '$') +#set($h1='#') +#set($h4='####') -<h1>Frequently Asked Questions</h1> +$h1 Frequently Asked Questions * [I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?](#missing_core) * [Which JAR files do I need?](#which_jars) @@ -37,13 +39,13 @@ * [How do I create a custom logger wrapper that shows the correct class, method and line number?](#logger-wrapper) <a name="missing_core"/> -<h4>I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong?</h4> +$h4 I'm seeing this error "Unable to locate a logging implementation, using SimpleLogger". What is wrong? You have the log4j-api-2.x jar file in your classpath but you still need to add the log4j-core-2.x jar to the classpath. (Also, it looks like you are using an old version of Log4j 2. You may want to upgrade.) <a name="which_jars"/> -<h4>Which JAR files do I need?</h4> +$h4 Which JAR files do I need? You need at least the log4j-api-2.x and the log4j-core-2.x jar files. @@ -64,7 +66,7 @@ The component page will have more detail. For example, the has an outline of which log4j-core features have external dependencies. <a name="exclusions"/> -<h4>How do I exclude conflicting dependencies?</h4> +$h4 How do I exclude conflicting dependencies? There are several scenarios where you may end up with conflicting dependencies, especially transitively included ones. The following table shows for each Log4j dependency on the left (implicit groupId of @@ -182,7 +184,7 @@ dependencies { ``` <a name="config_location"/> -<h4>How do I specify the configuration file location?</h4> +$h4 How do I specify the configuration file location? By default, Log4j looks for a configuration file named **log4j2.xml** (not log4j.xml) in the classpath. @@ -196,7 +198,7 @@ See [this section](http://logging.apache.org/log4j/2.x/manual/webapp.html#Contex of the Using Log4j 2 in Web Applications manual page. <a name="config_from_code"/> -<h4>How do I configure log4j2 in code without a configuration file?</h4> +$h4 How do I configure log4j2 in code without a configuration file? Starting with version 2.4, Log4j 2 provides an [API for programmatic configuration](manual/customconfig.html) The new @@ -205,7 +207,7 @@ allows you to create Configurations in code by constructing component definition without requiring you to know about the internals of actual configuration objects like Loggers and Appenders. <a name="reconfig_from_code"/> -<h4>How do I reconfigure log4j2 in code with a specific configuration file?</h4> +$h4 How do I reconfigure log4j2 in code with a specific configuration file? See the below example. Be aware that this LoggerContext class is not part of the public API so your code may break with any minor release. @@ -221,7 +223,7 @@ context.setConfigLocation(file.toURI()); ``` <a name="shutdown"/> -<h4>How do I shut down log4j2 in code?</h4> +$h4 How do I shut down log4j2 in code? Normally there is no need to do this manually. Each `LoggerContext` registers a shutdown hook that takes care of releasing resources @@ -243,7 +245,7 @@ LogManager.shutdown(); ``` <a name="config_sep_appender_level"/> -<h4>How do I send log messages with different levels to different appenders?</h4> +$h4 How do I send log messages with different levels to different appenders? You don't need to declare separate loggers to achieve this. You can set the logging level on the `AppenderRef` element. @@ -270,7 +272,7 @@ You can set the logging level on the `AppenderRef` element. ``` <a name="troubleshooting"/> -<h4>How do I debug my configuration?</h4> +$h4 How do I debug my configuration? First, make sure you have [the right jar files](#which_jars) on your classpath. You need at least log4j-api and log4j-core. @@ -290,7 +292,7 @@ log4j2 internal status logging by setting system property `-Dorg.apache.logging.log4j.simplelog.StatusLogger.level=TRACE`. <a name="separate_log_files"/> -<h4>How do I dynamically write to separate log files?</h4> +$h4 How do I dynamically write to separate log files? Look at the [RoutingAppender](http://logging.apache.org/log4j/2.x/manual/appenders.html#RoutingAppender). You can define multiple routes in the configuration, and put values in the `ThreadContext` @@ -350,7 +352,7 @@ You can use the `ThreadContext` map value to determine the log file name. ``` <a name="reconfig_level_from_code"/> -<h4>How do I set a logger's level programmatically?</h4> +$h4 How do I set a logger's level programmatically? You can set a logger's level with the class [`Configurator`](log4j-core/apidocs/org/apache/logging/log4j/core/config/Configurator.html) @@ -366,7 +368,7 @@ Configurator.setRootLevel(Level.DEBUG); ``` <a name="retention"/> -<h4>How do I set my log archive retention policy? How do I delete old log archives?</h4> +$h4 How do I set my log archive retention policy? How do I delete old log archives? The `DefaultRolloverStrategy` of the Rolling File appender (and Rolling Random Access File appender) supports a [Delete](manual/appenders.html#CustomDeleteOnRollover) element. @@ -379,7 +381,7 @@ conditions are not sufficient, users can provide custom conditions by creating [script condition](manual/appenders.html#ScriptCondition). <a name="api-tradeoffs" /> -<h4>What are the trade-offs of using the Log4j 2 API versus the SLF4J API?</h4> +$h4 What are the trade-offs of using the Log4j 2 API versus the SLF4J API? The Log4j 2 API and SLF4J have a lot in common. They both share the objective of cleanly separating the logging API from the implementation. @@ -408,7 +410,7 @@ Filters and Lookups to manipulate them. it avoids creating vararg arrays and avoids creating Strings when logging CharSequence objects. <a name="gc-free-slf4j" /> -<h4>Is Log4j 2 still garbage-free when I use the SLF4J API?</h4> +$h4 Is Log4j 2 still garbage-free when I use the SLF4J API? Yes, the log4j-slf4j-impl binding (together with log4j-core) implements the `org.slf4j.Logger` methods to be GC-free. @@ -428,7 +430,7 @@ method is not yet implemented in a garbage-free manner in the log4j-slf4j-impl binding. It creates a new message object for each call. <a name="gc-free-domain-object" /> -<h4>How do I log my domain object without creating garbage?</h4> +$h4 How do I log my domain object without creating garbage? One option is to let the domain object implement java.lang.CharSequence. However, for many domain objects it may not be trivial to implement this without allocating temporary @@ -452,7 +454,7 @@ public interface StringBuilderFormattable { ``` <a name="logger-wrapper" /> -<h4>How do I create a custom logger wrapper that shows the correct class, method and line number?</h4> +$h4 How do I create a custom logger wrapper that shows the correct class, method and line number? Log4j remembers the fully qualified class name (FQCN) of the logger and uses this to walk the stack trace for every log event when configured to print location. http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/d29dea42/src/site/markdown/index.md.vm ---------------------------------------------------------------------- diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index 990b85d..7dabeb2 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -15,21 +15,24 @@ See the License for the specific language governing permissions and limitations under the License. --> +#set($h1='#') +#set($h2='##') +#set($h3='###') -<h1>Apache Log4j 2</h1> +$h1 Apache Log4j 2 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. -<h2>Features</h2> +$h2 Features -<h3>API Separation</h3> +$h3 API Separation 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. -<h3>Improved Performance</h3> +$h3 Improved Performance 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. @@ -37,69 +40,69 @@ See [Asynchronous Logging Performance](manual/async.html#Performance) for detail outperforms Log4j 1.x, Logback and java.util.logging, especially in multi-threaded applications. See [Performance](performance.html) for more information. -<h3>Support for multiple APIs</h3> +$h3 Support for multiple APIs 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. -<h3>Avoid lock-in</h3> +$h3 Avoid lock-in 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. -<h3>Automatic Reloading of Configurations</h3> +$h3 Automatic Reloading of Configurations 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. -<h3>Advanced Filtering</h3> +$h3 Advanced Filtering 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. -<h3>Plugin Architecture</h3> +$h3 Plugin Architecture 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. -<h3>Property Support</h3> +$h3 Property Support 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 [Lookup](manual/lookups.html) Plugin. -<h3>Java 8 Lambda Support</h3> +$h3 Java 8 Lambda Support 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 [lambda support](manual/api.html#LambdaSupport). 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. -<h3>Custom Log Levels</h3> +$h3 Custom Log Levels In Log4j 2, [custom log levels](manual/customloglevels.html) can easily be defined in code or in configuration. No subclassing is required. -<h3>Garbage-free</h3> +$h3 Garbage-free During steady state logging, Log4j 2 is [garbage-free](manual/garbagefree.html) in stand-alone applications, and low garbage in web applications. This reduces pressure on the garbage collector and can give better response time performance. -<h2>Documentation</h2> +$h2 Documentation The Log4j 2 User's Guide is available on this [site](manual/index.html) or as a downloadable [PDF](log4j-users-guide.pdf). -<h2>Requirements</h2> +$h2 Requirements 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. -<h2>News</h2> +$h2 News 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
