The $h2 things are to get around Velocity syntax and Markdown syntax for headers getting confused. Same with the $dollar variable. -- Matt Sicker
> On Dec 24, 2021, at 15:57, Robert Middleton <rmiddle...@apache.org> wrote: > > 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 >>> >>> >>>
