From 383f008a05ab99cd68544174f9beb0180a53aa17 Mon Sep 17 00:00:00 2001
From: Ceki Gulcu SLF4J user manual
requires Java 8 and introduces a backward-compatible fluent logging
API. By backward-compatible, we mean that existing logging
frameworks do not have to be changed in order for the user to
- benefit from the fluent logging API.
+ benefit from the fluent logging API.
To run this example, you first need to download the slf4j distribution, and then to unpack it. Once that is done, add the file - slf4j-api-${project.version}.jar to your class path.
+ slf4j-api-${latest.stable.version}.jar to your class path.Compiling and running HelloWorld will result in the following output being printed on the console.
@@ -106,12 +106,12 @@The warning will disappear as soon as you add a binding to your class path. Assuming you add - slf4j-simple-${project.version}.jar so that your class + slf4j-simple-${latest.stable.version}.jar so that your class path contains:
Compiling and running HelloWorld will now result in @@ -157,11 +157,21 @@
As of version 2.0, SLF4J API introduces a fluent API.
-The idea is to contruct a logging event piece by piece and to - log it once constructed. If a given logger is disabled for a - given level, than the no construction takes place.
+The idea is to build a logging event piece by piece with a LoggingEventBuilder
+ and to log once the event is fully built. The
+ atTrace()
, atDebug()
,
+ atInfo()
, atWarn()
and
+ atError()
methods new in the
+ org.slf4j.Logger
interface return an instance of LoggingEventBuilder
. For
+ disabled log levels, the returned
+ LoggingEventBuilder
instance does nothing, thus
+ preserving the nano-second level performance of the regular
+ logging interface.
Here are few examples:
+ +Here are few usage examples:
The statement
logger.atInfo().log("Hello world");@@ -180,20 +190,44 @@
The fluent logging API allows the specification of many
+ different type of data to a org.slf4j.Logger
+ without a combinatorial explosion in the number of methods in
+ the Logger
interface.
It is now possible to pass multiple Markers, pass arguments + with a Supplier + or pass multiple key-value pairs. Key-value pairs are + particularly useful in conjuction with log data analysers which + can interpret them automatically.
+ +The following log statements are equivalent:
++ int newT = 15; + int oldT = 16; + + // using classical API + logger.debug("oldT={} newT={} Temperature changed.", newT, oldT); + + // using fluent API + logger.atDebug().addKeyValue("oldT", oldT).addKeyValue("newT", newT).log("Temperature changed."); +
To switch logging frameworks, just replace slf4j bindings on your class path. For example, to switch from java.util.logging - to log4j, just replace slf4j-jdk14-${project.version}.jar with - slf4j-log4j12-${project.version}.jar. + to log4j, just replace slf4j-jdk14-${latest.stable.version}.jar with + slf4j-log4j12-${latest.stable.version}.jar.
SLF4J does not rely on any special class loader machinery. In fact, each SLF4J binding is hardwired at compile time to use one and only one specific logging framework. For - example, the slf4j-log4j12-${project.version}.jar binding is + example, the slf4j-log4j12-${latest.stable.version}.jar binding is bound at compile time to use log4j. In your code, in addition - to slf4j-api-${project.version}.jar, you simply drop + to slf4j-api-${latest.stable.version}.jar, you simply drop one and only one binding of your choice onto the appropriate class path location. Do not place more than one binding on your class path. Here is a graphical illustration of @@ -355,11 +389,11 @@
<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> - <version>${project.version}</version> + <version>${latest.stable.version}</version> </dependency>
<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-jdk14</artifactId> - <version>${project.version}</version> + <version>${latest.stable.version}</version> </dependency>@@ -436,8 +470,8 @@
Mixing different versions of slf4j-api.jar and SLF4J binding can cause problems. For example, if you are using - slf4j-api-${project.version}.jar, then you should also use - slf4j-simple-${project.version}.jar, using + slf4j-api-${latest.stable.version}.jar, then you should also use + slf4j-simple-${latest.stable.version}.jar, using slf4j-simple-1.5.5.jar will not work.
diff --git a/slf4j-site/src/site/pages/news.html b/slf4j-site/src/site/pages/news.html index 4bc5c8020..b8c4ac313 100755 --- a/slf4j-site/src/site/pages/news.html +++ b/slf4j-site/src/site/pages/news.html @@ -48,7 +48,7 @@SLF4J version 2.0.0 requires Java 8. It builds on the 1.8.x series and adds a backward-compatible fluent-api. By backward-compatible, + href="manual.html#fluent">fluent logging api
. By backward-compatible, we mean that existing logging frameworks do not have to be changed for the user to benefit from the fluent logging API.