ppkarwasz commented on code in PR #2552: URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587659435
########## src/site/antora/modules/ROOT/pages/manual/_properties.adoc: ########## @@ -0,0 +1,1022 @@ +//// + 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. +//// +[#SystemProperties] += Global configuration properties + +Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables]. +See <<property-sources>> for a complete list of supported sources + +Global configuration properties are used by Log4j in the following situations: + +* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file, +* to change the default values of attributes used in a configuration file. + +Since Log4j 2.10 all the property names follow a common naming scheme: + +---- +log4j2.camelCasePropertyName +---- + +except the environment variables, which follow the: + +---- +LOG4J_CAMEL_CASE_PROPERTY_NAME +---- + +convention. + +[NOTE] +==== +If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup. +==== + +[WARNING] +==== +To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm. + +In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes: + +* `asyncLogger`, +* `disableThreadContext`, +* `isThreadContext`, +* `org.apache.logging.log4j` + +and that all the properties names that start with `log4j` use the normalized form provided by the tables below. +==== + +== Meta configuration properties + +In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties: + +.Meta configuration properties +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.isWebapp]]`log4j2.isWebapp` + +(`LOG4J_IS_WEBAPP`) +| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath +| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_). + +In this mode Log4j is optimized to work in a Servlet container. + +This mode is incompatible with <<log4j2.enableThreadlocals>>. + +| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals` + +(`LOG4J_ENABLE_THREADLOCALS`) +| `!log4j2.isWebapp` +| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_). + +In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations. + +This mode is incompatible with <<log4j2.isWebapp>>. + +|=== + +== Log4j API properties + +The services included in the `log4j-api` module can be configured exclusively through configuration properties. + +=== LoaderUtil + +The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name. +Therefore, its configuration influences all other services. + +It has only one configuration property: + +.LoaderUtil configuration properties +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl` + +(`LOG4J_IGNORE_TCL`) +| `false` +| +If `true`, classes are only loaded using the same classloader that loaded Log4j. + +Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader. + +|=== + +=== Provider + +The runtime classpath of an application **should** contain only a single implementation of the Log4j API. +In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider. +See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details. + +[NOTE] +==== +For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively. +==== + +=== Status Logger + +Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components. +By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties. + +.Status logger configuration +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.debug]]`log4j2.debug` + +(`LOG4J_DEBUG`) +| false +| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property. + +| [[log4j2.statusEntries]]`log4j2.statusEntries` + +(`LOG4J_STATUS_ENTRIES`) +| 0 +| Specifies the number of status logger entries to cache. +Once the limit is reached newer entries will overwrite the oldest ones. + +| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel` + +(`LOG4J_STATUS_LOGGER_LEVEL`) +| ERROR +| Specifies the level of the status logger. +Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file. + +| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat` + +(`LOG4J_STATUS_LOGGER_DATE_FORMAT`) +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT] +| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates. + +| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone` + +(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`) +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()] +| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats. + +|=== + +=== Simple logger + +The simple logger implementation contained in `log4j-api` can be configured using these properties: + +.Simple logger configuration +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel` + +(`LOG4J_SIMPLELOG_LEVEL`) +| ERROR +| Default level for new logger instances. + +| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level` + +(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`) +| value of <<log4j2.simplelogLevel>> +| Log level for a logger instance named `<loggerName>`. + +| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap` + +(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`) +| false +| If `true`, the full thread context map is included in each log message. + +| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname` + +(`LOG4J_SIMPLELOG_SHOWLOGNAME`) +| false +| If `true`, the logger name is included in each log message. + +| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname` + +(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`) +| true +| If `true`, only the last component of a logger name is included in each log message. + +| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime` + +(`LOG4J_SIMPLELOG_SHOWDATETIME`) +| false +| If `true`, a timestamp is included in each log message. + +| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat` + +(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`) +| `yyyy/MM/dd HH:mm:ss:SSS zzz` +| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`. + +| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile` + +(`LOG4J_SIMPLELOG_LOG_FILE`) +| System.err +a| Specifies the output stream used by all loggers: + +* `System.err` logs to the standard error output stream, +* `System.out` logs to the standard output stream, +* any other value is interpreted as a file name. + +|=== + +[#simple-logger-thread-context] +=== Thread context (Simple Logger) + +The behavior of the `ThreadContext` class can be fine-tuned using the following properties. + +[WARNING] +==== +These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API. + +The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class. + +The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls. +==== + +.Thread context configuration +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext` + +(`LOG4J_DISABLE_THREAD_CONTEXT`) +| false +| If `true`, the `ThreadContext` stack and map are disabled. + +| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack` + +(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`) +| false +| If `true`, the `ThreadContext` stack is disabled. + +| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap` + +(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`) +| false +| If `true`, the `ThreadContext` map is disabled. + +| [[log4j2.threadContextMap]]`log4j2.threadContextMap` + +(`LOG4J_THREAD_CONTEXT_MAP`) +| `WebApp` + +(GC-free mode: `CopyOnWrite`) +a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants: + +* `NoOp`: to disable the thread context, +* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks, +* `CopyOnWrite`: a copy-on-write implementation, +* `GarbageFree`: a garbage-free implementation. + +| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable` + +(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`) +| false +| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads. + +| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap` + +(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`) +| false +| If set to `true` selects a garbage-free thread context map implementation. +Requires <<log4j2.enableThreadlocals>> to be also `true`. + +|=== + +== Log4j Core + +While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works. + +=== Async components Review Comment: Fixed in 4c0930a555eed5678ac22b079ed693c6e669597e -- 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]
