I versions need to be variables somehow, it's going to be forgotten for each new release...
Gary On Fri, Dec 24, 2021 at 4:27 PM GitBox <g...@apache.org> wrote: > > carterkozak commented on a change in pull request #657: > URL: > https://github.com/apache/logging-log4j2/pull/657#discussion_r775080805 > > > > ########## > File path: src/site/markdown/api-separation.md > ########## > @@ -0,0 +1,241 @@ > +<!-- vim: set syn=markdown : --> > +<!-- > + 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. > +--> > + > +# API Separation > + > +When selecting a logging library, some care must be taken in order to > ensure > +that multiple different logging libraries are properly accounted for. For > +example, library code that you depend on may use slf4j, while other > libraries > +may simply use java.util.logging. All of these can be routed to the log4j > +core in order to be logged. > + > +If however you want to use a different logging implementation(such as > logback), > +it is possible to route messages from the Log4j API to logback, ensuring > that > +your application is not tied to a specific logging framework. > + > +A typical class using the Log4j2 API looks like the following: > + > +```java > +import org.apache.logging.log4j.LogManager; > +import org.apache.logging.log4j.Logger; > + > +public class Log4j2Test { > + private static final Logger logger = LogManager.getLogger(); > + > + public Log4j2Test(){ > + logger.info( "Hello World!" ); > + } > +} > +``` > + > +In order to use the API portion of Log4j2, we only need to provide a > single > +dependency, log4j-api. Using Maven, you would add the following to your > +dependencies: > + > +``` > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-api</artifactId> > + <version>2.17.0</version> > +</dependency> > +``` > + > +## Using Log4j2 API and Core > + > +Using the Log4j2 API and Core together means that log messages will be > routed > +through the Log4j2 Core. The Log4j2 core is responsible for the > +following(note: this is not an exhaustive list): > + > +* Configuration of the system(via an XML file for example) > +* Routing messages to appenders > +* Opening files and other resources for logs(e.g. network sockets) > + > +When using the Log4j2 core, this means that your config file must match > the > +[configuration](manual/configuration.html) used by Log4j2. > + > +To use both the API and the core, you would add the following to your > +dependencies(assuming that you are using Maven): > + > +``` > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-api</artifactId> > + <version>2.17.0</version> > +</dependency> > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-core</artifactId> > + <version>2.17.0</version> > +</dependency> > +``` > + > +Note that having two different versions of log4j-api and log4j-core on > your > +classpath is not guaranteed to work correctly(e.g. 2.15 of log4j-api and > +2.17 of log4j-core). > + > +## Using Log4j2 API with Logback > + > +Since the Log4j2 API is generic, we can use it to send messages via SLF4J > +and then have Logback do the actual logging of the messages. This means > +that you can write your code tied to the Log4j2 API, but users of your > +code do not need to use the Log4j2 core if they are already using Logback. > + > +To switch to using Logback, you will need to add the following to your > +dependencies(assumging that you are using Maven): > + > +``` > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-api</artifactId> > + <version>2.17.0</version> > +</dependency> > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-to-slf4j</artifactId> > + <version>2.17.0</version> > +</dependency> > +<dependency> > + <groupId>ch.qos.logback</groupId> > + <artifactId>logback-classic</artifactId> > + <version>1.2.10</version> > +</dependency> > +``` > + > +## Using Log4j2 as an SLF4J Implementation > + > +If you don't want to depend on the Log4j2 API and instead want to use > SLF4J, > +that is possible as well. Assuming that our code looks like the > following: > + > +```java > +import org.slf4j.Logger; > +import org.slf4j.LoggerFactory; > + > +public class Log4j2Test { > + > + private static final Logger logger = > LoggerFactory.getLogger(Log4j2Test.class); > + > + public Log4j2Test(){ > + logger.info( "Hello World!" ); > + } > +} > +``` > + > +We can then route the messages to Log4j2 using the log4j-slf4j-impl like > the following: > + > +``` > +<dependency> > + <groupId>org.slf4j</groupId> > + <artifactId>slf4j-api</artifactId> > + <version>1.7.32</version> > +</dependency> > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-slf4j-impl</artifactId> > + <version>2.17.0</version> > +</dependency> > +<dependency> > + <groupId>org.apache.logging.log4j</groupId> > + <artifactId>log4j-core</artifactId> > + <version>2.17.0</version> > +</dependency> > +``` > + > +Note that if we were using SLF4J 1.8 instead of 1.7, that requires us to > use > +log4j-slf4j18-impl instead of log4j-slf4j-impl. > + > +## Using Log4j2 with JUL > + > +It is also possible to route messages that are logged using > java.util.logging > +to Log4j2. Assuming that the code looks like the following: > + > +```java > +import java.util.logging.Logger; > + > +public class Log4j2Test { > + > + private static final Logger logger = > Logger.getLogger(Log4j2Test.class.getName()); > + > + public Log4j2Test(){ > + logger.info( "Hello World!" ); > + } > +``` > + > +We can then also route these messages to the Log4j2 core by adding in the > JUL bridge, > +and setting the java.util.logging.manager property in the JVM(see the > documentation on > > Review comment: > It might be helpful to provide the precise arg here, otherwise > folks may read over it. I've seen it done incorrectly a few places. > ```suggestion > and setting > `-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager` on > the JVM (see the documentation on > ``` > > > > > -- > 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: notifications-unsubscr...@logging.apache.org > > For queries about this service, please contact Infrastructure at: > us...@infra.apache.org > > >
