-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathapi-separation.html
360 lines (328 loc) · 22.2 KB
/
api-separation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/markdown/api-separation.md at 2021-12-28
| Rendered using Apache Maven Fluido Skin 1.8
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.1" />
<title>Log4j – API Separation</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.8.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script src="./js/apache-maven-fluido-1.8.min.js"></script>
</head>
<body class="topBarDisabled">
<div class="container-fluid">
<header>
<div id="banner">
<div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="images/ls-logo.jpg" alt=""/></a></div>
<div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="images/logo.png" alt=""/></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2021-12-28<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.17.1</li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li>
<li class="pull-right"><span class="divider">|</span>
<a href="../../" title="Logging Services">Logging Services</a></li>
<li class="pull-right"><span class="divider">|</span>
<a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li>
<li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li>
</ul>
</div>
</header>
<div class="row-fluid">
<header id="leftColumn" class="span2">
<nav class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><img class="imageLink" src="img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li>
<li><a href="index.html" title="About"><span class="none"></span>About</a></li>
<li><a href="download.html" title="Download"><span class="none"></span>Download</a></li>
<li><a href="javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li>
<li><a href="maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li>
<li><a href="runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li>
<li><a href="changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li>
<li><a href="faq.html" title="FAQ"><span class="none"></span>FAQ</a></li>
<li><a href="performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li>
<li><a href="articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li>
<li><a href="security.html" title="Security"><span class="none"></span>Security</a></li>
<li><a href="support.html" title="Support"><span class="none"></span>Support</a></li>
<li><a href="thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li>
<li><a href="build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></li>
<li><a href="guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li>
<li><a href="javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li>
<li><a href="manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li>
<li><a href="manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li>
<li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li>
<li><a href="manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li>
<li><a href="manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li>
<li><a href="manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li>
<li><a href="manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li>
<li><a href="manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li>
<li><a href="manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li>
<li><a href="manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li>
<li><a href="manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li>
<li><a href="manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li>
<li><a href="manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li>
<li><a href="manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li>
<li><a href="manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li>
<li><a href="manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li>
<li><a href="manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li>
<li><a href="manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li>
<li><a href="manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li>
<li><a href="manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li>
<li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li>
<li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li>
<li><a href="http://logging.apache.org/log4j/log4j-2.3.1/" class="externalLink" title="Log4j 2.3.1 - Java 6"><span class="none"></span>Log4j 2.3.1 - Java 6</a></li>
<li><a href="http://logging.apache.org/log4j/log4j-2.12.3/" class="externalLink" title="Log4j 2.12.3 - Java 7"><span class="none"></span>Log4j 2.12.3 - Java 7</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/cog.png" alt="Components" border="0"/> Components</li>
<li><a href="log4j-api/index.html" title="API"><span class="none"></span>API</a></li>
<li><a href="log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li>
<li><a href="log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li>
<li><a href="log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li>
<li><a href="log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li>
<li><a href="log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li>
<li><a href="log4j-jpl/index.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li>
<li><a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li>
<li><a href="log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li>
<li><a href="log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li>
<li><a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li>
<li><a href="log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li>
<li><a href="log4j-jakarta-web/index.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li>
<li><a href="log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li>
<li><a href="log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li>
<li><a href="log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li>
<li><a href="log4j-mongodb4/index.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li>
<li><a href="log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li>
<li><a href="log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li>
<li><a href="log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li>
<li><a href="log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li>
<li><a href="log4j-spring-boot/index.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li>
<li><a href="log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li>
<li><a href="dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li>
<li><a href="dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li>
<li><a href="team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li>
<li><a href="mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li>
<li><a href="issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li>
<li><a href="license.html" title="Project License"><span class="none"></span>Project License</a></li>
<li><a href="source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li>
<li><a href="project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li>
<li><a href="changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li>
<li><a href="jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li>
<li><a href="rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li>
</ul>
</nav>
<div class="well sidebar-nav">
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</header>
<main id="bodyColumn" class="span10" >
<!-- 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.
-->
<h1>API Separation</h1>
<p>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.</p>
<p>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.</p>
<p>A typical class using the Log4j2 API looks like the following:</p>
<div>
<div>
<pre class="source">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!" );
}
}
</pre></div></div>
<p>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:</p>
<div>
<div>
<pre class="source"><dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.17.0</version>
</dependency>
</pre></div></div>
<section>
<h2><a name="Using_Log4j2_API_and_Core"></a>Using Log4j2 API and Core</h2>
<p>Using the Log4j2 API and the implementation (Core) together means that log messages will be routed through the Log4j2 Core. The Log4j2 core implementation is responsible for the following (note: this is not an exhaustive list):</p>
<ul>
<li>Configuration of the system (via an XML file for example)</li>
<li>Routing messages to Appenders</li>
<li>Opening files and other resources for logging (e.g. network sockets)</li>
</ul>
<p>The <a href="manual/configuration.html">configuration</a> page in the manual describes the configuration format supported by the Log4j2 core implementation.</p>
<p>To use both the API and the core implementation, you would add the following to your dependencies (assuming that you are using Maven):</p>
<div>
<div>
<pre class="source"><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>
</pre></div></div>
<p>Note that having two different versions of log4j-api and log4j-core on your classpath is not guaranteed to work correctly (e.g., log4j-api version 2.15 and log4j-core version 2.17 are not guaranteed to work correctly together).</p></section><section>
<h2><a name="Using_Log4j2_API_with_Logback"></a>Using Log4j2 API with Logback</h2>
<p>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.</p>
<p>To switch to using Logback as your logging backend, you will need to add the following to your dependencies (assuming that you are using Maven):</p>
<div>
<div>
<pre class="source"><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>
</pre></div></div>
</section><section>
<h2><a name="Using_Log4j2_as_an_SLF4J_Implementation"></a>Using Log4j2 as an SLF4J Implementation</h2>
<p>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:</p>
<div>
<div>
<pre class="source">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!" );
}
}
</pre></div></div>
<p>We can then route the messages to Log4j2 using the log4j-slf4j-impl like the following:</p>
<div>
<div>
<pre class="source"><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>
</pre></div></div>
<p>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.</p></section><section>
<h2><a name="Using_Log4j2_with_JUL"></a>Using Log4j2 with JUL</h2>
<p>It is also possible to route messages that are logged using java.util.logging to Log4j2. Assuming that the code looks like the following:</p>
<div>
<div>
<pre class="source">import java.util.logging.Logger;
public class Log4j2Test {
private static final Logger logger = Logger.getLogger(Log4j2Test.class.getName());
public Log4j2Test() {
logger.info("Hello World!");
}
}
</pre></div></div>
<p>We can then also route these messages to the Log4j2 core by adding in the JUL bridge, and setting -Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager on the JVM (see the documentation on <a class="externalLink" href="https://logging.apache.org/log4j/2.x/log4j-jul/index.html">the JUL adapter</a> for more information as to how this works).</p>
<p>In order to route these messages to Log4j2, your dependencies would look like the following:</p>
<div>
<div>
<pre class="source"><dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-jul</artifactId>
<version>2.17.0</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.17.0</version>
</dependency>
</pre></div></div>
</section><section>
<h2><a name="Using_Log4j2_as_a_backend_for_Log4j1"></a>Using Log4j2 as a backend for Log4j1</h2>
<p>Some software may still depend on Log4j1, and in some cases it may be infeasible to modify this software to migrate it to Log4j2.</p>
<p>However, it may be possible to start using Log4j2 without modifying the application.</p>
<p>Assuming that our code looks like the following:</p>
<div>
<div>
<pre class="source">import org.apache.log4j.Logger;
public class Log4j2Test {
private static final Logger logger = Logger.getLogger(Log4j2Test.class);
public Log4j2Test(){
logger.info( "Hello World!" );
}
}
</pre></div></div>
<p>we can then quickly and easily configure these messages to use Log4j2 as the logging implementation by depending on the log4j-1.2-api bridge, like so:</p>
<div>
<div>
<pre class="source"><dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-1.2-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>
</pre></div></div>
<p>There are some limitations to this, but it is expected to work for the majority of common cases. See the (manual)[https://logging.apache.org/log4j/2.x/manual/migration.html] for more information on this feature.</p>
<h1>Conclusion</h1>
<p>With the API separation that Log4j2 provides, it is possible to use multiple logging APIs and implementations in the same project. This allows for greater flexibility, ensuring that you are not tied to a single API or implementation.</p></section>
</main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p align="center">Copyright © 1999-2021 <a class="external" href="http://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br>
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
</div>
</div>
</footer>
</body>
</html>