You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@logging.apache.org by GitBox <gi...@apache.org> on 2021/12/24 21:27:40 UTC
[GitHub] [logging-log4j2] carterkozak commented on a change in pull request #657: Api separation documentation
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-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [GitHub] [logging-log4j2] carterkozak commented on a change in pull request #657: Api separation documentation
Posted by Matt Sicker <bo...@gmail.com>.
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 <rm...@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 <ga...@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 <gi...@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-unsubscribe@logging.apache.org
>>>
>>> For queries about this service, please contact Infrastructure at:
>>> users@infra.apache.org
>>>
>>>
>>>
Re: [GitHub] [logging-log4j2] carterkozak commented on a change in pull request #657: Api separation documentation
Posted by Robert Middleton <rm...@apache.org>.
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 <ga...@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 <gi...@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-unsubscribe@logging.apache.org
> >
> > For queries about this service, please contact Infrastructure at:
> > users@infra.apache.org
> >
> >
> >
Re: [GitHub] [logging-log4j2] carterkozak commented on a change in pull request #657: Api separation documentation
Posted by Gary Gregory <ga...@gmail.com>.
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 <gi...@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-unsubscribe@logging.apache.org
>
> For queries about this service, please contact Infrastructure at:
> users@infra.apache.org
>
>
>