You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/05/27 10:46:05 UTC
(logging-log4j2) branch doc/2.x/simple-and-status-logger created (now 9e1d31294e)
This is an automated email from the ASF dual-hosted git repository.
vy pushed a change to branch doc/2.x/simple-and-status-logger
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
at 9e1d31294e Add Simple Logger and Status Logger pages
This branch includes the following new commits:
new 9e1d31294e Add Simple Logger and Status Logger pages
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(logging-log4j2) 01/01: Add Simple Logger and Status Logger pages
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/2.x/simple-and-status-logger
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 9e1d31294ebeb57faab2c6c0afbf0aae360a2417
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Mon May 27 12:45:44 2024 +0200
Add Simple Logger and Status Logger pages
---
src/site/antora/modules/ROOT/nav.adoc | 2 +
src/site/antora/modules/ROOT/pages/faq.adoc | 2 +-
src/site/antora/modules/ROOT/pages/manual/api.adoc | 25 ++++-
.../modules/ROOT/pages/manual/configuration.adoc | 4 +-
.../modules/ROOT/pages/manual/simple-logger.adoc | 29 ++++++
.../modules/ROOT/pages/manual/status-logger.adoc | 107 +++++++++++++++++++++
6 files changed, 163 insertions(+), 6 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index 65d5a8bb34..fd9e3eefae 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -42,6 +42,8 @@
** xref:manual/flowtracing.adoc[]
** xref:manual/eventlogging.adoc[]
** xref:manual/resource-logger.adoc[]
+** xref:manual/simple-logger.adoc[]
+** xref:manual/status-logger.adoc[]
* Configuration
** xref:manual/configuration.adoc[Configuration file]
** xref:manual/systemproperties.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/faq.adoc b/src/site/antora/modules/ROOT/pages/faq.adoc
index 64dc81f017..5ec5661f32 100644
--- a/src/site/antora/modules/ROOT/pages/faq.adoc
+++ b/src/site/antora/modules/ROOT/pages/faq.adoc
@@ -156,7 +156,7 @@ It is the responsibility of the logging _implementation_ to handle this object,
* Log4j API offers support for logging xref:manual/messages.adoc[`Message` objects].
Messages allow support for interesting and complex constructs to be passed through the logging system and be efficiently manipulated.
Users are free to create their own message types and write custom layouts, filters and lookups to manipulate them.
-* Log4j API supports xref:manual/api.adoc#LambdaSupport[lambda expressions] both in its plain and fluent API.
+* Log4j API supports xref:manual/api.adoc#fluent-api[lambda expressions] both in its plain and fluent API.
* Log4j API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating `vararg` arrays and avoids creating ``String``s when logging ``CharSequence``s.
[#gc-free-slf4j]
diff --git a/src/site/antora/modules/ROOT/pages/manual/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc
index a5edfcd650..fd179483ec 100644
--- a/src/site/antora/modules/ROOT/pages/manual/api.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/api.adoc
@@ -49,9 +49,10 @@ You can also check out xref:manual/installation.adoc[] for the complete installa
Log4j API provides
* A logging API that libraries and applications can code to
+* xref:#simple-logger[A minimal logging implementation (aka. Simple logger)]
* Adapter components to create a logging implementation
-This page tries to cover the most prominent Log4j API features that libraries and applications can code to.
+This page tries to cover the most prominent Log4j API features.
[TIP]
====
@@ -92,7 +93,7 @@ include::partial$manual/api-best-practice-use-supplier.adoc[]
[#loggers]
== Loggers
-link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s obtained using link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`] is the primary entry point for logging.
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s are the primary entry point for logging.
In this section we will introduce you to further details about ``Logger``s.
[#logger-names]
@@ -220,7 +221,25 @@ link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`EventLogger`
xref:manual/eventlogging.adoc[Read more on event loggers...]
-[#feature-fluent-api]
+[#simple-logger]
+=== Simple logger
+
+Even though Log4j Core is the reference implementation of Log4j API, Log4j API itself also provides a very minimalist implementation: _Simple Logger_.
+This is a convenience for environments where either a fully-fledged logging implementation is missing, or cannot be included for other reasons.
+`SimpleLogger` is the default Log4j API implementation if no other is available in the classpath.
+
+xref:manual/simple-logger.adoc[Read more on the simple logger...]
+
+[#status-logger]
+=== Status logger
+
+_Status Logger_ is a standalone, self-sufficient `Logger` implementation to record events that occur in the logging system (i.e., Log4j) itself.
+It is the logging system used by Log4j for reporting status of its internals.
+Users can use the status logger to either emit logs in their custom Log4j components, or troubleshoot a Log4j configuration.
+
+xref:manual/status-logger.adoc[Read more on the status logger...]
+
+[#fluent-api]
== Fluent API
The fluent API allows you to log using a fluent interface:
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index 6aa6b9ff5a..e4d3e6a891 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -59,7 +59,7 @@ Upon initialization of a new logger context, Log4j assigns it a context name and
. Files named `log4j2-test.<extension>`,
. Files named `log4j2<contextName>.<extension>`
. Files named `log4j2.<extension>`,
-. If no configuration file is found, Log4j uses the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration], and the status logger prints a warning.
+. If no configuration file is found, Log4j uses the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration], and xref:manual/status-logger.adoc[the status logger] prints a warning.
The default configuration prints all messages less specific than
xref:manual/systemproperties.adoc#log4j2.level[log4j2.level]
to the console.
@@ -424,7 +424,7 @@ To modify these options during a reconfiguration, you also need to change the re
Overrides the logging level of the status logger.
-WARNING: Since 2.24.0 this attribute is deprecated and should be replaced with the
+WARNING: Since version `2.24.0` this attribute is deprecated and should be replaced with the
xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]
configuration property.
diff --git a/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc b/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc
new file mode 100644
index 0000000000..2a7e67c576
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc
@@ -0,0 +1,29 @@
+////
+ 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.
+////
+
+= Simple Logger
+
+Even though Log4j Core is the reference implementation of xref:manual/api.adoc[Log4j API], Log4j API itself also provides a very minimalist implementation: link:../javadoc/log4j-api/org/apache/logging/log4j/simple/SimpleLogger.html[`SimpleLogger`].
+This is a convenience for environments where either a fully-fledged logging implementation is missing, or cannot be included for other reasons.
+`SimpleLogger` is the default Log4j API implementation if no other is available in the classpath.
+
+[#config]
+== Configuration
+
+`SimpleLogger` can be configured using the following system properties:
+
+include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+1]
diff --git a/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc b/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc
new file mode 100644
index 0000000000..28c476f068
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/status-logger.adoc
@@ -0,0 +1,107 @@
+////
+ 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.
+////
+
+:status-logger-properties-file-name: "log4j2.StatusLogger.properties"
+
+= Status Logger
+
+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.
+It is the logging system used by Log4j for reporting status of its internals.
+
+[#usage]
+== Usage
+
+You can use the status logger for several purposes:
+
+[#usage-troubleshoot]
+Troubleshooting::
+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.
+See xref:#config[] for details.
+
+[#usage-report]
+Reporting internal status::
+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.
+This is where `StatusLogger` comes into play:
++
+[source,java]
+----
+private class CustomLog4jComponent {
+
+ private static final Logger LOGGER = StatusLogger.getInstance();
+
+ void doSomething(String input) {
+ LOGGER.trace("doing something with input: `{}`", input);
+ }
+
+}
+----
+
+[#usage-listen]
+Listening internal status::
+You can configure where the status logger messages are delivered to.
+See xref:#listeners[].
+
+[#config]
+== Configuration
+
+`StatusLogger` can be configured in following ways:
+
+. Passing system properties to the Java process (e.g., xref:#log4j2.statusLoggerLevel[`-Dlog4j2.statusLoggerLevel=INFO`]}
++
+[WARNING]
+====
+Due to several complexities involved, **you are strongly advised to xref:#properties[configure the status logger only using system properties]!**
+====
+. Providing properties in a `{status-logger-properties-file-name}` file in the classpath
+. Using Log4j configuration (i.e., `<Configuration status="WARN" dest="out">` in a `log4j2.xml` in the classpath)
++
+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.
+. Programmatically (e.g., `StatusLogger.getLogger().setLevel(Level.WARN)`)
+
+It is crucial to understand that there is a time between the first `StatusLogger` access and a configuration file (e.g., `log4j2.xml`) read.
+Consider the following example:
+
+. The default level (of fallback listener) is `ERROR`
+. You have `<Configuration status="WARN">` in your `log4j2.xml`
+. Until your `log4j2.xml` configuration is read, the effective level will be `ERROR`
+. Once your `log4j2.xml` configuration is read, the effective level will be `WARN` as you configured
+
+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.
+
+`StatusLogger` is designed as a singleton class accessed statically.
+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.
+
+[#properties]
+=== Properties
+
+`StatusLogger` can be configured using the following system properties:
+
+include::partial$manual/systemproperties/properties-status-logger.adoc[leveloffset=+2]
+
+[#debug]
+== Debug mode
+
+When the `log4j2.debug` system property is present, any level-related filtering will be skipped and all events will be notified to listeners.
+If no listeners are available, the fallback listener of type `StatusConsoleListener` will be used.
+
+[#listeners]
+== Listeners
+
+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.
+If none are available, *the fallback listener* of type link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusConsoleListener.html[`StatusConsoleListener`] will be used.
+
+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].