This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/configuration in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit a330c6bca35922dcf47e5404fd4e8018122713fb Author: Piotr P. Karwasz <[email protected]> AuthorDate: Sun May 12 12:07:04 2024 +0200 Add arbiters and scripts --- .../examples/configuration/arbiters-select.json | 29 + .../configuration/arbiters-select.properties | 15 + .../examples/configuration/arbiters-select.xml | 22 + .../examples/configuration/arbiters-select.yaml | 18 + .../ROOT/examples/configuration/arbiters.json | 33 + .../examples/configuration/arbiters.properties | 16 + .../ROOT/examples/configuration/arbiters.xml | 20 + .../ROOT/examples/configuration/arbiters.yaml | 18 + .../ROOT/examples/configuration/scripts.json | 65 ++ .../ROOT/examples/configuration/scripts.properties | 51 ++ .../ROOT/examples/configuration/scripts.xml | 50 ++ .../ROOT/examples/configuration/scripts.yaml | 54 ++ .../examples/configuration/xinclude-appenders.xml | 9 + .../examples/configuration/xinclude-loggers.xml | 9 + .../ROOT/examples/configuration/xinclude-main.xml | 11 + src/site/antora/modules/ROOT/nav.adoc | 4 +- src/site/antora/modules/ROOT/pages/log4j-jul.adoc | 2 +- .../pages/log4j-spring-cloud-config-client.adoc | 4 +- .../modules/ROOT/pages/manual/appenders.adoc | 2 +- .../antora/modules/ROOT/pages/manual/async.adoc | 6 +- .../modules/ROOT/pages/manual/configuration.adoc | 551 +++++++++++++--- .../ROOT/pages/manual/configuration_old.adoc | 715 --------------------- .../modules/ROOT/pages/manual/garbagefree.adoc | 8 +- src/site/antora/modules/ROOT/pages/manual/jmx.adoc | 4 +- .../properties.adoc => systemproperties.adoc} | 0 25 files changed, 910 insertions(+), 806 deletions(-) diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.json b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.json new file mode 100644 index 0000000000..a30901cebd --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.json @@ -0,0 +1,29 @@ +{ + "Configuration": { + "Appenders": { + "File": { + "name": "MAIN", + "Select": { + "SystemPropertyArbiter": { // <1> + "propertyName": "env", + "propertyValue": "dev", + "PatternLayout": { + "pattern": "%d [%t] %p %c - %m%n" + } + }, + "DefaultArbiter": { // <2> + "JsonTemplateLayout": {} + } + } + } + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "MAIN" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.properties b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.properties new file mode 100644 index 0000000000..006414a3c2 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.properties @@ -0,0 +1,15 @@ +appender.0.type = File +appender.0.name = MAIN +appender.0.select.type = Select + +appender.0.select.0.type = SystemPropertyArbiter # <1> +appender.0.select.0.propertyName = env +appender.0.select.0.propertyValue = dev +appender.0.select.0.layout.type = PatternLayout +appender.0.select.0.layout.pattern = %d [%t] %p %c - %m%n + +appender.0.select.1.type = DefaultArbiter # <2> +appender.0.select.1.layout.type = JsonTemplateLayout + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = MAIN \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.xml b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.xml new file mode 100644 index 0000000000..a1afe26421 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.xml @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + <Appenders> + <File name="MAIN" fileName="logs/app.log"> + <Select> + <SystemPropertyArbiter propertyName="env" propertyValue="dev"> <!--1--> + <PatternLayout pattern="%d [%t] %p %c - %m%n"/> + </SystemPropertyArbiter> + <DefaultArbiter> <!--2--> + <JsonTemplateLayout/> + </DefaultArbiter> + </Select> + </File> + </Appenders> + <Loggers> + <Root level="INFO"> + <AppenderRef ref="MAIN"/> + </Root> + </Loggers> +</Configuration> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.yaml b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.yaml new file mode 100644 index 0000000000..1ddaed5a15 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters-select.yaml @@ -0,0 +1,18 @@ +Configuration: + Appenders: + File: + name: "MAIN" + fileName: "logs/app.log" + Select: + SystemPropertyArbiter: # <1> + propertyName: "env" + propertyValue: "dev" + PatternLayout: + pattern: "%d [%t] %p %c - %m%n" + DefaultArbiter: # <2> + JsonTemplateLayout: { } + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "MAIN" diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters.json b/src/site/antora/modules/ROOT/examples/configuration/arbiters.json new file mode 100644 index 0000000000..d732aaaa7a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters.json @@ -0,0 +1,33 @@ +{ + "Configuration": { + "Appenders": { + "File": { + "name": "MAIN", + "SystemPropertyArbiter": [ + // <1> + { + "propertyName": "env", + "propertyValue": "dev", + "PatternLayout": { + "pattern": "%d [%t] %p %c - %m%n" + } + }, + // <2> + { + "propertyName": "env", + "propertyValue": "prod", + "JsonTemplateLayout": {} + } + ] + } + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "MAIN" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters.properties b/src/site/antora/modules/ROOT/examples/configuration/arbiters.properties new file mode 100644 index 0000000000..7c4f664549 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters.properties @@ -0,0 +1,16 @@ +appender.0.type = File +appender.0.name = MAIN + +appender.0.arbiter[0].type = SystemPropertyArbiter # <1> +appender.0.arbiter[0].propertyName = env +appender.0.arbiter[0].propertyValue = dev +appender.0.arbiter[0].layout.type = PatternLayout +appender.0.arbiter[0].layout.pattern = %d [%t] %p %c - %m%n + +appender.0.arbiter[1].type = SystemPropertyArbiter # <2> +appender.0.arbiter[1].propertyName = env +appender.0.arbiter[1].propertyValue = prod +appender.0.arbiter[1].layout.type = JsonTemplateLayout + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = MAIN \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters.xml b/src/site/antora/modules/ROOT/examples/configuration/arbiters.xml new file mode 100644 index 0000000000..0e17becbe2 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters.xml @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + <Appenders> + <File name="MAIN" fileName="logs/app.log"> + <SystemPropertyArbiter propertyName="env" propertyValue="dev"> <!--1--> + <PatternLayout pattern="%d [%t] %p %c - %m%n"/> + </SystemPropertyArbiter> + <SystemPropertyArbiter propertyName="env" propertyValue="prod"> <!--2--> + <JsonTemplateLayout/> + </SystemPropertyArbiter> + </File> + </Appenders> + <Loggers> + <Root level="INFO"> + <AppenderRef ref="MAIN"/> + </Root> + </Loggers> +</Configuration> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/arbiters.yaml b/src/site/antora/modules/ROOT/examples/configuration/arbiters.yaml new file mode 100644 index 0000000000..4bb5c7bb17 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/arbiters.yaml @@ -0,0 +1,18 @@ +Configuration: + Appenders: + File: + name: "MAIN" + fileName: "logs/app.log" + SystemPropertyArbiter: + - propertyName: "env" # <1> + propertyValue: "dev" + PatternLayout: + pattern: "%d [%t] %p %c - %m%n" + - propertyName: "env" # <2> + propertyValue: "prod" + JsonTemplateLayout: { } + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "MAIN" diff --git a/src/site/antora/modules/ROOT/examples/configuration/scripts.json b/src/site/antora/modules/ROOT/examples/configuration/scripts.json new file mode 100644 index 0000000000..5a8aeaa484 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/scripts.json @@ -0,0 +1,65 @@ +{ + "Configuration": { + "Appenders": { + "Console": { + "name": "STDOUT", + "PatternLayout": { + "ScriptPatternSelector": { + "defaultPattern": "%d %p %m%n", + "ScriptRef": { + "ref": "selector", + "PatternMatch": [ + { + "key": "NoLocation", + "pattern": "[%-5level] %c{1.} %msg%n" + }, + { + "key": "Flow", + "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n" + } + ] + } + } + } + }, + "Loggers": { + "Logger": { + "name": "EventLogger", + "ScriptFilter": { + "onMatch": "ACCEPT", + "onMismatch": "DENY", + "Script": { + "name": "EventLogger-filter", + "language": "groovy", + "scriptText": "if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf(\"FLOW\"))) { return true; } else if (logEvent.getContextMap().containsKey(\"UserId\")) { return true; } return false;" + } + } + }, + "Root": { + "level": "INFO", + "ScriptFilter": { + "onMatch": "ACCEPT", + "onMismatch": "DENY", + "ScriptRef": { + "ref": "Root-filter" + } + }, + "AppenderRef": { + "ref": "STDOUT" + } + }, + "Scripts": { + "Script": { + "name": "selector", + "language": "javascript", + "scriptText": "var result; if (logEvent.getLoggerName().equals(\"JavascriptNoLocation\")) { result = \"NoLocation\"; } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf(\"FLOW\")) { result = \"Flow\"; } result;" + }, + "ScriptFile": { + "name": "Root-filter", + "path": "scripts/filter.groovy" + } + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/scripts.properties b/src/site/antora/modules/ROOT/examples/configuration/scripts.properties new file mode 100644 index 0000000000..d09c394977 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/scripts.properties @@ -0,0 +1,51 @@ +appender.0.type = Console +appender.0.name = STDOUT +appender.0.layout.type = PatternLayout + +appender.0.layout.selector = ScriptPatternSelector +appender.0.layout.selector.defaultPattern = %d %p %m%n +appender.0.layout.selector.scriptRef.type = ScriptRef +appender.0.layout.selector.scriptRef.ref = selector +appender.0.layout.selector.match[0].type = PatternMatch +appender.0.layout.selector.match[0].key = NoLocation +appender.0.layout.selector.match[0].pattern = [%-5level] %c{1.} %msg%n +appender.0.layout.selector.match[1].type = PatternMatch +appender.0.layout.selector.match[1].key = Flow +appender.0.layout.selector.match[1].pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n + +logger.0.name = EventLogger +logger.0.filter.0.type = ScriptFilter +logger.0.filter.0.onMatch = ACCEPT +logger.0.filter.0.onMismatch = DENY +logger.0.filter.0.script.type = Script +logger.0.filter.0.script.name = EventLogger-filter +logger.0.filter.0.script.language = groovy +logger.0.filter.0.script.scriptText = if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW"))) {\ + return true;\ + } else if (logEvent.getContextMap().containsKey("UserId")) {\ + return true;\ + }\ + return false; + +rootLogger.level = INFO +rootLogger.filter.0.type = ScriptFilter +rootLogger.filter.0.onMatch = ACCEPT +rootLogger.filter.0.onMismatch = DENY +rootLogger.filter.0.scriptRef.type = ScriptRef +rootLogger.filter.0.scriptRef.ref = Root-Filter +rootLogger.appenderRef.0.ref = STDOUT + +script.0.type = Script +script.0.name = selector +script.0.language = javascript +script.0.scriptText = var result;\ + if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {\ + result = "NoLocation";\ + } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {\ + result = "Flow";\ + }\ + result; + +script.1.type = ScriptFile +script.1.name = Root-filter +script.1.path = scripts/filter.groovy diff --git a/src/site/antora/modules/ROOT/examples/configuration/scripts.xml b/src/site/antora/modules/ROOT/examples/configuration/scripts.xml new file mode 100644 index 0000000000..4334eb7c82 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/scripts.xml @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8"?> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + <Appenders> + <Console name="STDOUT"> + <PatternLayout> + <ScriptPatternSelector defaultPattern="%d %p %m%n"> + <ScriptRef ref="selector"/> + <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/> + <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/> + </ScriptPatternSelector> + </PatternLayout> + </Console> + </Appenders> + <Loggers> + <Logger name="EventLogger"> + <ScriptFilter onMatch="ACCEPT" onMismatch="DENY"> + <Script name="EventLogger-filter" language="groovy"><![CDATA[ + if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { + return true; + } else if (logEvent.getContextMap().containsKey("UserId")) { + return true; + } + return false; + ]]> + </Script> + </ScriptFilter> + </Logger> + <Root level="INFO"> + <ScriptFilter onMatch="ACCEPT" onMismatch="DENY"> + <ScriptRef ref="Root-filter"/> + </ScriptFilter> + <AppenderRef ref="STDOUT"/> + </Root> + </Loggers> + <Scripts> + <Script name="selector" language="javascript"><![CDATA[ + var result; + if (logEvent.getLoggerName().equals("JavascriptNoLocation")) { + result = "NoLocation"; + } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { + result = "Flow"; + } + result; + ]]> + </Script> + <ScriptFile name="Root-filter" path="scripts/filter.groovy"/> + </Scripts> +</Configuration> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/scripts.yaml b/src/site/antora/modules/ROOT/examples/configuration/scripts.yaml new file mode 100644 index 0000000000..de5252dcd7 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/scripts.yaml @@ -0,0 +1,54 @@ +Configuration: + Appenders: + Console: + name: "STDOUT" + PatternLayout: + ScriptPatternSelector: + defaultPattern: "%d %p %m%n" + ScriptRef: + ref: "selector" + PatternMatch: + - key: "NoLocation" + pattern: "[%-5level] %c{1.} %msg%n" + - key: "Flow" + pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n" + Loggers: + Logger: + name: "EventLogger" + ScriptFilter: + onMatch: "ACCEPT" + onMismatch: "DENY" + Script: + name: "EventLogger-filter" + language: "groovy" + scriptText: | + if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { + return true; + } else if (logEvent.getContextMap().containsKey("UserId")) { + return true; + } + return false; + Root: + level: "INFO" + ScriptFilter: + onMatch: "ACCEPT" + onMismatch: "DENY" + ScriptRef: + ref: "Root-filter" + AppenderRef: + ref: "STDOUT" + Scripts: + Script: + name: "selector" + language: "javascript" + scriptText: | + var result; + if (logEvent.getLoggerName().equals("JavascriptNoLocation")) { + result = "NoLocation"; + } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { + result = "Flow"; + } + result; + ScriptFile: + name: "Root-filter" + path: "scripts/filter.groovy" diff --git a/src/site/antora/modules/ROOT/examples/configuration/xinclude-appenders.xml b/src/site/antora/modules/ROOT/examples/configuration/xinclude-appenders.xml new file mode 100644 index 0000000000..2a12906169 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/xinclude-appenders.xml @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<Appenders> + <Console name="StdOut"> + <PatternLayout pattern="%d %m%n"/> + </Console> + <File name="File" fileName="${filename}"> + <PatternLayout pattern="%d %p %C{1.} [%t] %m%n"/> + </File> +</Appenders> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/xinclude-loggers.xml b/src/site/antora/modules/ROOT/examples/configuration/xinclude-loggers.xml new file mode 100644 index 0000000000..408560cb9f --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/xinclude-loggers.xml @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<Loggers> + <Rogger name="org.example" level="DEBUG" additivity="false"> + <AppenderRef ref="File" /> + </Rogger> + <Root level="ERROR"> + <AppenderRef ref="StdOut" /> + </Root> +</Loggers> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/configuration/xinclude-main.xml b/src/site/antora/modules/ROOT/examples/configuration/xinclude-main.xml new file mode 100644 index 0000000000..130b9ada71 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/configuration/xinclude-main.xml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xi="http://www.w3.org/2001/XInclude"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + <Properties> + <Property name="filename" value="app.log"/> + </Properties> + <xi:include href="xinclude-appenders.xml"/> + <xi:include href="xinclude-loggers.xml"/> +</Configuration> \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index b7789787fd..218fec5959 100644 --- a/src/site/antora/modules/ROOT/nav.adoc +++ b/src/site/antora/modules/ROOT/nav.adoc @@ -41,6 +41,9 @@ ** xref:manual/scoped-context.adoc[] ** xref:manual/resource-logger.adoc[] * xref:manual/configuration.adoc[] +** xref:manual/configuration.adoc#configuration-file[Configuration file] +** xref:manual/customconfig.adoc[] +** xref:manual/systemproperties.adoc[] * xref:manual/usage.adoc[] * xref:manual/cloud.adoc[] * xref:manual/lookups.adoc[] @@ -52,7 +55,6 @@ * xref:manual/garbagefree.adoc[] * xref:manual/extending.adoc[] * xref:manual/plugins.adoc[] -* xref:manual/customconfig.adoc[] * xref:manual/customloglevels.adoc[] * xref:manual/jmx.adoc[] * xref:manual/logsep.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc index e141ea0613..d6974a822e 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc @@ -55,7 +55,7 @@ plugin. Java logging levels are translated into Log4j logging levels dynamically. The following table lists the conversions between a Java logging level and its equivalent Log4j level. Custom levels should be implemented as an implementation of `LevelConverter`, and the Log4j property -xref:manual/configuration/properties.adoc#log4j2.julLevelConverter[log4j2.julLevelConverter] +xref:manual/systemproperties.adoc#log4j2.julLevelConverter[log4j2.julLevelConverter] must be set to your custom class name. Using the default `LevelConverter` implementation, custom logging levels are mapped to whatever the current level of the `Logger` being logged to is using. diff --git a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc index 5eca408a29..ce8e4b31ca 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc @@ -25,7 +25,7 @@ Spring Boot applications initialize logging 3 times. . SpringApplication declares a Logger. This Logger will be initialized using Log4j's "normal" mechanisms. Thus, the -xref:manual/configuration/properties.adoc#log4j2.configurationFile[`log4j2.configurationFile`] +xref:manual/systemproperties.adoc#log4j2.configurationFile[`log4j2.configurationFile`] system property will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath. The property may also be declare in log4j2.component.properties. @@ -125,7 +125,7 @@ Note that Log4j currently does not directly support encrypting the password. However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well. If more extensive authentication is required an `AuthorizationProvider` can be implemented and its fully qualified class name should be specified in the -xref:manual/configuration/properties.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] +xref:manual/systemproperties.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in log4j2.component.properties or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` or `logging.auth.authorizationProvider` key. For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[the Transport Security configuration]. diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc index 1431c9b49d..07fca6666e 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc @@ -120,7 +120,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy` +xref:manual/systemproperties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy` and `log4j2.DiscardThreshold`]. A typical AsyncAppender configuration might look like: diff --git a/src/site/antora/modules/ROOT/pages/manual/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc index 53e8e9f24f..c334ccb2f0 100644 --- a/src/site/antora/modules/ROOT/pages/manual/async.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/async.adoc @@ -117,7 +117,7 @@ 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. -To make all loggers asynchronous, add the disruptor jar to the classpath and set the system property xref:manual/configuration/properties.adoc#log4j2.contextSelector[log4j2.contextSelector] to `org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` or `org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector`. +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 asynchronous loggers. If one of your layouts or custom filters needs @@ -183,7 +183,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` +xref:manual/systemproperties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` and `log4j2.discardThreshold`]. [#MixedSync-Async] @@ -257,7 +257,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` +xref:manual/systemproperties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` and `log4j2.discardThreshold`]. [#custom-waitstrategy] diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc index 3f64c8b866..a3ed9b7899 100644 --- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc @@ -14,25 +14,28 @@ See the License for the specific language governing permissions and limitations under the License. //// +[id=configuration] = Configuration +Ralph Goers <[email protected]>; Piotr Karwasz <[email protected]> + Since logging is a common way to monitor the health of an application and diagnose problems that occur in it, even moderately sized applications can contain thousands of logging statements. In order to decide which of these statements will be logged and where, users need to configure Log4j Core. Log4j Core can be configured in two ways: -* through a <<log4j-core-configuration-file>>. +* through a <<configuration-file>>. Since version 2.0 the configuration file format is considered as part of the public API, and it remains stable even across major version upgrades. -* through <<log4j-core-programmatic-configuration>>, which provides a larger spectrum of possible customizations, but might require code changes even for minor version upgrades, according to https://semver.org/[semantic versioning] rules. +* through xref:manual/customconfig.adoc[Programmatic Configuration], which provides a larger spectrum of possible customizations, but might require code changes even for minor version upgrades, according to https://semver.org/[semantic versioning] rules. [NOTE] ==== -To prevent a chicken-and-egg problem some configuration options, such as the location of the configuration file can be supplied only through xref:manual/configuration/properties.adoc[System properties]. +To prevent a chicken-and-egg problem some configuration options, such as the location of the configuration file can be supplied only through xref:manual/systemproperties.adoc[System properties]. ==== -[#log4j-core-configuration-file] +[#configuration-file] == Configuration file TIP: For a quick example of configuration file see the xref:manual/installation.adoc#impl-core-config[Configuring Log4j Core section]. @@ -53,7 +56,7 @@ To enable partial support for old configuration formats see xref:manual/migratio ==== [id=automatic-configuration] -=== Configuration file location +=== [[AutomaticConfiguration]] Configuration file location Upon initialization of a new logger context, Log4j assigns it a context name and scans the following **classpath** locations for a configuration file: @@ -63,7 +66,7 @@ Upon initialization of a new logger context, Log4j assigns it a context name and . Files named `log4j2.<extension>`, . If no configuration file could be located a link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration] is used and a warning is printed by the status logger. The default configuration prints all messages less specific than -xref:manual/configuration/properties.adoc#log4j2.level[log4j2.level] +xref:manual/systemproperties.adoc#log4j2.level[log4j2.level] to the console. [CAUTION] @@ -107,14 +110,15 @@ See xref:manual/webapp.adoc#configuration[Log4j [NOTE] ==== It is also possible to override the location of the configuration file using the -xref:./configuration/properties.adoc#log4j2.configurationFile[log4j2.configurationFile] +xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurationFile] configuration property. In this case Log4j will guess the configuration file format from the extension of the provided configuration file or will use the default configuration factory if the extension is unknown. -See xref:./configuration/properties.adoc#log4j2.configurationFile[log4j2.configurationFile] for details. +See xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurationFile] for details. ==== -=== Syntax +[id=configuration-syntax] +=== [[ConfigurationSyntax]] Syntax All configuration files are parsed into a tree of link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node[Node]s, each representing a different Log4j component. The root of the tree creates a link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration[Configuration] object. @@ -239,41 +243,12 @@ In the Java properties configuration format: ==== The id assigned to nested components is only used for sorting purposes. However, some components assign a special meaning to some ids. -See a list of exceptions below: -==== -+ -.Properties format quirks -[%collapsible,#properties-format-quirks] +See a list of exceptions in <<java-properties-features>>. ==== -The Java properties configuration format is by far the most verbose of the available formats. -In order to make it more usable a series of exceptions to the rules in <<configuration-with-properties,Java properties syntax>> have been introduced over time: -. The following direct children of `Configuration` have predefined prefixes and do not require to specify a `type` -attribute: -* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-AppendersPlugin[Appender container] has a predefined `appender` prefix. -* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-CustomLevels[Custom levels container] has a predefined `customLevel` prefix. -* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggersPlugin[Loggers container] has a predefined `logger` prefix. -* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-PropertiesPlugin[Properties container] has a predefined `property` prefix. -* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts container] has a predefined `script` prefix. -. Properties that start with `property` are used for <<property-substitution>>. -Their syntax is `property.<key> = <value>`. -. The root logger can be configured using properties that start with `rootLogger`. -. A shorthand notation is available that allows users to write: -+ ----- -rootLogger = INFO, APPENDER ----- -+ -instead of: -+ ----- -rootLogger.level = INFO -rootLogger.appenderRef.0.ref = APPENDER ----- -. All the keys of the form `logger.<name>.appenderRef.<id>`, where `<name>` and `<id>` are arbitrary, are considered appender references. -==== ===== +[id=main-configuration-elements] === Main configuration elements Log4j Core's logging pipeline is quite complex (see xref:manual/architecture.adoc[Architecture]), but most users only require these elements: @@ -282,19 +257,26 @@ Loggers:: + Loggers are the entry point of the logging pipeline, directly used in code. Their configuration must specify which level of messages they log and to which appenders they send the messages. ++ +See <<configuring-loggers>> for details. -Appenders:: +[id=configuring-appenders] +[[Appenders]] Appenders:: + Appenders are the exit point of the logging pipeline. They decide to which resource (console, file, database, etc.) the log event is sent. -For a complete list see xref:manual/appenders.adoc[Appenders]. -In this chapter we will only use the xref:manual/appenders.adoc#consoleappender[console appender] and the xref:manual/appenders.adoc#fileappender[file appender] in the examples. +In the examples of this chapter we will only use the xref:manual/appenders.adoc#consoleappender[console appender] and the xref:manual/appenders.adoc#fileappender[file appender] in the examples. ++ +See xref:manual/appenders.adoc[Appender configuration] for details. Layouts:: + Layouts tell appenders how they should format the log event: text, JSON, XML, etc. -For a complete list see xref:manual/layouts.adoc[Layouts]. -In this chapter we will only use the xref:manual/layouts.adoc#pattern-layout[textual pattern layout] and xref:manual/json-template-layout.adoc[JSON template layout] in the examples. +In the examples of this chapter we will only use the xref:manual/layouts.adoc#pattern-layout[textual pattern layout] +and +xref:manual/json-template-layout.adoc[JSON template layout] in the examples. ++ +See xref:manual/layouts.adoc[Layout configuration] for details. A moderately complex configuration might look like this: @@ -367,6 +349,34 @@ The logger is configured to forward messages to its parent (the root appender). |=== +[id=additional-configuration-elements] +=== Additional configuration elements + +A Log4j Core configuration file can also contain these configuration elements: + +CustomLevels:: ++ +Log4j allows to configure custom level names. ++ +See xref:manual/customloglevels.adoc[Custom log level configuration] for details. + +Filters:: ++ +Components that can be added to loggers, appender references, appenders or the global configuration object to provide additional filtering of log events. ++ +See xref:manual/filters.adoc[Filter configuration] for details. + +Properties:: ++ +A set of reusable configuration values for property substitution. ++ +See <<property-substitution>> for details. + +Scripts:: ++ +See <<scripts>> for details. + +[id=global-configuration-attributes] === Global configuration attributes The main `Configuration` element has a set of attributes that can be used to tune the way the configuration file itself is used. @@ -374,7 +384,7 @@ The principal attributes are listed below. See xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration[Plugin reference] for a complete list. [id=configuration-attribute-monitorInterval] -==== `monitorInterval` +==== [[AutomaticReconfiguration]] `monitorInterval` [cols="1h,5"] |=== @@ -384,14 +394,19 @@ See xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-lo Determines the polling interval used by Log4j to check for changes to the configuration file. +If a change in the configuration file is detected, Log4j automatically reconfigures the logger context. + If set to `0`, polling is disabled. -[NOTE] +[CAUTION] ==== -Unlike other logging backends Log4j Core is designed with audit logging in mind. +Unlike other logging backends Log4j Core is designed with **audit** logging in mind. During a reconfiguration process, no messages are lost. + Unless the new configuration file removes an appender, the old one continues to work without interruption. +This behavior also implies that changes to appenders that modify the options of the resource used by the appender (e.g. a change in the `append` attribute of a file appender) will be **ignored**. +In order to modify these options during a reconfiguration you also need to change the resource used by the appender (e .g. the file name used by a file appender). ==== [id=configuration-attribute-status] @@ -401,42 +416,23 @@ Unless the new configuration file removes an appender, the old one continues to |=== | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL] | Status | **DEPRECATED** -| Default value (since 2.24.0) | xref:./configuration/properties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] +| Default value (since 2.24.0) | xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] | Default value (before 2.24.0) | value of `log4j2.defaultStatusLevel` |=== Overrides the logging level of the status logger. WARNING: Since 2.24.0 this attribute is deprecated and will be replaced with the -xref:./configuration/properties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] +xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property. -[id=configuration-attribute-schema] -==== `schema` - -[cols="1h,5"] -|=== -| Type | classpath resource -| Default value | `null` -|=== - -[id=configuration-attribute-strict] -==== `strict` - -[cols="1h,5"] -|=== -| Type | `boolean` -| Default value | `false` -|=== - -If set to `true` all configuration files will be checked against. - [id=configuration-elements-filters] ==== Filters See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to the global configuration object. -=== Logger configuration +[id=configuring-loggers] +=== [[Loggers]] Loggers Log4j 2 contains multiple types of logger components that can be added to the `Loggers` element of the configuration: @@ -459,7 +455,7 @@ See also xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apac Every configuration **must** have at least a `Root` or `AsyncRoot` element. The presence of other logger configurations is optional. -The logger components can have the following attributes and elements: +The logger components can have the following configuration attributes and elements: [id=logger-attributes-name] ==== `name` @@ -475,7 +471,7 @@ Specifies the name of the logger configuration. Since loggers are usually named using fully qualified class names, this value usually contains the fully qualified name of a class or a package. [id=logger-attributes-additivity] -==== `additivity` +==== [[Additivity]] `additivity` [cols="1h,5"] |=== @@ -494,7 +490,7 @@ If `true` (default), all the messages received by this logger will also be trans | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level] | Default value a| -* xref:./configuration/properties.adoc#log4j2.level[log4j2.level], +* xref:manual/systemproperties.adoc#log4j2.level[log4j2.level], for `Root` and `AsyncRoot`, * inherited from the parent logger, for `Logger` and `AsyncLogger`. |=== @@ -518,7 +514,7 @@ a| ** `false` for `AsyncRoot` and `AsyncLogger`. See -xref:./configuration/properties.adoc#log4j2.contextSelector[log4j2.contextSelector] +xref:manual/systemproperties.adoc#log4j2.contextSelector[log4j2.contextSelector] for more details. |=== @@ -534,6 +530,13 @@ This setting only applies to computation of location at **runtime**. If the location is computed at build time using link:/log4j/transform/latest/#log4j-transform-maven-plugin[Log4j Transform Maven Plugin] this setting is ignored and location information will always be available for logging. ==== +[id=logger-elements-appenderrefs] +==== Appender references + +Loggers use appender references to list the appenders to use to deliver log events. + +See <<configuring-appenderrefs>> below for more details. + [id=logger-elements-properties] ==== Additional context properties @@ -585,6 +588,43 @@ include::example$configuration/logger-properties.properties[tag=loggers] See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration. +[id=configuring-appenderrefs] +=== Appender references + +Many Log4j components such as loggers use appender references to designate, which appenders will be used to deliver their events. + +Unlike Log4j 1, where appender references were simple pointers, in Log4j 2 they have additional filtering capabilities. + +Appender references can have the following configuration attributes and elements: + +[id=appenderref-attributes-name] +==== `ref` + +[cols="1h,5"] +|=== +| Type | `String` +|=== + +Specifies the name of the appender to use. + +[id=appenderref-attributes-level] +==== `level` + +[cols="1h,5"] +|=== +| Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level] +|=== + +Specifies the level threshold that a log event must have to be logged. +Log events more specific than this setting will be filtered out. + +See also xref:manual/filters.adoc#filters[Filters] if you require additional filtering. + +[id=appenderrefs-elements-filters] +==== Filters + +See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration. + [id=property-substitution] === Property substitution @@ -744,5 +784,362 @@ include::example$configuration/routing.properties[tag=appender] Therefore, the dollar `$` sign needs to be escaped. <2> All the attributes inside the `File` element have a **deferred** evaluation, therefore they need only one `$` sign. -[#log4j-core-programmatic-configuration] -== Programmatic configuration \ No newline at end of file +[id=arbiters] +=== [[Arbiters]] Arbiters + +While property substitution allows to use the same configuration file in multiple deployment environments, sometimes changing the values of configuration attributes is not enough. + +Arbiters are to configuration elements what property substitution is for configuration attributes: they allow to conditionally add a subtree of configuration elements to a configuration file. + +Arbiters may occur anywhere an element is allowed in the configuration and can be nested. +So an Arbiter could encapsulate something as simple as a single property declaration or a whole set of appenders, loggers or other arbiters. +The child elements of an arbiter must be valid elements for whatever element is the parent of the arbiter. + +For a complete list of available arbiters see +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-Arbiter[plugin reference]. +In the examples below we'll just use the +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-DefaultArbiter[DefaultArbiter], +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SelectArbiter[Select] +and +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SystemPropertyArbiter[SystemPropertyArbiter]. + +For example, you might want to use a different layout in a production and development environment: + +[tabs] +==== +XML:: ++ +[source,xml] +---- +include::example$configuration/arbiters.xml[] +---- + +JSON:: ++ +[source,json] +---- +include::example$configuration/arbiters.json[] +---- + +YAML:: ++ +[source,yaml] +---- +include::example$configuration/arbiters.yaml[] +---- + +Java properties:: ++ +[source,properties] +---- +include::example$configuration/arbiters.properties[] +---- +==== + +<1> If the Java system property `env` has a value of `dev`, a pattern layout will be used. +<2> If the Java system property `env` has a value of `prod`, a JSON template layout will be used. + +The above example has a problem: if the Java system property `env` has a value different from `dev` or `prod`, the appender will have no layout. + +This is a case, when the `Select` plugin is useful: this configuration element contains a list of arbiters and a +`DefaultArbiter` element. +If none of the arbiters match, the configuration from the `DefaultArbiter` element will be used: + +[tabs] +==== +XML:: ++ +[source,xml] +---- +include::example$configuration/arbiters-select.xml[] +---- + +JSON:: ++ +[source,json] +---- +include::example$configuration/arbiters-select.json[] +---- + +YAML:: ++ +[source,yaml] +---- +include::example$configuration/arbiters-select.yaml[] +---- + +Java properties:: ++ +[source,properties] +---- +include::example$configuration/arbiters-select.properties[] +---- +==== + +<1> If the Java system property `env` has a value of `dev`, a pattern layout will be used. +<2> Otherwise, a JSON template layout will be used. + +[#CompositeConfiguration] +=== Composite Configuration + +Log4j allows multiple configuration files to be used at the same time by specifying them as a list of comma separated file paths or URLs in the +xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurationFile] +configuration property. + +These configuration files are merged into a single configuration file using +link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy.html[MergeStrategy] +service that can be customized using the +xref:manual/systemproperties.adoc#log4j2.mergeStrategy[log4j2.mergeStrategy] +configuration property. + +The default merge strategy will merge the files using the following rules: + +. <<global-configuration-attributes>> in later configurations replace those in previous configurations. ++ +The exception is the `monitorInterval` attribute: the lowest positive value from all the configuration files will be used. + +. <<property-substitution,Properties>> from all configurations are aggregated. +Duplicate properties replace those in previous configurations. + +. xref:manual/filters.adoc[Filters] are aggregated under +xref:manual/filters.adoc#CompositeFilter[CompositeFilter], if more than one filter is defined. + +. <<scripts,Scripts>> are aggregated. +Duplicate definitions replace those in previous configurations. + +. xref:manual/appenders.adoc[Appenders] are aggregated. +Appenders with the same name are **replaced** by those in later configurations, including all their elements. + +. <<configuring-loggers,Loggers>> are all aggregated. +Logger attributes are individually merged with duplicates being replaced by those in later configurations. +Appender references on a logger are aggregated with duplicates being replaced by those in later configurations. +The strategy merges filters on loggers using the rule above. + +[id=scripts] +=== [[Scripts]] Scripts + +Log4j provides support for +https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR +223] scripting languages to be used in some of its components. + +[WARNING] +==== +In order to enable a scripting language, its name must be included in the +xref:manual/systemproperties.adoc#log4j2.scriptEnableLanguages[log4j2.scriptEnableLanguages] +configuration property. +==== + +Each component that allows scripts can contain on of the following configuration elements: + +Script:: ++ +This element specifies the content of the script directly and has: ++ +-- +* a required `language` configuration attribute that specifies the name of the JSR 223 language to use, +* a required `scriptText` configuration attribute that contains the text of the script. +In the XML configuration format, the text of the script can also be written as content of the `<Script>` XML element. +This allows the usage of a `CDATA` block. +-- ++ +The element can be assigned a name using the `name` configuration attribute. ++ +See also +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-Script[Plugin reference]. + +ScriptFile:: ++ +This element points to an external script file and has: ++ +-- +* a required `path` attribute that points to the path to a file name. +* an optional `language` attribute that specifies the name of the JSR 223 language to use. +If not provided, the language is deduced from the extension of the file. +* an optional `isWatched` attribute. +If set to `true` the script file will be monitored for changes. +-- ++ +The element can be assigned a name using the `name` configuration attribute. ++ +See also +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptFile[Plugin reference]. + +ScriptRef:: ++ +This element references a **named** script from the global +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts] +container plugin in the configuration file. ++ +See also +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptRef[Plugin reference]. + +The environment in which the script runs is different for each Log4j script-based component. + +[tabs] +==== +XML:: ++ +[source,xml] +---- +include::example$configuration/scripts.xml[] +---- + +JSON:: ++ +[source,json] +---- +include::example$configuration/scripts.json[] +---- + +YAML:: ++ +[source,yaml] +---- +include::example$configuration/scripts.yaml[] +---- + +Java properties:: ++ +[source,properties] +---- +include::example$configuration/scripts.properties[] +---- +==== + +[id=a-special-note-on-beanshell] +==== A special note on Beanshell + +JSR 223 scripting engines are supposed to identify that they support the +https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/Compilable.html[Compilable] +interface if they support compiling their scripts. + +Beanshell does extend the `Compilable` interface, but an attempt to compile a script ends up in an +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Error.html[Error] +being thrown. +Log4j catches the throwable, but issues a warning in the status logger. + +---- +2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable +2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error: unimplemented + at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175) + at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154) + at org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125) + at org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94) +---- + +[id=format-specific-notes] +=== Format specific notes + +[id=xml-features] +==== XML format + +[id=xml-global-configuration-attributes] +===== Global configuration attributes + +The XML format supports the following additional attributes on the `Configuration` element. + +[id=configuration-attribute-schema] +====== `schema` + +[cols="1h,5"] +|=== +| Type | classpath resource +| Default value | `null` +|=== + +Specifies the path to a classpath resource containing an XML schema. + +[id=configuration-attribute-strict] +====== `strict` + +[cols="1h,5"] +|=== +| Type | `boolean` +| Default value | `false` +|=== + +If set to `true` all configuration files will be checked against the XML schema provided by the +<<configuration-attribute-schema>>. + +This setting also enables "XML strict mode" and allows to specify the **plugin type** of an element through a `type` attribute instead of the tag name. + +[id=xinclude] +===== [[XInlcude]] XInclude + +XML configuration files can include other files with +https://www.w3.org/TR/xinclude/[XInclude]. + +NOTE: The list of `XInclude` and `XPath` features supported depends upon your +https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/xml/jaxp/index.html[JAXP implementation]. + +Here is an example log4j2.xml file that includes two other files: + +.log4j2.xml +[source,xml] +---- +include::example$configuration/xinclude-main.xml[] +---- + +.xinclude-appenders.xml +[source,xml] +---- +include::example$configuration/xinclude-appenders.xml[] +---- + +.xinclude-loggers.xml +[source,xml] +---- +include::example$configuration/xinclude-loggers.xml[] +---- + +[id=java-properties-features] +==== Java properties format + +The Java properties configuration format is by far the most verbose of the available formats. +In order to make it more usable a series of exceptions to the rules in <<configuration-with-properties,Java properties syntax>> have been introduced over time: + +. The following direct children of `Configuration` have predefined prefixes and do not require to specify a `type` +attribute: +* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-AppendersPlugin[Appender container] has a predefined `appender` prefix. +* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-CustomLevels[Custom levels container] has a predefined `customLevel` prefix. +* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggersPlugin[Loggers container] has a predefined `logger` prefix. +* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-PropertiesPlugin[Properties container] has a predefined `property` prefix. +* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts container] has a predefined `script` prefix. + +. Properties that start with `property` are used for <<property-substitution>>. +Their syntax is: ++ +[source,properties] +---- +property.<key> = <value> +---- + +. Properties that start with `customLevel` are used to define custom levels Their syntax is: ++ +[source,properties] +---- +customLevel.<name> = <intValue> +---- ++ +where `<name>` is the name of the level and `<intValue>` its numerical value. + +. The root logger can be configured using properties that start with `rootLogger`. + +. A shorthand notation is available that allows users to write: ++ +[source,properties] +---- +rootLogger = INFO, APPENDER +---- ++ +instead of: ++ +[source,properties] +---- +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = APPENDER +---- + +. All the keys of the form `logger.<name>.appenderRef.<id>`, where `<name>` and `<id>` are arbitrary, are considered appender references. + +. To add a filter to a component use a `filter.<id>` prefix instead of just `<id>`. \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration_old.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration_old.adoc deleted file mode 100644 index d34d313fcd..0000000000 --- a/src/site/antora/modules/ROOT/pages/manual/configuration_old.adoc +++ /dev/null @@ -1,715 +0,0 @@ -//// - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -//// -[#configuration] -= Configuration -Ralph Goers <[email protected]> - -[#Arbiters] -== Arbiters - -In some situations it is desirable to have a single logging configuration that can be used in any -deployment environment. For example, it may be necessary to have a different default logging level in -production then in development. Another case might be where one type of appender is used when running -natively but another is used when deployed to a docker container. One way to handle that is to use -a tool such as Spring Cloud Config Server that can be environment aware and serve a different file for -each environment. Another option is to include Arbiters in the configuration. - -An Arbiter is a Log4j plugin that has the job of determining whether other configured elements should be -included in the generated configuration. While all other "Core" plugins are designed to execute as part of -Log4j's runtime logic Arbiters execute after the Node tree has been constructed but before the tree is -converted to a configuration. An Arbiter is a Node itself which is always removed from the Node tree -before it the tree is processed. All an arbiter really does is provide a method that returns a boolean -result that determines whether the child nodes of the arbiter should remain in the configuration or be -pruned. - -Arbiters may occur anywhere an element is allowed in the configuration. So an Aribiter could encapsulate -something as simple as a single property declaration or a whole set of Appenders or Loggers. Arbiters -may also be nested although Arbiters that are the descendant of another arbiter will only be evalued if the -ancestor returned true. The child elements of an Arbiter must be valid elements for whatever element is -the parent of the Arbiter. - -This example shows two Arbiters configured that will include either a Console Appender or a List Appender -depending on whether the value of the env System Property is "dev" or "prod". - -[source,xml] ----- -<Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> - <Appenders> - - <SystemPropertyArbiter propertyName="env" propertyValue="dev"> - <Console name="Out"> - <PatternLayout pattern="%m%n"/> - </Console> - </SystemPropertyArbiter> - <SystemPropertyArbiter propertyName="env" propertyValue="prod"> - <List name="Out"> - </List> - </SystemPropertyArbiter> - - </Appenders> - <Loggers> - <Logger name="org.apache.test" level="trace" additivity="false"> - <AppenderRef ref="Out"/> - </Logger> - <Root level="error"> - <AppenderRef ref="Out"/> - </Root> - </Loggers> -</Configuration> ----- - -Normally Arbiters act in isolation from other Arbiters. That is, the outcome of one Arbiter will not -impact any other Arbiters. This can be cumbersome when you simply want to use one of a set of choices. A -special plugin named "Select" can be used in this case. Each element under the Select is required to be -an Arbiter. The first Arbiter that returns a true value will be the one used while others are ignored. -If no Arbiter returns true a DefaultAtrbiter may be configured with the default configuration elements. -The DefaultArbiter is an Arbiter that always returns true, so using it outside of a Select would result in -its configured elements always being included just as if it hadn't been present. - -This example shows an Arbiter that uses Javascript residing in a separate file to determine whether to -include the Console Appender. If the result is false then a List Appender will be included. - -[source,xml] ----- -<Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> - <Appenders> - <Select> - <ScriptArbiter> - <ScriptFile language="JavaScript" path="src/test/resources/scripts/prodtest.js" charset="UTF-8" /> - <Console name="Out"> - <PatternLayout pattern="%m%n"/> - </Console> - </ScriptArbiter> - <DefaultArbiter> - <List name="Out"> - </List> - </DefaultArbiter> - </Select> - </Appenders> - <Loggers> - <Logger name="org.apache.test" level="trace" additivity="false"> - <AppenderRef ref="Out"/> - </Logger> - <Root level="error"> - <AppenderRef ref="Out"/> - </Root> - </Loggers> -</Configuration> ----- - -Natively Log4j contains the SystemProperty Arbiter that can evaluate whether to include elements based on -whether a SystemProperty is non-null or has a specific value, a ClassArbiter that makes its decision -based on whether the specified class is present, and a ScriptArbiter that makes its decision based -on the result of the script configured with it. - -For Spring Boot users an Arbiter named <code>SpringProfile</code> has been provided. The specified profiles -are evaluated by Spring's <code>Environment.acceptsProfiles()</code> method, so any expressions it supports -may be used as the name attribute. - -This example will use a Console Appender when the Spring profile is "dev" or "staging" and a List -Appender when the active profile is "prod". - -[source,xml] ----- -<Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> - <Appenders> - - <SpringProfile name="dev | staging"> - <Console name="Out"> - <PatternLayout pattern="%m%n"/> - </Console> - </SpringProfile> - <SpringProfile name="prod"> - <List name="Out"> - </List> - </SpringProfile> - - </Appenders> - <Loggers> - <Logger name="org.apache.test" level="trace" additivity="false"> - <AppenderRef ref="Out"/> - </Logger> - <Root level="error"> - <AppenderRef ref="Out"/> - </Root> - </Loggers> -</Configuration> ----- - -* A -link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/ConsoleAppender.html[`ConsoleAppender`] -attached to the root logger. -* A -link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`] -set to the pattern "%d\{HH:mm:ss.SSS} [%t] %-5level %logger\{36} - -%msg%n" attached to the ConsoleAppender - -Note that by default Log4j assigns the root logger to `Level.ERROR`. - -The output of MyApp would be similar to: - -.... -17:13:01.540 [main] ERROR com.foo.Bar - Did it again! -17:13:01.540 [main] ERROR MyApp - Didn't do it. -.... - -As was described previously, Log4j will first attempt to configure -itself from configuration files. A configuration equivalent to the -default would look like: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="WARN"> - <Appenders> - <Console name="Console" target="SYSTEM_OUT"> - <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/> - </Console> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="Console"/> - </Root> - </Loggers> -</Configuration> ----- - -Once the file above is placed into the classpath as log4j2.xml you will -get results identical to those listed above. Changing the root level to -trace will result in results similar to: - -.... -17:13:01.540 [main] TRACE MyApp - Entering application. -17:13:01.540 [main] TRACE com.foo.Bar - entry -17:13:01.540 [main] ERROR com.foo.Bar - Did it again! -17:13:01.540 [main] TRACE com.foo.Bar - exit with (false) -17:13:01.540 [main] ERROR MyApp - Didn't do it. -17:13:01.540 [main] TRACE MyApp - Exiting application. -.... - -Note that status logging is disabled when the default configuration is -used. - -[#Additivity] -== Additivity - -Perhaps it is desired to eliminate all the TRACE output from everything -except `com.foo.Bar`. Simply changing the log level would not accomplish -the task. Instead, the solution is to add a new logger definition to the -configuration: - -[source,xml] ----- -<Configuration> - <!-- ... --> - <Logger name="com.foo.Bar" level="TRACE"/> - <Root level="ERROR"> - <AppenderRef ref="STDOUT"/> - </Root> -</Configuration> ----- - -With this configuration all log events from `com.foo.Bar` will be -recorded while only error events will be recorded from all other -components. - -In the previous example all the events from `com.foo.Bar` were still -written to the Console. This is because the logger for `com.foo.Bar` did -not have any appenders configured while its parent did. In fact, the -following configuration - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="WARN"> - <Appenders> - <Console name="Console" target="SYSTEM_OUT"> - <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/> - </Console> - </Appenders> - <Loggers> - <Logger name="com.foo.Bar" level="trace"> - <AppenderRef ref="Console"/> - </Logger> - <Root level="error"> - <AppenderRef ref="Console"/> - </Root> - </Loggers> -</Configuration> ----- - -would result in - -.... -17:13:01.540 [main] TRACE com.foo.Bar - entry -17:13:01.540 [main] TRACE com.foo.Bar - entry -17:13:01.540 [main] ERROR com.foo.Bar - Did it again! -17:13:01.540 [main] TRACE com.foo.Bar - exit (false) -17:13:01.540 [main] TRACE com.foo.Bar - exit (false) -17:13:01.540 [main] ERROR MyApp - Didn't do it. -.... - -Notice that the trace messages from `com.foo.Bar` appear twice. This is -because the appender associated with logger `com.foo.Bar` is first used, -which writes the first instance to the Console. Next, the parent of -`com.foo.Bar`, which in this case is the root logger, is referenced. The -event is then passed to its appender, which is also writes to the -Console, resulting in the second instance. This is known as additivity. -While additivity can be quite a convenient feature (as in the first -previous example where no appender reference needed to be configured), -in many cases this behavior is considered undesirable and so it is -possible to disable it by setting the additivity attribute on the logger -to false: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="WARN"> - <Appenders> - <Console name="Console" target="SYSTEM_OUT"> - <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/> - </Console> - </Appenders> - <Loggers> - <Logger name="com.foo.Bar" level="trace" additivity="false"> - <AppenderRef ref="Console"/> - </Logger> - <Root level="error"> - <AppenderRef ref="Console"/> - </Root> - </Loggers> -</Configuration> ----- - -Once an event reaches a logger with its additivity set to false the -event will not be passed to any of its parent loggers, regardless of -their additivity setting. - -[#Appenders] -=== Configuring Appenders - -An appender is configured either using the specific appender plugin's -name or with an appender element and the type attribute containing the -appender plugin's name. In addition each appender must have a name -attribute specified with a value that is unique within the set of -appenders. The name will be used by loggers to reference the appender as -described in the previous section. - -Most appenders also support a layout to be configured (which again may -be specified either using the specific Layout plugin's name as the -element or with "layout" as the element name along with a type attribute -that contains the layout plugin's name. The various appenders will -contain other attributes or elements that are required for them to -function properly. - -[#Scripts] -== Scripts - -Log4j provides support for -https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR -223] scripting languages to be used in some of its components. Any -language that provides support for the JSR 223 scripting engine may be -used. A list of the languages and bindings for them can be found at the -https://java.net/projects/scripting/sources/svn/show/trunk/engines[Scripting -Engine] web site. However, some of the languages listed there, such as -JavaScript, Groovy and Beanshell, directly support the JSR 223 scripting -framework and only require that the jars for that language be installed. - -As of Log4j 2.17.2 the languages to be supported must be specified as a comma separated list in the -`log4j2.Script.enableLanguages` system property. - -The components that support using scripts do so by allowing a `<script>`, -`<scriptFile>`, or `<scriptRef>` element to be configured on them. The -script element contains a name for the script, the language of the -script, and the script text. The scriptFile element contains the name of -the script, its location, its language, its charset, and whether the -file should be watched for changes. The scriptRef element contains the -name of the script that is defined in the `<scripts>` configuration -element. The name of the script is used to store the script, along with -its ScriptEngine, so it can quickly be located each time the script -needs to be run. While the name is not required, providing it will help -in debugging problems when the script is running. The language must be -provided on the script element and must specify one of the language -names that appear in the Configuration status log as described in the -next section. If the language is not specified on the scriptFile element -the language will be determined by the file extension of the script -path. If file monitoring is requested it will only be enabled if a -non-zero monitorInterval is specified on the configuration element. That -interval will be used to check for changes in the file. - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="debug" name="RoutingTest"> - <Scripts> - <Script name="selector" language="javascript"><![CDATA[ - var result; - if (logEvent.getLoggerName().equals("JavascriptNoLocation")) { - result = "NoLocation"; - } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { - result = "Flow"; - } - result; - ]]></Script> - <ScriptFile name="groovy.filter" path="scripts/filter.groovy"/> - </Scripts> - - <Appenders> - <Console name="STDOUT"> - <ScriptPatternSelector defaultPattern="%d %p %m%n"> - <ScriptRef ref="selector"/> - <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/> - <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/> - </ScriptPatternSelector> - <PatternLayout pattern="%m%n"/> - </Console> - </Appenders> - - <Loggers> - <Logger name="EventLogger" level="info" additivity="false"> - <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY"> - <Script name="GroovyFilter" language="groovy"><![CDATA[ - if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { - return true; - } else if (logEvent.getContextMap().containsKey("UserId")) { - return true; - } - return false; - ]]> - </Script> - </ScriptFilter> - <AppenderRef ref="STDOUT"/> - </Logger> - - <Root level="error"> - <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY"> - <ScriptRef ref="groovy.filter"/> - </ScriptFilter> - <AppenderRef ref="STDOUT"/> - </Root> - </Loggers> - -</Configuration> ----- - -If the status attribute on the Configuration element is set to DEBUG the -list of script engines currently installed and their attributes will be -listed. Although some engines may say they are not thread safe, Log4j -takes steps to insure that the scripts will run in a thread-safe manner -if the engine advertises that it is not thread safe. - -.... -2015-09-27 16:13:22,925 main DEBUG Installed script engines -2015-09-27 16:13:22,963 main DEBUG AppleScriptEngine Version: 1.1, Language: AppleScript, Threading: Not Thread Safe, - Compile: false, Names: {AppleScriptEngine, AppleScript, OSA} -2015-09-27 16:13:22,983 main DEBUG Groovy Scripting Engine Version: 2.0, Language: Groovy, Threading: MULTITHREADED, - Compile: true, Names: {groovy, Groovy} -2015-09-27 16:13:23,030 main DEBUG BeanShell Engine Version: 1.0, Language: BeanShell, Threading: MULTITHREADED, - Compile: true, Names: {beanshell, bsh, java} -2015-09-27 16:13:23,039 main DEBUG Mozilla Rhino Version: 1.7 release 3 PRERELEASE, Language: ECMAScript, Threading: MULTITHREADED, - Compile: true, Names: {js, rhino, JavaScript, javascript, ECMAScript, ecmascript} -.... - -When the scripts are executed they will be provided with a set of -variables that should allow them to accomplish whatever task they are -expected to perform. See the documentation for the individual components -for the list of variables that are available to the script. - -The components that support scripting expect a return value to be passed -back to the calling Java code. This is not a problem for several of the -scripting languages, but Javascript does not allow a return statement -unless it is within a function. However, Javascript will return the -value of the last statement executed in the script. As a consequence, -code such as that shown below will result in the desired behavior. - -[source,javascript] ----- -var result; -if (logEvent.getLoggerName().equals("JavascriptNoLocation")) { - result = "NoLocation"; -} else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { - result = "Flow"; -} -result; ----- - -=== A special note on Beanshell - -JSR 223 scripting engines are supposed to identify that they support the -Compilable interface if they support compiling their scripts. Beanshell -does this. However, whenever the compile method is called it throws an -Error (not an Exception). Log4j catches this but will log the warning -shown below for each Beanshell script when it tries to compile them. All -Beanshell scripts will then be interpreted on each execution. - -.... -2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable -2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error: unimplemented - at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175) - at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154) - at org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125) - at org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94) - -.... - -[#XInclude] -== XInclude - -XML configuration files can include other files with -http://www.xml.com/lpt/a/1009[XInclude]. Here is an example log4j2.xml -file that includes two other files: - -.log4j2.xml -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<configuration xmlns:xi="http://www.w3.org/2001/XInclude"; - status="warn" name="XIncludeDemo"> - <properties> - <property name="filename">xinclude-demo.log</property> - </properties> - <ThresholdFilter level="debug"/> - <xi:include href="log4j-xinclude-appenders.xml" /> - <xi:include href="log4j-xinclude-loggers.xml" /> -</configuration> ----- - -.log4j-xinclude-appenders.xml -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<appenders> - <Console name="STDOUT"> - <PatternLayout pattern="%m%n" /> - </Console> - <File name="File" fileName="${filename}" bufferedIO="true" immediateFlush="true"> - <PatternLayout> - <pattern>%d %p %C{1.} [%t] %m%n</pattern> - </PatternLayout> - </File> -</appenders> ----- - -.log4j-xinclude-loggers.xml -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<loggers> - <logger name="org.apache.logging.log4j.test1" level="debug" additivity="false"> - <ThreadContextMapFilter> - <KeyValuePair key="test" value="123" /> - </ThreadContextMapFilter> - <AppenderRef ref="STDOUT" /> - </logger> - - <logger name="org.apache.logging.log4j.test2" level="debug" additivity="false"> - <AppenderRef ref="File" /> - </logger> - - <root level="error"> - <AppenderRef ref="STDOUT" /> - </root> -</loggers> ----- - -[#CompositeConfiguration] -== Composite Configuration - -Log4j allows multiple configuration files to be used by specifying them -as a list of comma separated file paths on log4j2.configurationFile or, -when using URLs, by adding secondary configuration locations as query -parameters named "override". The merge logic can be controlled by specifying -a class that implements the MergeStrategy interface on the log4j.mergeStrategy -property. The default merge strategy will merge the files using the following rules: - -1. The global configuration attributes are aggregated with those in -later configurations replacing those in previous configurations, with -the exception that the highest status level and the lowest -monitorInterval greater than 0 will be used. -2. Properties from all configurations are aggregated. Duplicate -properties replace those in previous configurations. -3. Filters are aggregated under a CompositeFilter if more than one -Filter is defined. Since Filters are not named duplicates may be -present. -4. Scripts and ScriptFile references are aggregated. Duplicate -definitions replace those in previous configurations. -5. Appenders are aggregated. Appenders with the same name are replaced -by those in later configurations, including all of the Appender's -subcomponents. -6. Loggers are all aggregated. Logger attributes are individually -merged with duplicates being replaced by those in later configurations. -Appender references on a Logger are aggregated with duplicates being -replaced by those in later configurations. Filters on a Logger are -aggregated under a CompositeFilter if more than one Filter is defined. -Since Filters are not named duplicates may be present. Filters under -Appender references included or discarded depending on whether their -parent Appender reference is kept or discarded. - -[#StatusMessages] -== Status Messages - -**** -*Troubleshooting tip for the impatient:* - -From log4j-2.9 onward, log4j2 will print all internal logging to the -console if system property `log4j2.debug` is either defined empty or its value -equals to `true` (ignoring case). - -Prior to log4j-2.9, there are two places where internal logging can be -controlled: - -* Before a configuration is found, status logger level can be controlled -with system property -`org.apache.logging.log4j.simplelog.StatusLogger.level`. -* After a configuration is found, status logger level can be controlled -in the configuration file with the "status" attribute, for example: -`<Configuration status="trace">`. -**** - -Just as it is desirable to be able to diagnose problems in applications, -it is frequently necessary to be able to diagnose problems in the -logging configuration or in the configured components. Since logging has -not been configured, "normal" logging cannot be used during -initialization. In addition, normal logging within appenders could -create infinite recursion which Log4j will detect and cause the -recursive events to be ignored. To accomodate this need, the Log4j 2 API -includes a -link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html[`StatusLogger`]. -Components declare an instance of the StatusLogger similar to: - -[source,java] ----- -protected final static Logger logger = StatusLogger.getLogger(); ----- - -Since StatusLogger implements the Log4j 2 API's Logger interface, all -the normal Logger methods may be used. - -When configuring Log4j it is sometimes necessary to view the generated status events. -This can be accomplished by adding the status attribute to the configuration element or a default value can be provided by setting the xref:statusLoggerLevel["log4j2.statusLoggerLevel"] system property. -Valid values of the status attribute are "trace", "debug", "info", "warn", "error" and "fatal". -The following configuration has the status attribute set to debug. - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="debug" name="RoutingTest"> - <Properties> - <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property> - </Properties> - <ThresholdFilter level="debug"/> - - <Appenders> - <Console name="STDOUT"> - <PatternLayout pattern="%m%n"/> - <ThresholdFilter level="debug"/> - </Console> - <Routing name="Routing"> - <Routes pattern="$${sd:type}"> - <Route> - <RollingFile name="Rolling-${sd:type}" fileName="${filename}" - filePattern="target/rolling1/test1-${sd:type}.%i.log.gz"> - <PatternLayout> - <pattern>%d %p %c{1.} [%t] %m%n</pattern> - </PatternLayout> - <SizeBasedTriggeringPolicy size="500" /> - </RollingFile> - </Route> - <Route ref="STDOUT" key="Audit"/> - </Routes> - </Routing> - </Appenders> - - <Loggers> - <Logger name="EventLogger" level="info" additivity="false"> - <AppenderRef ref="Routing"/> - </Logger> - - <Root level="error"> - <AppenderRef ref="STDOUT"/> - </Root> - </Loggers> - -</Configuration> ----- - -During startup this configuration produces: - -.... -2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds -2011-11-23 17:08:00,789 DEBUG Calling createProperty on class org.apache.logging.log4j.core.config.Property for element property with params(name="filename", value="target/rolling1/rollingtest-${sd:type}.log") -2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class org.apache.logging.log4j.core.config.PropertiesPlugin for element properties with params(properties={filename=target/rolling1/rollingtest-${sd:type}.log}) -2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds -2011-11-23 17:08:00,797 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null") -2011-11-23 17:08:00,800 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%m%n", Configuration(RoutingTest), null, charset="null") -2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds -2011-11-23 17:08:00,804 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.ConsoleAppender for element Console with params(PatternLayout(%m%n), null, target="null", name="STDOUT", ignoreExceptions="null") -2011-11-23 17:08:00,804 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null") -2011-11-23 17:08:00,813 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="null", key="null", Node=Route) -2011-11-23 17:08:00,823 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="STDOUT", key="Audit", Node=Route) -2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class org.apache.logging.log4j.core.appender.routing.Routes for element Routes with params(pattern="${sd:type}", routes={Route(type=dynamic default), Route(type=static Reference=STDOUT key='Audit')}) -2011-11-23 17:08:00,827 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.routing.RoutingAppender for element Routing with params(name="Routing", ignoreExceptions="null", Routes({Route(type=dynamic default),Route(type=static Reference=STDOUT key='Audit')}), Configuration(RoutingTest), null, null) -2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class org.apache.logging.log4j.core.config.AppendersPlugin for element appenders with params(appenders={STDOUT, Routing}) -2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="Routing") -2011-11-23 17:08:00,829 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig for element logger with params(additivity="false", level="info", name="EventLogger", AppenderRef={Routing}, null) -2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="STDOUT") -2011-11-23 17:08:00,831 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig$RootLogger for element root with params(additivity="null", level="error", AppenderRef={STDOUT}, null) -2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class org.apache.logging.log4j.core.config.LoggersPlugin for element loggers with params(loggers={EventLogger, root}) -2011-11-23 17:08:00,834 DEBUG Reconfiguration completed -2011-11-23 17:08:00,846 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%d %p %c{1.} [%t] %m%n", Configuration(RoutingTest), null, charset="null") -2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy for element SizeBasedTriggeringPolicy with params(size="500") -2011-11-23 17:08:00,851 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.RollingFileAppender for element RollingFile with params(fileName="target/rolling1/rollingtest-Unknown.log", filePattern="target/rolling1/test1-Unknown.%i.log.gz", append="null", name="Rolling-Unknown", bufferedIO="null", immediateFlush="null", SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)), null, PatternLayout(%d %p %c{1.} [%t] %m%n), null, ignoreExceptions="null") -2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds -2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context sun.misc.Launcher$AppClassLoader@37b90b39 -2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds -2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds -2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds -2011-11-23 17:08:00,965 WARN No Loggers were configured, using default -2011-11-23 17:08:00,976 DEBUG Reconfiguration completed -.... - -If the status attribute is set to error then only error messages will be -written to the console. This makes troubleshooting configuration errors -possible. As an example, if the configuration above is changed to have -the status set to error and the logger declaration is: - -[source,xml] ----- -<logger name="EventLogger" level="info" additivity="false"> - <AppenderRef ref="Routng"/> -</logger> ----- - -the following error message will be produced. - -.... -2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng for logger EventLogger -.... - -Applications may wish to direct the status output to some other -destination. This can be accomplished by setting the dest attribute to -either "err" to send the output to stderr or to a file location or URL. -This can also be done by insuring the configured status is set to OFF -and then configuring the application programmatically such as: - -[source,java] ----- -StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR); -StatusLogger.getLogger().registerListener(listener); ----- - - diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc index 1763e1bcee..426af6b5d8 100644 --- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc @@ -82,7 +82,7 @@ reference these fields after the web application is undeployed. To avoid causing memory leaks, Log4j will not use these ThreadLocals when it detects that it is used in a web application (when the `javax.servlet.Servlet` class is in the classpath, or when system -property xref:manual/configuration/properties.adoc#log4j2.isWebapp[log4j2.isWebapp] is set to `true`). +property xref:manual/systemproperties.adoc#log4j2.isWebapp[log4j2.isWebapp] is set to `true`). Some garbage-reducing functionality does not rely on ThreadLocals and is enabled by default for all applications: in Log4j 2.6, converting log @@ -112,8 +112,8 @@ you may also configure a xref:manual/async.adoc#WaitStrategy[custom wait strateg There are separate system properties for manually controlling the mechanisms Log4j uses to avoid creating temporary objects: -* xref:manual/configuration/properties.adoc#log4j2.enableThreadlocals[log4j2.enableThreadlocals] - if "true" (the default for non-web applications) objects are stored in ThreadLocal fields and reused, otherwise new objects are created for each log event. -* xref:manual/configuration/properties.adoc#log4j2.enableDirectEncoders[log4j2.enableDirectEncoders] - if "true" (the default) +* xref:manual/systemproperties.adoc#log4j2.enableThreadlocals[log4j2.enableThreadlocals] - if "true" (the default for non-web applications) objects are stored in ThreadLocal fields and reused, otherwise new objects are created for each log event. +* xref:manual/systemproperties.adoc#log4j2.enableDirectEncoders[log4j2.enableDirectEncoders] - if "true" (the default) log events are converted to text and this text is converted to bytes without creating temporary objects. Note: _synchronous_ logging performance may be worse @@ -122,7 +122,7 @@ 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 -xref:manual/configuration/properties.adoc#log4j2.garbagefreeThreadContextMap[log4j2.garbagefreeThreadContextMap] to "true". +xref:manual/systemproperties.adoc#log4j2.garbagefreeThreadContextMap[log4j2.garbagefreeThreadContextMap] to "true". Instead of system properties, the above properties can also be specified in a file named `log4j2.component.properties` by including this file in diff --git a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc index cf47226659..a6a5f93361 100644 --- a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc @@ -35,7 +35,7 @@ JMX support is disabled by default. NOTE: JMX support was enabled by default in Log4j 2 versions before 2.24.0. To enable JMX support, set the -xref:manual/configuration/properties.adoc#log4j2.disableJmx[log4j2.disableJmx] +xref:manual/systemproperties.adoc#log4j2.disableJmx[log4j2.disableJmx] system property when starting the Java VM: `log4j2.disableJmx=false` @@ -44,7 +44,7 @@ system property when starting the Java VM: == Local Monitoring and Management To perform local monitoring you need to set the -xref:manual/configuration/properties.adoc#log4j2.disableJmx[log4j2 +xref:manual/systemproperties.adoc#log4j2.disableJmx[log4j2 .disableJmx] system property to `false`. The JConsole tool that is included in the Java JDK can be diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc b/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc similarity index 100% rename from src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc rename to src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc
