From e84a46ceb7fb5740f16a012da47b04cc87b1f0b7 Mon Sep 17 00:00:00 2001 From: Christian Grobmeier Date: Tue, 14 May 2024 20:32:27 +0200 Subject: [PATCH] tiny wording improvments and corrections --- .../modules/ROOT/pages/manual/async.adoc | 72 +++--- .../modules/ROOT/pages/manual/filters.adoc | 87 ++++---- .../ROOT/pages/manual/garbagefree.adoc | 97 ++++---- .../ROOT/pages/manual/installation.adoc | 16 +- .../antora/modules/ROOT/pages/manual/jmx.adoc | 6 +- .../modules/ROOT/pages/manual/layouts.adoc | 210 +++++++++--------- 6 files changed, 238 insertions(+), 250 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc index c334ccb2f07..0f576da2671 100644 --- a/src/site/antora/modules/ROOT/pages/manual/async.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/async.adoc @@ -18,11 +18,11 @@ Remko Popma Asynchronous logging can improve your application's performance by -executing the I/O operations in a separate thread. Log4j 2 makes a -number of improvements in this area. +executing the I/O operations in a separate thread. +Log4j 2 makes several improvements in this area. -* *Asynchronous Loggers* are a new addition in Log4j 2. Their aim is to -return from the call to Logger.log to the application as soon as +* *Asynchronous Loggers* are a new addition in Log4j 2. They aim to +return the call to Logger.log to the application as soon as possible. You can choose between making all Loggers asynchronous or using a mixture of synchronous and asynchronous Loggers. Making all Loggers asynchronous will give the best performance, while mixing gives @@ -35,8 +35,8 @@ latency. been enhanced to flush to disk at the end of a batch (when the queue is empty). This produces the same result as configuring "immediateFlush=true", that is, all received log events are always -available on disk, but is more efficient because it does not need to -touch the disk on each and every log event. (Async Appenders use +available on disk but are more efficient because it does not need to +touch the disk on every log event. (Async Appenders use ArrayBlockingQueue internally and do not need the disruptor jar on the classpath.) @@ -58,7 +58,7 @@ to log bursts of messages. Async logging can help prevent or dampen latency spikes by shortening the wait time until the next message can be logged. If the queue size is configured large enough to handle the burst, asynchronous logging will help prevent your application from -falling behind (as much) during a sudden increase of activity. +falling behind (as much) during a sudden increase in activity. * Lower logging response time link:#Latency[latency]. Response time latency is the time it takes for a call to Logger.log to return under a given workload. Asynchronous Loggers have consistently lower latency @@ -71,8 +71,8 @@ exception is thrown, it is less easy for an asynchronous logger or appender to signal this problem to the application. This can partly be alleviated by configuring an `ExceptionHandler`, but this may still not cover all cases. For this reason, if logging is part of your business -logic, for example if you are using Log4j as an audit logging framework, -we would recommend to synchronously log those audit messages. (Note that +logic, for example, if you are using Log4j as an audit logging framework, +we would recommend synchronously logging those audit messages. (Note that you can still link:#MixedSync-Async[combine] them and use asynchronous logging for debug/trace logging in addition to synchronous logging for the audit trail.) @@ -85,7 +85,7 @@ modified later. It is safe to asynchronously log mutable objects because most link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message`] implementations built-in to Log4j take a snapshot of the parameters. -There are some exceptions however: +There are some exceptions, however: link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[`MapMessage`] and link:../javadoc/log4j-api/org/apache/logging/log4j/message/StructuredDataMessage.html[`StructuredDataMessage`] @@ -98,6 +98,7 @@ link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[`Message implementations should be designed with asynchronous use in mind, and either take a snapshot of their parameters at construction time, or document their thread-safety characteristics. + * If your application is running in an environment where CPU resources are scarce, like a machine with one CPU with a single core, starting another thread is not likely to give better performance. @@ -105,7 +106,7 @@ another thread is not likely to give better performance. is faster than the maximum sustained throughput of the underlying appender, the queue will fill up and the application will end up logging at the speed of the slowest appender. If this happens, consider -selecting a xref:manual/performance.adoc#whichAppender[faster appender], or +selecting an xref:manual/performance.adoc#whichAppender[faster appender], or logging less. If neither of these is an option, you may get better throughput and fewer latency spikes by logging synchronously. @@ -116,7 +117,7 @@ NOTE: _Log4j-2.9 and higher require disruptor-3.3.4.jar or higher on the classpath. Prior to Log4j-2.9, disruptor-3.0.0.jar or higher was required._ -This is simplest to configure and gives the best performance. +This is the simplest to configure and gives the best performance. To make all loggers asynchronous, add the disruptor jar to the classpath and set the system property xref:manual/systemproperties.adoc#log4j2.contextSelector[log4j2.contextSelector] to `org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` or `org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector`. By default, link:#Location[location] is not passed to the I/O thread by @@ -190,17 +191,17 @@ and `log4j2.discardThreshold`]. == Mixing Synchronous and Asynchronous Loggers NOTE: _Log4j-2.9 and higher require disruptor-3.3.4.jar or higher on the -classpath. Prior to Log4j-2.9, disruptor-3.0.0.jar or higher was -required. There is no need to set system property "Log4jContextSelector" +classpath. Before Log4j-2.9, disruptor-3.0.0.jar or higher was +required. There is no need to set the system property "Log4jContextSelector" to any value._ Synchronous and asynchronous loggers can be combined in configuration. This gives you more flexibility at the cost of a slight loss in performance (compared to making all loggers asynchronous). Use the -`` or `` configuration elements to specify the +`` or `` configuration elements specify the loggers that need to be asynchronous. A configuration can contain only one root logger (either a `` or an `` element), but -otherwise async and non-async loggers may be combined. For example, a +otherwise, async and non-async loggers may be combined. For example, a configuration file containing `` elements can also contain `` and `` elements for the synchronous loggers. @@ -308,7 +309,7 @@ public interface AsyncWaitStrategyFactory { The specified class must also have a public no-argument constructor; Log4j will instantiate an instance of the specified factory class and use this factory to create the WaitStrategy used by all Async Loggers. -WaitStrategy-related system properties are ignored if a `AsyncWaitStrategyFactory` is configured. +WaitStrategy-related system properties are ignored if an `AsyncWaitStrategyFactory` is configured. [#Location] @@ -338,7 +339,7 @@ logging with location is 30-100 times slower than without location. For this reason, asynchronous loggers and asynchronous appenders do not include location information by default. -You can override the default behaviour in your logger or asynchronous +You can override the default behavior in your logger or asynchronous appender configuration by specifying `includeLocation="true"`. [#Performance] @@ -378,10 +379,10 @@ higher throughput than sync loggers.] === Asynchronous Throughput Comparison with Other Logging Packages -We also compared peak throughput of asynchronous loggers to the +We also compared the peak throughput of asynchronous loggers to the synchronous loggers and asynchronous appenders available in other logging packages, specifically log4j-1.2.17 and logback-1.0.10, with -similar results. For asynchronous appenders, total logging throughput of +similar results. For asynchronous appenders, the total logging throughput of all threads together remains roughly constant when adding more threads. Asynchronous loggers make more effective use of the multiple cores available on the machine in multi-threaded scenarios. @@ -457,14 +458,13 @@ threads This section has been rewritten with the Log4j 2.6 release. The previous version only reported _service time_ instead of _response -time_. See the xref:manual/performance.adoc#responseTime[response time] side -bar on the performance page on why this is too optimistic. Furthermore -the previous version reported average latency, which does not make sense +time_. See the xref:manual/performance.adoc#responseTime[response time] sidebar on the performance page on why this is too optimistic. +Furthermore, the previous version reported average latency, which does not make sense since latency is not a normal distribution. Finally, the previous version of this section only reported the maximum latency of up to 99.99% of the measurements, which does not tell you how bad the worst 0.01% were. This is unfortunate because often the "outliers" are all -that matter when it comes to response time. From this release we will +that matter when it comes to response time. From this release, we will try to do better and report response time latency across the full range of percentages, including all the outliers. Our thanks to Gil Tene for his http://www.infoq.com/presentations/latency-response-time[How NOT to @@ -473,11 +473,11 @@ the "Oh s#@t!" presentation.) xref:manual/performance.adoc#responseTime[Response time] is how long it takes to log a message under a certain load. What is often reported as -latency is actually _service time_: how long it took to perform the -operation. This hides the fact that a single spike in service time adds -queueing delay for many of the subsequent operations. Service time is +latency is _service time_: how long it took to operate. +This hides the fact that a single spike in service time adds +a queueing delay for many of the subsequent operations. Service time is easy to measure (and often looks good on paper) but is irrelevant for -users since it omits the time spent waiting for service. For this reason +users since it omits the time spent waiting for service. For this reason, we report response time: service time plus wait time. The response time test results below were all derived from running the @@ -494,9 +494,9 @@ wait strategy reduces some jitter.) * -XX:CompileCommand=dontinline,org.apache.logging.log4j.core.async.perftest.NoOpIdleStrategy::idle * -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintTenuringDistribution -XX:+PrintGCApplicationConcurrentTime --XX:+PrintGCApplicationStoppedTime (to eyeball GC and safepoint pauses) +-XX:+PrintGCApplicationStoppedTime (to eyeball GC and savepoint pauses) -The graph below compares response time latency of the +The graph below compares the response time latency of the ArrayBlockingQueue-based asynchronous appenders in Logback 1.1.7, Log4j 1.2.17 to the various options for asynchronous logging that Log4j 2.6 offers. Under a workload of 128,000 messages per second, using 16 @@ -506,14 +506,14 @@ orders of magnitude larger than Log4j 2. image:ResponseTimeAsyncLogging16Threads_8kEach.png[When 16 threads generate a total workload of 128,000 msg/sec, Logback 1.1.7 and -Log4j 1.2.17 experience latency spikes that are orders of magnitude +Log4j 1.2.17 experiences latency spikes that are orders of magnitude larger than Log4j 2] The graph below zooms in on the Log4j 2 results for the same test. We see that the worst-case response time is highest for the ArrayBlockingQueue-based Async Appender. xref:manual/garbagefree.adoc[Garbage-free] async loggers have the best response -time behaviour. +time behavior. image:ResponseTimeAsyncLogging16Threads_8kEachLog4j2Only-labeled.png[image] @@ -522,14 +522,14 @@ image:ResponseTimeAsyncLogging16Threads_8kEachLog4j2Only-labeled.png[image] Asynchronous Loggers are implemented using the https://lmax-exchange.github.io/disruptor/[LMAX Disruptor] inter-thread -messaging library. From the LMAX web site: +messaging library. From the LMAX website: ____ ...using queues to pass data between stages of the system was -introducing latency, so we focused on optimising this area. The +introducing latency, so we focused on optimizing this area. The Disruptor is the result of our research and testing. We found that cache -misses at the CPU-level, and locks requiring kernel arbitration are both -extremely costly, so we created a framework which has "mechanical +misses at the CPU level, and locks requiring kernel arbitration are both +extremely costly, so we created a framework that has "mechanical sympathy" for the hardware it's running on, and that's lock-free. ____ diff --git a/src/site/antora/modules/ROOT/pages/manual/filters.adoc b/src/site/antora/modules/ROOT/pages/manual/filters.adoc index 52c4bdfc36d..872e4ef4467 100644 --- a/src/site/antora/modules/ROOT/pages/manual/filters.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/filters.adoc @@ -75,7 +75,7 @@ If the logger is additive, the filter on the parent logger is applied recursivel [CAUTION] ==== -For performance reasons log events should be filtered as soon as possible in the logging pipeline. +For performance reasons, log events should be filtered as soon as possible in the logging pipeline. This reduces the costs (formatting, transfer through an asynchronous barrier) of disabled log events. ==== @@ -90,8 +90,7 @@ Using the `level` property of appender references will give a better performance == BurstFilter The BurstFilter provides a mechanism to control the rate at which -LogEvents are processed by silently discarding events after the maximum -limit has been reached. +LogEvents are processed by silently discarding events after the maximum limit has been reached. .Burst Filter Parameters [cols="1m,1,4"] @@ -117,12 +116,12 @@ times the rate. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -154,8 +153,8 @@ A configuration containing the BurstFilter might look like: == CompositeFilter The CompositeFilter provides a way to specify more than one filter. It -is added to the configuration as a filters element and contains other -filters to be evaluated. The filters element accepts no parameters. +is added to the configuration as a filter element and contains other +filters to be evaluated. The filter element accepts no parameters. A configuration containing the CompositeFilter might look like: @@ -218,7 +217,7 @@ specified ThreadContext item NEUTRAL will be returned. |String |Level of messages to be filtered. The default threshold only applies if the log event contains the specified -ThreadContext Map item and its value does not match any key in the +ThreadContext Map item and its value do not match any key in the key/value pairs. |keyValuePair @@ -229,12 +228,12 @@ key matches. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -329,7 +328,7 @@ MapMessage. |keyValuePair |KeyValuePair[] |One or more KeyValuePair elements that -define the key in the map and the value to match on. If the same key is +define the key in the map and the value to match. If the same key is specified more than once then the check for that key will automatically be an "or" since a Map can only contain a single value. @@ -341,12 +340,12 @@ key/value pairs must match. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -458,12 +457,12 @@ matches either the Log Event's Marker or one of its parents. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -495,7 +494,7 @@ appender if the Marker matches: [#MutableThreadContextMapFilter] == MutableThreadContextMapFilter -The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the current context. By default this is the ThreadContext Map. The values to compare are defined externally and can be periodically polled for changes. +The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the current context. By default, this is the ThreadContext Map. The values to compare are defined externally and can be periodically polled for changes. .Mutable Context Map Filter Parameters [cols="1m,1,4"] @@ -514,16 +513,16 @@ key/value pairs must match. |pollInterval |int -|The number of seconds to wait before checking to see if the configuration has been modified. When using HTTP or HTTPS the server must support the If-Modified-Since header and return a Last-Modified header containing the date and time the file was last modified. Note that by default only the https, file, and jar protocols are allowed. Support for other protocols can be enabled by specifying them in the log4j2.Configuration.allowedProtocols system property +|The number of seconds to wait before checking to see if the configuration has been modified. When using HTTP or HTTPS the server must support the If-Modified-Since header and return a Last-Modified header containing the date and time the file was last modified. Note that by default only the https, file, and jar protocols are allowed. Support for other protocols can be enabled by specifying them in the `log4j2.Configuration.allowedProtocols` system property |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -567,8 +566,8 @@ The configuration file supplied to the filter should look similar to: [#NoMarkerFilter] == NoMarkerFilter -The NoMarkerFilter checks that there is no marker included in the LogEvent. A match occurs when there is no -marker in the Log Event. +The NoMarkerFilter checks that there is no marker included in the LogEvent. +A match occurs when there is no marker in the Log Event. .No Marker Filter Parameters [cols="1m,1,3"] @@ -577,12 +576,12 @@ marker in the Log Event. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -629,17 +628,17 @@ compared against a regular expression. |useRawMsg |boolean |If true the unformatted message will be used, -otherwise the formatted message will be used. The default value is +otherwise, the formatted message will be used. The default value is false. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -683,12 +682,12 @@ The ScriptFilter executes a script that returns true or false. |onMatch |String -|Action to take when the script returns true. May be +|Action to take when the script returns true. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter returns false. May +|Action to take when the filter returns false. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -741,7 +740,7 @@ Throwable as part of the Message. |substitutor |StrSubstitutor -|The StrSubstitutor used to replace lookup variables. +|The StrSubstitutor is used to replace lookup variables. |=== The sample below shows how to declare script fields and then reference @@ -801,7 +800,7 @@ the event id, type and message. |KeyValuePair[] |One or more KeyValuePair elements that define the key in the map and the value to match on. "id", "id.name", -"type", and "message" should be used to match on the StructuredDataId, +"type", and "message" should be used to match the StructuredDataId, the name portion of the StructuredDataId, the type, and the formatted message respectively. If the same key is specified more than once then the check for that key will automatically be an "or" since a Map can @@ -815,12 +814,12 @@ key/value pairs must match. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -857,7 +856,7 @@ particular events: == ThreadContextMapFilter The ThreadContextMapFilter or ContextMapFilter allows filtering against -data elements that are in the current context. By default this is the +data elements that are in the current context. By default, this is the ThreadContext Map. .Context Map Filter Parameters @@ -868,7 +867,7 @@ ThreadContext Map. |keyValuePair |KeyValuePair[] |One or more KeyValuePair elements that -define the key in the map and the value to match on. If the same key is +define the key in the map and the value to match. If the same key is specified more than once then the check for that key will automatically be an "or" since a Map can only contain a single value. @@ -880,12 +879,12 @@ key/value pairs must match. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -950,9 +949,9 @@ The ContextMapFilter can also be applied to a logger for filtering: == ThresholdFilter This filter returns the onMatch result if the level in the LogEvent is -the same or more specific than the configured level and the onMismatch +the same or more specific than the configured level and the `onMismatch` value otherwise. For example, if the ThresholdFilter is configured with -Level ERROR and the LogEvent contains Level DEBUG then the onMismatch +Level ERROR and the LogEvent contains Level DEBUG then the `onMismatch` value will be returned since ERROR events are more specific than DEBUG. .Threshold Filter Parameters @@ -962,16 +961,16 @@ value will be returned since ERROR events are more specific than DEBUG. |level |String -|A valid Level name to match on. +|A valid Level name to match. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== @@ -1003,7 +1002,7 @@ appender if the level matches: [#TimeFilter] == TimeFilter -The time filter can be used to restrict filter to only a certain portion +The time filter can be used to restrict the filter to only a certain portion of the day. .Time Filter Parameters @@ -1027,12 +1026,12 @@ timestamp. |onMatch |String -|Action to take when the filter matches. May be ACCEPT, +|Action to take when the filter matches. Can be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL. |onMismatch |String -|Action to take when the filter does not match. May +|Action to take when the filter does not match. Can be ACCEPT, DENY or NEUTRAL. The default value is DENY. |=== diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc index 426af6b5d83..3393c21a3a1 100644 --- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc @@ -32,14 +32,14 @@ many systems significant effort is spent on controlling these pauses. Many logging libraries, including previous versions of Log4j, allocate temporary objects like log event objects, Strings, char arrays, byte -arrays and more during steady state logging. This contributes to +arrays and more during steady-state logging. This contributes to pressure on the garbage collector and increases the frequency with which GC pauses occur. -From version 2.6, Log4j runs in "garbage free" mode by default where +From version 2.6, Log4j runs in "garbage-free" mode by default where objects and buffers are reused and no temporary objects are allocated as much as possible. There is also a "low garbage" mode which is not -completely garbage free but does not use ThreadLocal fields. This is the +completely garbage-free but does not use ThreadLocal fields. This is the default mode when Log4j link:#Config[detects] it is running in a web application. Finally, it is possible to switch off all garbage-free logic and run in "classic mode" instead. For details, see the @@ -121,7 +121,7 @@ for multi-threaded applications in this mode due to synchronization on the shared buffer. If your application is multi-threaded and logging performance is important, consider using Async Loggers. * The ThreadContext map is _not_ garbage-free by default, but from Log4j -2.7 it can be configured to be garbage-free by setting system property +2.7 it can be configured to be garbage-free by setting the system property xref:manual/systemproperties.adoc#log4j2.garbagefreeThreadContextMap[log4j2.garbagefreeThreadContextMap] to "true". Instead of system properties, the above properties can also be specified @@ -158,16 +158,16 @@ steady-state logging: * CompositeFilter (adding and removing element filters creates temporary objects for thread safety) * DynamicThresholdFilter -* LevelRangeFilter (garbage free since 2.8) -* MapFilter (garbage free since 2.8) -* MarkerFilter (garbage free since 2.8) -* StructuredDataFilter (garbage free since 2.8) -* ThreadContextMapFilter (garbage free since 2.8) -* ThresholdFilter (garbage free since 2.8) -* TimeFilter (garbage free since 2.8 except when range must be recalculated once per day) +* LevelRangeFilter (garbage-free since 2.8) +* MapFilter (garbage-free since 2.8) +* MarkerFilter (garbage-free since 2.8) +* StructuredDataFilter (garbage-free since 2.8) +* ThreadContextMapFilter (garbage-free since 2.8) +* ThresholdFilter (garbage-free since 2.8) +* TimeFilter (garbage-free since 2.8 except when range must be recalculated once per day) Other filters like BurstFilter, RegexFilter and ScriptFilter are not -trivial to make garbage free, and there is currently no plan to change +trivial to make garbage-free, and there is currently no plan to change them. [#Layouts] @@ -186,7 +186,7 @@ xref:manual/json-template-layout.adoc#faq-garbage-free[a few exceptions]. PatternLayout with the following limited set of conversion patterns is garbage-free. Format modifiers to control such things as field width, -padding, left and right justification will not generate garbage. +padding, and left and right justification will not generate garbage. [cols="1m,2"] |=== @@ -198,7 +198,7 @@ padding, left and right justification will not generate garbage. |%d, %date a| Note: Only the predefined date formats are garbage-free: (millisecond -separator may be either a comma ',' or a period '.') +the separator may be either a comma ',' or a period '.') [cols="1m,1"] !=== @@ -248,11 +248,11 @@ garbage-free since 2.8 %equalsIgnoreCase\{pattern}\{test}\{substitution} |Replaces occurrences of 'test', a string, with its replacement 'substitution' in the string -resulting from evaluation of the pattern - garbage-free since 2.8 +resulting from the evaluation of the pattern - garbage-free since 2.8 |%highlight\{pattern}\{style} |Adds ANSI colors - garbage-free since 2.7 -(unless nested pattern is not garbage free) +(unless the nested pattern is not garbage-free) |%K\{key}, %map\{key}, %MAP\{key} |Outputs the entries in a @@ -272,11 +272,11 @@ since 2.8 parents) |%maxLen, %maxLength -|Truncates another pattern to some max number of +|Truncates another pattern to some maximum number of characters - garbage-free since 2.8 |%n -|The platform dependent line separator +|The platform-dependent line separator |%N, %nano |System.nanoTime() when the event was logged @@ -300,7 +300,7 @@ every event - garbage-free since 2.8 |%style\{pattern}{ANSI style} |Style the message - garbage-free since -2.7 (unless nested pattern is not garbage free) +2.7 (unless the nested pattern is not garbage-free) |%T, %tid, %threadId |The ID of the thread that generated the logging @@ -324,13 +324,13 @@ garbage-free since 2.8 substitution) |=== -Other PatternLayout conversion patterns, and other Layouts may be +Other PatternLayout conversion patterns and other Layouts may be updated to avoid creating temporary objects in future releases. (Patches welcome!) NOTE: Logging exceptions and stack traces will create temporary objects with any layout. (However, Layouts will only create these -temporary objects when an exception actually occurs.) We haven't figured +temporary objects when an exception occurs.) We haven't figured out a way to log exceptions and stack traces without creating temporary objects. That is unfortunate, but you probably still want to log them when they happen. @@ -393,10 +393,10 @@ not possible. When logging primitive values (i.e. int, double, boolean, etc.) the JVM autoboxes these primitive values to their Object wrapper equivalents, creating garbage. -Log4j provides an `Unbox` utility to prevent autoboxing of primitive +Log4j provides an `Unbox` utility to prevent the autoboxing of primitive parameters. This utility contains a thread-local pool of reused `StringBuilder`s. The `Unbox.box(primitive)` methods write directly into -a StringBuilder, and the resulting text will be copied into the final +a `StringBuilder`, and the resulting text will be copied into the final log message text without creating temporary objects. [source,java] @@ -410,16 +410,16 @@ public void garbageFree() { ---- **** -NOTE: not all logging is garbage free. Specifically: +NOTE: not all logging is garbage-free. Specifically: -* The ThreadContext map is not garbage-free by default, but can be -configured to be garbage-free by setting system property +* The ThreadContext map is not garbage-free by default but can be +configured to be garbage-free by setting the system property `log4j2.garbagefreeThreadContextMap` to "true". * The ThreadContext stack is not garbage-free. * Logging more than 10 parameters creates vararg arrays. * Logging very large messages (more than 518 characters) when all loggers are Async Loggers will cause the internal StringBuilder in the -RingBuffer to be trimmed back to their max size. +RingBuffer is to be trimmed back to its max size. * Logging messages containing '${': substituting a `$\{variable}` creates temporary objects. * Logging a lambda _as a parameter_ @@ -428,7 +428,7 @@ creates a vararg array. Logging a lambda expression by itself is garbage-free: `logger.debug(() -> callExpensiveMethod())`. * The `Logger.traceEntry` and `Logger.traceExit` methods create temporary objects. -* Time calculations are not garbage free when log4j2.usePreciseClock is set to true. +* Time calculations are not garbage-free when log4j2.usePreciseClock is set to true. The default is false. **** @@ -439,12 +439,12 @@ The default is false. === Response Time Latency Response time is how long it takes to log a message under a certain -load. What is often reported as latency is actually _service time_: how -long it took to perform the operation. This hides the fact that a single -spike in service time adds queueing delay for many of the subsequent +load. What is often reported as latency is _service time_: how +long it took to operate. This hides the fact that a single +spike in service time adds a queueing delay for many of the subsequent operations. Service time is easy to measure (and often looks good on paper) but is irrelevant for users since it omits the time spent waiting -for service. For this reason we report response time: service time plus +for service. For this reason, we report response time: service time plus wait time. See the xref:manual/performance.adoc#responseTime[response time section] of the performance page for more detail. @@ -462,25 +462,25 @@ wait strategy reduces some jitter.) * -XX:CompileCommand=dontinline,org.apache.logging.log4j.core.async.perftest.NoOpIdleStrategy::idle * -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintTenuringDistribution -XX:+PrintGCApplicationConcurrentTime --XX:+PrintGCApplicationStoppedTime (to eyeball GC and safepoint pauses) +-XX:+PrintGCApplicationStoppedTime (to eyeball GC and savepoint pauses) === Async Loggers The graph below compares "classic" logging to garbage-free logging -response time behaviour for Log4j's Async Loggers. In the graph, "100k" -means logging at a sustained load of 100,000 messages/second, "800k" is +response time behavior for Log4j's Async Loggers. In the graph, "100k" +means logging at a sustained load of 100,000 messages/second, and "800k" is a sustained load of 800,000 messages/second. image:ResponseTimeAsyncClassicVsGcFree-label.png[image] -In *classic* mode we see numerous minor garbage collections which pause +In *classic* mode we see numerous minor garbage collections that pause the application threads for 3 milliseconds or more. This quickly adds up to response time delays of almost 10 milliseconds. As you can see in the graph, increasing the load shifts the curve to the left (there are more spikes). This makes sense: logging more means more pressure on the garbage collector resulting in more minor GC pauses. We experimented a little with reducing the load to 50,000 or even 5000 messages/second, -but this did not eliminate the 3 millisecond pauses, it just made them +but this did not eliminate the 3-millisecond pauses, it just made them occur less frequently. Note that all GC pauses in this test are minor GC pauses. We did not see any full garbage collections. @@ -488,19 +488,19 @@ In *garbage-free* mode, maximum response time remains well below 1 millisecond under a wide range of loads. (Max 780 us at 800,000 messages/sec, max 407 us at 600,000 messages/sec, with the 99% around 5 us for all loads up to 800,000 messages/sec.) Increasing or decreasing -the load does not change the response time behaviour. We did not +the load does not change the response time behavior. We did not investigate the cause of the 200-300 microsecond pauses we saw in these tests. -When we increased the load further we begin to see larger response time +When we increased the load further we began to see larger response time pauses for both classic and garbage-free logging. At sustained loads of 1 million messages/second or more we start to approach the maximum throughput of the underlying RandomAccessFile Appender (see the -synchronous logging throughput chart below). At these loads the -ringbuffer starts to fill up and backpressure kicks in: attempting to +synchronous logging throughput chart below). At these loads, the +ringbuffer starts to fill up and backpressure kicks in, attempting to add another message when the ringbuffer is full will block until a free slot becomes available. We start to see response times of tens of -milliseconds or more; and attempting to increase the load even more +milliseconds or more, and attempting to increase the load even more results in larger and larger response time spikes. === Synchronous File Logging @@ -509,11 +509,11 @@ With synchronous file logging, garbage-free logging still performs better than classic logging, but the difference is less pronounced. At a workload of 100,000 messages/second, classic logging max response -time was a little over 2 milliseconds where garbage-free logging was a +time was a little over 2 milliseconds whereas garbage-free logging was a little over 1 millisecond. When the workload is increased to 300,000 messages/second, classic logging shows response time pauses of 6 milliseconds where the garbage-free response times were less than 3 -milliseconds. It may be possible to improve on this, we did not +milliseconds. It may be possible to improve on this, but we did not investigate further yet. image:ResponseTimeSyncClassicVsGcFree.png[image] @@ -535,7 +535,7 @@ classic mode and Log4j 2.5. image:garbage-free2.6-SyncThroughputLinux.png[Throughput of Log4j 2.6 in garbage-free mode is slightly worse than in classic mode, -but on par with 2.5 and much better than alternatives logging libraries] +but on par with 2.5 and much better than alternative logging libraries] The results above are obtained with the http://openjdk.java.net/projects/code-tools/jmh/[JMH] Java benchmark @@ -564,12 +564,11 @@ directly write into. `AbstractOutputStreamAppender` has been modified to make the ConsoleAppender, (Rolling)FileAppender, (Rolling)RandomAccessFileAppender and MemoryMappedFileAppender -garbage-free. An effort has been made to minimize impact on custom +garbage-free. An effort has been made to minimize the impact on custom Appenders that extend `AbstractOutputStreamAppender`, but it is -impossible to guarantee that changing the superclass will not impact any -and all subclasses. Custom Appenders that extend +impossible to guarantee that changing the superclass will not impact any subclasses. Custom Appenders that extend `AbstractOutputStreamAppender` should verify that they still function -correctly. In case there is a problem, system property +correctly. In case there is a problem, the system property `log4j2.enable.direct.encoders` can be set to "false" to revert to the pre-Log4j 2.6 behaviour. diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index c2d46c7d452..cf84dac6c76 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -33,7 +33,7 @@ Below we share some shortcuts for the impatient. [WARNING] ==== -We strongly advise you to skim through this page to get a grip on fundamental logging concepts and understand which recipe fits to your bill best. +We strongly advise you to skim through this page to get a grip on fundamental logging concepts and understand which recipe fits your bill best. ==== Are you a library developer?:: @@ -262,7 +262,7 @@ implementation 'org.apache.logging.log4j:log4j-api' [#impl] == Installing a logging implementation -Log4j provides several modules to facilitate deployment of different logging implementations: +Log4j provides several modules to facilitate the deployment of different logging implementations: `log4j-core`:: The reference implementation. @@ -280,7 +280,7 @@ https://logback.qos.ch/[Logback] implements SLF4J natively, refer to < While xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is a good first choice and preferable for tests, we recommend using a structured format such as xref:manual/json-template-layout.adoc[] for production deployments. -In order to use these formats, the following additional dependencies are required: +To use these formats, the following additional dependencies are required: include::partial$configuration-file-format-deps.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc index a6a5f933614..43dba1504fa 100644 --- a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc @@ -50,7 +50,7 @@ system property to `false`. The JConsole tool that is included in the Java JDK can be used to monitor your application. Start JConsole by typing `$JAVA_HOME/bin/jconsole` in a command shell. For more details, -see Oracle's documentation on +see Oracle's documentation at https://docs.oracle.com/javase/7/docs/technotes/guides/management/jconsole.html[how to use JConsole]. @@ -69,7 +69,7 @@ and In the property above, `portNum` is the port number through which you want to enable JMX RMI connections. -For more details, see Oracle's documentation on +For more details, see Oracle's documentation at https://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl[Remote Monitoring and Management]. @@ -83,7 +83,7 @@ documentation] for the `sun.rmi.dgc.server.gcInterval` and properties is 3600000 milliseconds (one hour). Before Java 6, it was one minute. -The two sun.rmi arguments reflect whether your JVM is running in server +The two `sun.rmi` arguments reflect whether your JVM is running in server or client mode. If you want to modify the GC interval time it may be best to specify both properties to ensure the argument is picked up by the JVM. diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc index 1b16a5eddf5..1859d2b4c9d 100644 --- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc @@ -52,8 +52,7 @@ The CSV layout can be used in two ways: First, using `CsvParameterLayout` to log event parameters to create a custom database, usually to a logger and file appender uniquely configured for this purpose. Second, using `CsvLogEventLayout` to log events to create -a database, as an alternative to using a full DBMS or using a JDBC -driver that supports the CSV format. +a database, as an alternative to using a full DBMS or using a JDBC driver that supports the CSV format. The `CsvParameterLayout` converts an event's parameters into a CSV record, ignoring the message. To log CSV records, you can use the usual @@ -70,7 +69,7 @@ Which will create the CSV record: value1, value2, value3 .... -Alternatively, you can use a `ObjectArrayMessage`, which only carries +Alternatively, you can use an `ObjectArrayMessage`, which only carries parameters: [source,java] @@ -131,7 +130,7 @@ specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`. |Desc. |=== -Logging as a CSV events looks like this: +Logging as a CSV event looks like this: [source,java] ---- @@ -273,7 +272,7 @@ expensive operation and may impact performance. Use with caution. |fontSize |String -|The `font-size` to use. The default is "small". +|The `font size` to use. The default is "small". |datePattern |String @@ -281,12 +280,12 @@ expensive operation and may impact performance. Use with caution. |timezone |String -|The timezone id of the logging event. If not specified, this layout uses the https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()[java.util.TimeZone.getDefault] as default timezone. Like link:#PatternDate[date pattern] of PatternLayout, you can use timezone id from +|The timezone id of the logging event. If not specified, this layout uses the https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()[java.util.TimeZone.getDefault] as the default timezone. Like link:#PatternDate[date pattern] of PatternLayout, you can use the timezone id from https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone]. |=== -Configure as follows to use dataPattern and timezone in HtmlLayout: +Configure as follows to use `dataPattern` and timezone in `HtmlLayout`: [source,xml] ---- @@ -371,7 +370,7 @@ Log event follows this pattern: === Pretty vs. compact JSON -The compact attribute determines whether the output will be "pretty" or not. The default value is "false", which means the appender uses end-of-line characters and indents lines to format the text. If `compact="true"`, then no end-of-line or indentation is used, which will cause the output to take less space. Of course, the message content may contain, escaped end-of-lines. +The compact attribute determines whether the output will be "pretty" or not. The default value is "false", which means the appender uses end-of-line characters and indent lines to format the text. If `compact="true"`, then no end-of-line or indentation is used, which will cause the output to take less space. Of course, the message content may contain, escaped end-of-lines. [options="header"] |=== @@ -391,7 +390,7 @@ The compact attribute determines whether the output will be "pretty" or not. The | objectMessageAsJsonObject | boolean | If true, ObjectMessage is serialized as JSON object to the "message" field of the output log. Defaults to false. |=== -To include any custom field in the output, use following syntax: +To include any custom field in the output, use the following syntax: [source,xml] ---- @@ -409,8 +408,8 @@ Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for [#JSONTemplateLayout] == JSON Template Layout -`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON -emitting layout. It encodes ``LogEvent``s according to the structure described +`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON-emitting layout. +It encodes ``LogEvent``s according to the structure described by the JSON template provided. For instance, given the following JSON template modelling https://github.com/logstash/log4j-jsonevent-layout[the official Logstash `JSONEventLayoutV1`] @@ -515,12 +514,12 @@ documentation. [id=pattern-layout] == [[PatternLayout]] Pattern Layout -A flexible layout configurable with pattern string. The goal of this +A flexible layout is configurable with a pattern string. The goal of this class is to format a LogEvent and return the results. The format of the result depends on the _conversion pattern_. The conversion pattern is closely related to the conversion pattern of -the printf function in C. A conversion pattern is composed of literal +the `printf()` function in C. A conversion pattern is composed of literal text and format control expressions called _conversion specifiers_. _Note that any literal text, including *Special Characters*, may be @@ -531,7 +530,7 @@ Each conversion specifier starts with a percent sign (%) and is followed by optional _format modifiers_ and a _conversion character_. The conversion character specifies the type of data, e.g. category, priority, date, thread name. The format modifiers control such things as -field width, padding, left and right justification. The following is a +field width, padding, and left and right justification. The following is a simple example. Let the conversion pattern be *"%-5p [%t]: %m%n"* and assume that the @@ -558,7 +557,7 @@ logging event should be left justified to a width of five characters. If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the pattern will act as if the `%xEx` specifier -had be added to the end of the string. To suppress formatting of the +had been added to the end of the string. To suppress the formatting of the Throwable completely simply add `%ex\{0}` as a specifier in the pattern string. @@ -632,7 +631,7 @@ escape codes. |regex |String -|A Java-compliant regular expression to match in the resulting string. See +|A Java-compliant regular expression to match the resulting string. See https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[Pattern]. |replacement @@ -658,7 +657,7 @@ with a decimal integer. When the precision specifier is an integer value, it reduces the size of the logger name. If the number is positive, the layout prints the -corresponding number of rightmost logger name components. If negative, +corresponding number of the rightmost logger name components. If negative, the layout removes the corresponding number of leftmost logger name components. If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern. @@ -824,7 +823,7 @@ You can define custom date formats: `%d\{UNIX}` outputs the UNIX time in seconds. `%d\{UNIX_MILLIS}` outputs the UNIX time in milliseconds. The UNIX time is the difference, in seconds -for UNIX and in milliseconds for UNIX_MILLIS, between the current time +for UNIX and milliseconds for UNIX_MILLIS, between the current time and midnight, January 1, 1970 UTC. While the time unit is milliseconds, the granularity depends on the operating system (http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx[Windows]). @@ -835,11 +834,11 @@ involved. Log4j 2.11 adds limited support for timestamps more precise than milliseconds when running on Java 9. Note that not all https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] -formats are supported. Only timestamps in the formats mentioned in the -table above may use the "nano-of-second" pattern letter `n` instead of +formats are supported. Only timestamps in the formats mentioned in the table +above may use the "nano-of-second" pattern letter `n` instead of the "fraction-of-second" pattern letter `S`. -Users may revert back to a millisecond-precision clock when running on +Users may revert to a millisecond-precision clock when running on Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`. |*enc*\{pattern}{[HTML\|XML\|JSON\|CRLF]} + @@ -847,9 +846,8 @@ Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`. |Encodes and escapes special characters suitable for output in specific markup languages. By default, this encodes for HTML if only one option is specified. The second option is used to specify which encoding format -should be used. This converter is particularly useful for encoding user -provided data so that the output data is not written improperly or -insecurely. +should be used. This converter is particularly useful for encoding user-provided +data so that the output data is not written improperly or insecurely. A typical usage would encode the message `%enc{%m}` but user input could come from other locations as well, such as the MDC `%enc{%mdc\{key}}` @@ -911,9 +909,9 @@ Using the CRLF encoding format, the following characters are replaced: |*equals*\{pattern}\{test}\{substitution} + *equalsIgnoreCase*\{pattern}\{test}\{substitution} |Replaces occurrences of 'test', a string, with its replacement -'substitution' in the string resulting from evaluation of the pattern. +'substitution' in the string resulting from the evaluation of the pattern. For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings -produces by events without markers with an empty string. +produced by events without markers with an empty string. The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords. @@ -968,7 +966,7 @@ Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces. Use `{suffix(pattern)}` to add the output of _pattern_ at the end of -each stack frames. +each stack frame. Use a `{separator(...)}` as the end-of-line string. For example: `separator(\|)`. The default value is the `line.separator` system @@ -1014,8 +1012,7 @@ The color names are ANSI names defined in the link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`] class. -The color and attribute names and are standard, but the exact shade, -hue, or value. +The color and attribute names are standard, but the exact shade, hue, or value. .Color table !=== @@ -1039,14 +1036,13 @@ example: %highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue} .... -You can highlight only the a portion of the log event: +You can highlight only the portion of the log event: .... %d [%t] %highlight{%-5level: %msg%n%throwable} .... -You can style one part of the message and highlight the rest the log -event: +You can style one part of the message and highlight the rest of the log event: .... %style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable} @@ -1085,16 +1081,16 @@ The STYLE value can be one of: link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage], if one is present in the event. The `K` conversion character can be followed by the key for the map placed between braces, as in -`%K\{clientNumber}` where `clientNumber` is the key. The value in the -Map corresponding to the key will be output. If no additional sub-option -is specified, then the entire contents of the Map key value pair set is +`%K\{clientNumber}` where `clientNumber` is the key. The value of the Map +corresponding to the key will be output. If no additional sub-option +is specified, then the entire contents of the Map key-value pair set is output using a format {{key1,val1},{key2,val2}} |[[PatternLocation]] *l* + *location* -|Outputs location information of the caller which generated the logging event. +|Outputs location information of the caller which generates the logging event. -The location information depends on the JVM implementation but usually +The location information depends on the JVM implementation but it usually consists of the fully qualified name of the calling method followed by the callers source the file name and line number between parentheses. @@ -1112,7 +1108,7 @@ with caution. |[[PatternMessage]] *m*\{lookups}\{ansi} + *msg*\{lookups}\{ansi} + *message\{lookups}\{ansi} -|Outputs the application supplied message associated with the logging +|Outputs the application-supplied message associated with the logging event. Add `\{ansi}` to render messages with ANSI escape codes (requires JAnsi, @@ -1192,7 +1188,7 @@ example: `%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis. |[[PatternNewLine]] *n* -|Outputs the platform dependent line separator character or characters. +|Outputs the platform-dependent line separator character or characters. This conversion character offers practically the same performance as using non-portable line separator strings such as "\n", or "\r\n". Thus, @@ -1200,8 +1196,7 @@ it is the preferred way of specifying a line separator. |[[NanoTime]] *N* + *nano* -|Outputs the result of `System.nanoTime()` at the time the log -event was created. +|Outputs the result of `System.nanoTime()` at the time the log event was created. |[[Process_ID]] *pid*{[defaultValue]} + *processId*{[defaultValue]} @@ -1225,7 +1220,7 @@ For example: ...} **p**\|*level*{length=_n_} **p**\|*level*{lowerCase=__true__\|_false_} |Outputs the level of the logging event. You provide a level name map in -the form "level=value, level=value" where level is the name of the Level +the form "level=value, level=value" where the level is the name of the Level and value is the value that should be displayed instead of the name of the Level. @@ -1257,11 +1252,10 @@ You can combine the two kinds of options: %level{ERROR=Error, length=2} .... -This give you the `Error` level name and all other level names of length +This gives you the `Error` level name and all other level names of length 2. -Finally, you can output lower-case level names (the default is -upper-case): +Finally, you can output lower-case level names (the default is upper-case): .... %level{lowerCase=true} @@ -1279,11 +1273,11 @@ For example, "%repeat{\*}\{2}" will result in the string "**". |[[PatternReplace]] *replace*\{pattern}\{regex}\{substitution} |Replaces occurrences of 'regex', a regular expression, with its -replacement 'substitution' in the string resulting from evaluation of +replacement 'substitution' in the string resulting from the evaluation of the pattern. For example, "%replace{%msg}{\s}\{}" will remove all spaces contained in the event message. -The pattern can be arbitrarily complex and in particular can contain +The pattern can be arbitrarily complex and in particular, can contain multiple conversion keywords. For instance, "%replace{%logger %msg}{\.}{/}" will replace all dots in the logger or the message of the event with a forward slash. @@ -1329,7 +1323,7 @@ within applications that share the same converter Class object. |[[PatternStyle]] *style*\{pattern}{ANSI style} |Uses ANSI escape sequences to style the result of the enclosed pattern. -The style can consist of a comma separated list of style names from the +The style can consist of a comma-separated list of style names from the following table. (See Jansi link:#enable-jansi[configuration].) !=== @@ -1357,55 +1351,55 @@ following table. (See Jansi link:#enable-jansi[configuration].) ! !Black or FG_Black -!Set foreground color to black +!Set the foreground color to black !Red or FG_Red -!Set foreground color to red +!Set the foreground color to red !Green or FG_Green -!Set foreground color to green +!Set the foreground color to green !Yellow or FG_Yellow -!Set foreground color to yellow +!Set the foreground color to yellow !Blue or FG_Blue -!Set foreground color to blue +!Set the foreground color to blue !Magenta or FG_Magenta -!Set foreground color to magenta +!Set the foreground color to magenta !Cyan or FG_Cyan -!Set foreground color to cyan +!Set the foreground color to cyan !White or FG_White -!Set foreground color to white +!Set the foreground color to white !Default or FG_Default -!Set foreground color to default (white) +!Set the foreground color to default (white) !BG_Black -!Set background color to black +!Set the background color to black !BG_Red -!Set background color to red +!Set the background color to red !BG_Green -!Set background color to green +!Set the background color to green !BG_Yellow -!Set background color to yellow +!Set the background color to yellow !BG_Blue -!Set background color to blue +!Set the background color to blue !BG_Magenta -!Set background color to magenta +!Set the background color to magenta !BG_Cyan -!Set background color to cyan +!Set the background color to cyan !BG_White -!Set background color to white +!Set the background color to white !=== For example: @@ -1464,14 +1458,14 @@ for the map placed between braces, as in *%X\{clientNumber}* where `clientNumber` is the key. The value in the MDC corresponding to the key will be output. -If a list of keys are provided, such as *%X{name, number}*, then each +If a list of keys is provided, such as *%X{name, number}*, then each key that is present in the ThreadContext will be output using the format {name=val1, number=val2}. The key/value pairs will be printed in the order they appear in the list. -If no sub-options are specified then the entire contents of the MDC key -value pair set is output using a format {key1=val1, key2=val2}. The -key/value pairs will be printed in sorted order. +If no sub-options are specified then the entire contents of the MDC key-value pair +set is output using a format {key1=val1, key2=val2}. +The key/value pairs will be printed in sorted order. See the link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[ThreadContext] @@ -1480,10 +1474,10 @@ class for more details. |[[PatternUUID]] *u*{"RANDOM" \| "TIME"} + *uuid* |Includes either a random or a time-based UUID. The time-based -UUID is a Type 1 UUID that can generate up to 10,000 unique ids per -millisecond, will use the MAC address of each host, and to try to insure -uniqueness across multiple JVMs and/or ClassLoaders on the same host a -random number between 0 and 16,384 will be associated with each instance +UUID is a Type 1 UUID that can generate up to 10,000 unique IDs per +millisecond will use the MAC address of each host, and to try to insure +uniqueness across multiple JVMs and/or ClassLoaders on the same host +a random number between 0 and 16,384 will be associated with each instance of the UUID generator Class and included in each time-based UUID generated. Because time-based UUIDs contain the MAC address and timestamp they should be used with care as they can cause a security @@ -1524,9 +1518,9 @@ Use a `separator` string to separate the lines of a stack trace. For example: `separator(\|)`. The default value is the `line.separator` system property, which is operating system dependent. -The `ansi` option renders stack traces with ANSI escapes code using the +The `ansi` option renders stack traces with ANSI escape code using the JAnsi library. (See link:#enable-jansi[configuration].) Use `\{ansi}` to -use the default color mapping. You can specify your own mappings with +use the default color mapping. You can specify your mappings with `key=value` pairs. The keys are: * Prefix @@ -1568,8 +1562,8 @@ print. |The sequence %% outputs a single percent sign. |=== -By default the relevant information is output as is. However, with the -aid of format modifiers it is possible to change the minimum field +By default, the relevant information is output as is. However, with +the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification. The optional format modifier is placed between the percent sign and the @@ -1591,9 +1585,9 @@ This behavior can be changed using the _maximum field width_ modifier which is designated by a period followed by a decimal constant. If the data item is longer than the maximum field, then the extra characters are removed from the _beginning_ of the data item and not from the end. -For example, it the maximum field width is eight and the data item is +For example, if the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are -dropped. This behavior deviates from the printf function in C where +dropped. This behavior deviates from the `printf()` function in C where truncation is done from the end. Truncation from the end is possible by appending a minus character right @@ -1626,15 +1620,14 @@ less than 20 characters long. |NA |none |30 -|Truncate from the beginning if the category name -is longer than 30 characters. +|Truncate from the beginning if the category name is longer than 30 characters. |%20.30c |false |20 |30 |Left pad with spaces if the category name is -shorter than 20 characters. However, if category name is longer than 30 +shorter than 20 characters. However, if the category name is longer than 30 characters, then truncate from the beginning. |%-20.30c @@ -1642,7 +1635,7 @@ characters, then truncate from the beginning. |20 |30 |Right pad with spaces if the category name is -shorter than 20 characters. However, if category name is longer than 30 +shorter than 20 characters. However, if the category name is longer than 30 characters, then truncate from the beginning. |%-20.-30c @@ -1650,7 +1643,7 @@ characters, then truncate from the beginning. |20 |30 |Right pad with spaces if the category name is -shorter than 20 characters. However, if category name is longer than 30 +shorter than 20 characters. However, if the category name is longer than 30 characters, then truncate from the end. |=== @@ -1663,9 +1656,9 @@ http://jansi.fusesource.org/[Jansi] jar to your application and set property `log4j.skipJansi` to `false`. This allows Log4j to use Jansi to add ANSI escape codes when writing to the console. -NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that +NOTE: Before Log4j 2.10, Jansi was enabled by default. The fact that Jansi requires native code means that Jansi can only be loaded by a -single class loader. For web applications this means the Jansi jar has +single class loader. For web applications, this means the Jansi jar has to be in the web container's classpath. To avoid causing problems for web applications, Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward. @@ -1728,7 +1721,7 @@ that can be selected. The LevelPatternSelector selects patterns based on the log level of the log event. If the Level in the log event is equal to (ignoring case) - the name specified on the PatternMatch key attribute, then +the name specified on the PatternMatch key attribute, then the pattern specified on that PatternMatch element will be used. [source,xml] @@ -1760,11 +1753,11 @@ the pattern specified on that PatternMatch element will be used. [#ScriptPatternSelector] ==== ScriptPatternSelector -The ScriptPatternSelector executes a script as descibed in the +The ScriptPatternSelector executes a script as described in the xref:manual/configuration.adoc#Scripts[Scripts] section of the Configuration chapter. The script is passed all the properties configured in the Properties section of the configuration, the StrSubstitutor used by the -Confguration in the "substitutor" variables, and the log event in the +Configuration in the "substitutor" variables, and the log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that should be used, or null if the default pattern should be used. @@ -1791,9 +1784,8 @@ should be used. [#RFC5424Layout] == RFC5424 Layout -As the name implies, the Rfc5424Layout formats LogEvents in accordance -with http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog -specification. Although the specification is primarily directed at +As the name implies, the Rfc5424Layout formats LogEvents by http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog specification. +Although the specification is primarily directed at sending messages via Syslog, this format is quite useful for other purposes since items are passed in the message as self-describing key/value pairs. @@ -1811,7 +1803,7 @@ syslog record. |charset |String |The character set to use when converting the syslog -String to a byte array. The String must be a valid +String to a byte array. The String must be valid http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset]. If not specified, the default system Charset will be used. @@ -1835,21 +1827,20 @@ The facility option must be set to one of "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be -specified as upper or lower case characters. +specified as upper or lowercase characters. |format |String -|If set to "RFC5424" the data will be formatted in -accordance with RFC 5424. Otherwise, it will be formatted as a BSD +|If set to "RFC5424" the data will be formatted by RFC 5424. +Otherwise, it will be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not truncate records since the receiver must -accept records of up to 2048 bytes and may accept records that are -longer. +accept records of up to 2048 bytes and may accept longer records. |id |String -|The default structured data id to use when formatting +|The default structured data-id to use when formatting according to RFC 5424. If the LogEvent contains a StructuredDataMessage the id from the Message will be used instead of this value. @@ -1870,29 +1861,28 @@ which specifies the PatternLayout pattern to use as the value. |mdcExcludes |String -|A comma separated list of mdc keys that should be +|A comma-separated list of mdc keys that should be excluded from the LogEvent. This is mutually exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records. |mdcIncludes |String -|A comma separated list of mdc keys that should be +|A comma-separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes attribute. This attribute only applies to RFC 5424 syslog records. |mdcRequired |String -|A comma separated list of mdc keys that must be +|A comma-separated list of mdc keys that must be present in the MDC. If a key is not present a LoggingException will be thrown. This attribute only applies to RFC 5424 syslog records. |mdcPrefix |String -|A string that should be prepended to each MDC key in -order to distinguish it from event attributes. The default string is -"mdc:". This attribute only applies to RFC 5424 syslog records. +|A string that should be prepended to each MDC key to distinguish it from event attributes. +The default string is "mdc:". This attribute only applies to RFC 5424 syslog records. |mdcId |String @@ -1917,7 +1907,7 @@ order to distinguish it from event attributes. The default string is The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization. The SerializedLayout accepts no parameters. -This layout is deprecated since version 2.9. Java Serialization has +This layout has been deprecated since version 2.9. Java Serialization has inherent security weaknesses, using this layout is no longer recommended. @@ -1925,7 +1915,7 @@ recommended. == Syslog Layout The SyslogLayout formats the LogEvent as BSD Syslog records matching the -same format used by Log4j 1.2. +the same format used by Log4j 1.2. .SyslogLayout Parameters [cols="1m,1,4"] @@ -1946,7 +1936,7 @@ The facility option must be set to one of "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be -specified as upper or lower case characters. +specified as upper or lowercase characters. |newLine |boolean @@ -2025,7 +2015,7 @@ Markers are represented by a `Marker` element within the `Event` element. The `M === Pretty vs. compact XML -By default, the XML layout is not compact (a.k.a. not "pretty") with `compact="false"`, which means the appender uses end-of-line characters and indents lines to format the XML. If `compact="true"`, then no end-of-line or indentation is used. Message content may contain, of course, end-of-lines. +By default, the XML layout is not compact (a.k.a. not "pretty") with `compact="false"`, which means the appender uses end-of-line characters and indent lines to format the XML. If `compact="true"`, then no end-of-line or indentation is used. Message content may contain, of course, end-of-lines. [options="header"] |=== @@ -2155,5 +2145,5 @@ logging with location is 30-100 times slower than without location. For this reason, asynchronous loggers and asynchronous appenders do not include location information by default. -You can override the default behaviour in your logger or asynchronous +You can override the default behavior in your logger or asynchronous appender configuration by specifying `includeLocation="true"`.