vy commented on code in PR #2645: URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633691523
########## src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc: ########## @@ -0,0 +1,1719 @@ +//// + 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. +//// + += Pattern Layout + +Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern. +It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`. + +[IMPORTANT] +==== +Pattern Layout is not intended for _structural logging_ purposes. +For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging. +==== + +[#usage] +== Usage + +Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`. +A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*. +For instance, given the following layout configuration + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`] +[source,xml] +---- +include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`] +[source,json] +---- +include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`] +[source,xml] +---- +include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`] +[source,xml] +---- +include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0] +---- +==== + +then the following statements + +[source,java] +---- +LOGGER.debug("Message 1"); +LOGGER.warn("Message 2"); +---- + +will yield the output + +[source,text] +---- +DEBUG [main]: Message 1 +WARN [main]: Message 2 +---- + +Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern. +Use `\\` to insert a single backslash into the output. + +Each conversion specifier starts with a `%` character, 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, and left and right justification. +Use `%%` to insert a single `%` into the output. +Use `%n` to insert the line separator of the platform. + +There is no explicit separator between text and conversion specifiers. +The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character. +In the example above the conversion specifier `%-5p` means the priority of the log 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 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. + +[#config] +== Configuration + +This section explains how to configure Pattern Layout plugin element in a Log4j configuration file. + +[#plugin-attrs] +=== Plugin attributes + +Pattern Layout plugin configuration accepts the following attributes: + +[#plugin-attr-charset] +==== `charset` + +[cols="2h,6"] +|=== +|Type |`Charset` +|Default value |The platform default +|=== + +`Charset` used for encoding the produced JSON into bytes + +[#plugin-attr-pattern] +==== `pattern` + +[cols="2h,6"] +|=== +|Type |`String` +|Default value |`%m%n` +|=== + +A composite pattern string of one or more xref:#converters[]. +`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified. + +[#plugin-attr-patternSelector] +==== `patternSelector` + +[cols="2h,6"] +|=== +|Type |xref:#plugin-element-PatternSelector[`PatternSelector`] +|=== + +A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event. +`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified. + +[#plugin-attr-replace] +==== `replace` + +[cols="2h,6"] +|=== +|Type |xref:#plugin-element-RegexReplacement[`RegexReplacement`] +|=== + +Allows portions of the resulting `String` to be replaced. +If configured, the `replace` element must specify the regular expression to match and the substitution. + +[#plugin-attr-alwaysWriteExceptions] +==== `alwaysWriteExceptions` + +[cols="2h,6"] +|=== +|Type |`boolean` +|Default value |`true` +|=== + +If `true`, exceptions are always written even if the pattern contains no exception conversions. +This means that if you do not include a way to output exceptions in your pattern, the default exception formatter will be added to the end of the pattern. +Setting this to `false` disables this behavior and allows you to exclude exceptions from your pattern output. + +[#plugin-attr-header] +==== `header` + +[cols="2h,6"] +|=== +|Type |`String` +|=== + +The optional header to include at the top of each log file + +[#plugin-attr-footer] +==== `footer` + +[cols="2h,6"] +|=== +|Type |`String` +|=== + +The optional footer to include at the bottom of each log file + +[#plugin-attr-disableAnsi] +==== `disableAnsi` + +[cols="2h,6"] +|=== +|Type |`boolean` +|Default value |`false` +|=== + +If `true`, do not output ANSI escape codes + +[#plugin-attr-noConsoleNoAnsi] +==== `noConsoleNoAnsi` + +[cols="2h,6"] +|=== +|Type |`boolean` +|Default value |`false` +|=== + +If `true` and `System.console()` is null, do not output ANSI escape codes + +[#plugin-elements] +=== Plugin elements + +Pattern Layout plugin configuration accepts the following elements: + +[#plugin-element-RegexReplacement] +==== `RegexReplacement` + +Allows portions of the resulting `String` to be replaced. +This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates. + +It supports following attributes: + +`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string + +`replacement`:: The string to replace any matched substrings with + +[#plugin-element-PatternSelector] +==== `PatternSelector` + +Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`PatternSelector`] to allow it to choose a pattern to use based on attributes of the log event or other factors. +A `PatternSelector` will normally be configured with a `defaultPattern` attribute, which is used when other criteria don't match, and a set of link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected. + +Predefined ``PatternSelector``s are as follows: + +[#plugin-element-LevelPatternSelector] +===== `LevelPatternSelector` + +The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event. +Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event. + +[#plugin-element-MarkerPatternSelector] +===== `MarkerPatternSelector` + +The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[marker] included in the log event. +If the marker in the log event is equal to or is an ancestor of the name specified on the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used. + +Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`] +[source,xml] +---- +include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`] +[source,json] +---- +include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`] +[source,xml] +---- +include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`] +[source,xml] +---- +include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0] +---- +==== + +[#plugin-element-ScriptPatternSelector] +===== `ScriptPatternSelector` + +The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements. + +Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`] +[source,xml] +---- +include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`] +[source,json] +---- +include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`] +[source,xml] +---- +include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`] +[source,xml] +---- +include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0] +---- +==== + +[#converters] +=== Pattern converters + +The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details. +xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers. +The predefined set of pattern converters are shared below. Review Comment: Fixed in b95d668f7e9dfe7a7d5b7787be58f4a7b9b65a15. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
