|
| 1 | +//// |
| 2 | + Licensed to the Apache Software Foundation (ASF) under one or more |
| 3 | + contributor license agreements. See the NOTICE file distributed with |
| 4 | + this work for additional information regarding copyright ownership. |
| 5 | + The ASF licenses this file to You under the Apache License, Version 2.0 |
| 6 | + (the "License"); you may not use this file except in compliance with |
| 7 | + the License. You may obtain a copy of the License at |
| 8 | + |
| 9 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | + |
| 11 | + Unless required by applicable law or agreed to in writing, software |
| 12 | + distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | + See the License for the specific language governing permissions and |
| 15 | + limitations under the License. |
| 16 | +//// |
| 17 | +
|
| 18 | +:status-logger-properties-file-name: "log4j2.StatusLogger.properties" |
| 19 | +
|
| 20 | += Status Logger |
| 21 | +
|
| 22 | +link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html[`StatusLogger`] is a standalone, self-sufficient `Logger` implementation to record events that occur in the logging system (i.e., Log4j) itself. |
| 23 | +It is the logging system used by Log4j for reporting status of its internals. |
| 24 | +
|
| 25 | +[#usage] |
| 26 | +== Usage |
| 27 | +
|
| 28 | +You can use the status logger for several purposes: |
| 29 | +
|
| 30 | +[#usage-troubleshoot] |
| 31 | +Troubleshooting:: |
| 32 | +When Log4j is not behaving in the way you expect it to, you can increase the verbosity of status logger messages emitted using xref:#log4j2.debug[the `log4j2.debug` system property] for troubleshooting. |
| 33 | +See xref:#config[] for details. |
| 34 | +
|
| 35 | +[#usage-report] |
| 36 | +Reporting internal status:: |
| 37 | +If you have custom Log4j components (layouts, appenders, etc.), you cannot use Log4j API itself for logging, since this will result in a chicken and egg problem. |
| 38 | +This is where `StatusLogger` comes into play: |
| 39 | ++ |
| 40 | +[source,java] |
| 41 | +---- |
| 42 | +private class CustomLog4jComponent { |
| 43 | +
|
| 44 | + private static final Logger LOGGER = StatusLogger.getInstance(); |
| 45 | +
|
| 46 | + void doSomething(String input) { |
| 47 | + LOGGER.trace("doing something with input: `{}`", input); |
| 48 | + } |
| 49 | +
|
| 50 | +} |
| 51 | +---- |
| 52 | +
|
| 53 | +[#usage-listen] |
| 54 | +Listening internal status:: |
| 55 | +You can configure where the status logger messages are delivered to. |
| 56 | +See xref:#listeners[]. |
| 57 | +
|
| 58 | +[#config] |
| 59 | +== Configuration |
| 60 | +
|
| 61 | +`StatusLogger` can be configured in following ways: |
| 62 | +
|
| 63 | +. Passing system properties to the Java process (e.g., xref:#log4j2.statusLoggerLevel[`-Dlog4j2.statusLoggerLevel=INFO`]} |
| 64 | ++ |
| 65 | +[WARNING] |
| 66 | +==== |
| 67 | +Due to several complexities involved, **you are strongly advised to xref:#properties[configure the status logger only using system properties]!** |
| 68 | +==== |
| 69 | +. Providing properties in a `{status-logger-properties-file-name}` file in the classpath |
| 70 | +. Using Log4j configuration (i.e., `<Configuration status="WARN" dest="out">` in a `log4j2.xml` in the classpath) |
| 71 | ++ |
| 72 | +WARNING: Since version `2.24.0`, `status` attribute in the `Configuration` element is deprecated and should be replaced with the xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property. |
| 73 | +. Programmatically (e.g., `StatusLogger.getLogger().setLevel(Level.WARN)`) |
| 74 | +
|
| 75 | +It is crucial to understand that there is a time between the first `StatusLogger` access and a configuration file (e.g., `log4j2.xml`) read. |
| 76 | +Consider the following example: |
| 77 | +
|
| 78 | +. The default level (of fallback listener) is `ERROR` |
| 79 | +. You have `<Configuration status="WARN">` in your `log4j2.xml` |
| 80 | +. Until your `log4j2.xml` configuration is read, the effective level will be `ERROR` |
| 81 | +. Once your `log4j2.xml` configuration is read, the effective level will be `WARN` as you configured |
| 82 | +
|
| 83 | +Hence, unless you use either system properties or `{status-logger-properties-file-name}` file in the classpath, there is a time window that only the defaults will be effective. |
| 84 | +
|
| 85 | +`StatusLogger` is designed as a singleton class accessed statically. |
| 86 | +If you are running an application containing multiple Log4j configurations (e.g., in a servlet environment with multiple containers), and you happen to have differing `StatusLogger` configurations (e.g, one `log4j2.xml` containing `<Configuration status="ERROR">` while the other `<Configuration status="INFO">`), the last loaded configuration will be the effective one. |
| 87 | +
|
| 88 | +[#properties] |
| 89 | +=== Properties |
| 90 | +
|
| 91 | +`StatusLogger` can be configured using the following system properties: |
| 92 | +
|
| 93 | +include::partial$manual/systemproperties/properties-status-logger.adoc[leveloffset=+2] |
| 94 | +
|
| 95 | +[#debug] |
| 96 | +== Debug mode |
| 97 | +
|
| 98 | +When the `log4j2.debug` system property is present, any level-related filtering will be skipped and all events will be notified to listeners. |
| 99 | +If no listeners are available, the fallback listener of type `StatusConsoleListener` will be used. |
| 100 | +
|
| 101 | +[#listeners] |
| 102 | +== Listeners |
| 103 | +
|
| 104 | +Each recorded log event by `StatusLogger` will first get buffered and then used to notify the registered link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusListener.html[`StatusListener`]s. |
| 105 | +If none are available, *the fallback listener* of type link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusConsoleListener.html[`StatusConsoleListener`] will be used. |
| 106 | +
|
| 107 | +You can programmatically register listeners using link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html#registerListener(org.apache.logging.log4j.status.StatusListener)[the `StatusLogger#registerListener(StatusListener)` method]. |
0 commit comments