There are some .md.vm files in that same directory, but I'm not sure exactly how that works - it looks like it will do variable replacement, but there are also some $h2 thingies there, so I didn't want to mess with figuring out how it all goes together.
-Robert Middleton On Fri, Dec 24, 2021 at 4:37 PM Gary Gregory <garydgreg...@gmail.com> wrote: > > 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 > > > > > >
