ppkarwasz commented on code in PR #2552: URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587660266
########## 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 Review Comment: Should be fixed now. -- 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]
