blob: 2c2979fd4ef82e14cecf290a3db4d82a98758963 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/markdown/log4j-jul.md at 2023-12-19
| 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.11.1" />
<title>Log4j &#x2013; </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/3.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: 2023-12-19<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 3.0.0-beta1</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="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</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™ 3.x" border="0"/> Apache Log4j™ 3.x</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="none"></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="release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</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="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/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li>
<li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="none"></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/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="Older Releases" border="0"/> Older Releases</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/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li>
<li><a href="http://logging.apache.org/log4j/log4j-2.12.1/" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li>
<li><a href="http://logging.apache.org/log4j/2.x/" class="externalLink" title="Log4j 2.x - Latest release for Java 8"><span class="none"></span>Log4j 2.x - Latest release for Java 8</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/layers.png" alt="Internal Components" border="0"/> Internal Components</li>
<li><a href="log4j-api.html" title="API"><span class="none"></span>API</a></li>
<li><a href="log4j-core.html" title="Implementation"><span class="none"></span>Implementation</a></li>
<li><a href="log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li>
<li><a href="log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li>
<li><a href="log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li>
<li class="active"><a href="#"><span class="none"></span>JUL Adapter</a></li>
<li><a href="log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li>
<li><a href="log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li>
<li><a href="log4j-jdbc-dbcp2.html" title="JDBC Appender"><span class="none"></span>JDBC Appender</a></li>
<li><a href="log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li>
<li><a href="log4j-appserver.html" title="Application Server Integration"><span class="none"></span>Application Server Integration</a></li>
<li><a href="log4j-mongodb4.html" title="MongoDB 4 appender"><span class="none"></span>MongoDB 4 appender</a></li>
<li><a href="log4j-iostreams.html" title="IO Streams"><span class="none"></span>IO Streams</a></li>
<li><a href="log4j-docker.html" title="Docker Support"><span class="none"></span>Docker Support</a></li>
<li><a href="log4j-kubernetes.html" title="Kubernetes Support"><span class="none"></span>Kubernetes Support</a></li>
<li><a href="log4j-spring-cloud-config-client.html" title="Spring Cloud Config Client"><span class="none"></span>Spring Cloud Config Client</a></li>
<li><a href="log4j-transform" title="Log4j Transformation Tools"><span class="none"></span>Log4j Transformation Tools</a></li>
<li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="External Components" border="0"/> External Components</li>
<li><a href="log4j/jakarta" title="Log4j Jakarta EE"><span class="none"></span>Log4j Jakarta EE</a></li>
<li><a href="log4j/jmx-gui" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li>
<li><a href="log4j/tools" title="Log4j Tools"><span class="none"></span>Log4j Tools</a></li>
<li><a href="log4j/transform" title="Log4j Transformation Tools"><span class="none"></span>Log4j Transformation Tools</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="team.html" title="Project Team"><span class="none"></span>Project Team</a></li>
<li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li>
<li><a href="https://github.com/apache/logging-log4j2/tree/main" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</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="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.
-->
<p>There are two possibilities:</p>
<ul>
<li>Logging Adapter as complete replacement (preferred, but requires JVM start option)</li>
<li>Bridge Handler, transfering JDK output to log4j, e.g. useful for webapps</li>
</ul>
<h1>Log4j JDK Logging Adapter</h1>
<p>The JDK Logging Adapter is a custom implementation of
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/LogManager.html"><code>java.util.logging.LogManager</code></a>
that uses <a href="javadoc/log4j-core/index.html">Log4j</a>. This adapter can be used with either the Log4j API or
Log4j Core. When used with the API, there are a couple features of JUL that aren't supported. However, this
does allow any other Log4j Provider besides the Core provider to be used with JUL.</p><section>
<h2><a name="Requirements"></a>Requirements</h2>
<p>The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j Core.
For more information, see <a href="runtime-dependencies.html">Runtime Dependencies</a>.</p></section><section>
<h2><a name="Usage"></a>Usage</h2>
<p>To use the JDK Logging Adapter, you must set the system property <code>java.util.logging.manager</code> to
<code>org.apache.logging.log4j.jul.LogManager</code>.</p>
<p>This must be done either through the command line (i.e., using the
<code>-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager</code> argument) or by using
<code>System.setProperty()</code> before any calls are made to <code>LogManager</code> or <code>Logger</code>.</p></section><section>
<h2><a name="Compatibility"></a>Compatibility</h2>
<p>The use of a
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html"><code>java.util.logging.Filter</code></a>
is supported on a per-<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html"><code>Logger</code></a>
basis. However, it is recommended to use the standard <a href="manual/filters.html">Filters</a> feature in
Log4j instead.</p>
<p>The use of
<a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html"><code>java.util.logging.Handler</code></a>
classes is <i>NOT</i> supported. Custom Handlers should instead use an appropriate
<a href="manual/appenders.html">Appender</a> or code their own
<a href="javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html"><code>Appender</code></a>
plugin.</p>
<p>Java logging levels are translated into Log4j logging levels dynamically. The following table lists the
conversions between a Java logging level and its equivalent Log4j level. Custom levels should be implemented
as an implementation of
<code>LevelConverter</code>, and the
Log4j property <code>log4j.jul.levelConverter</code> must be set to your custom class name. Using the default
<code>LevelConverter</code> implementation, custom logging levels are mapped to whatever the current level of
the <code>Logger</code> being logged to is using.</p><section>
<h3><a name="Default_Level_Conversions"></a>Default Level Conversions</h3>
<table border="0" class="table table-striped">
<thead>
<tr class="a">
<th>Java Level</th>
<th>Log4j Level</th></tr>
</thead><tbody>
<tr class="b">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF"><code>OFF</code></a></td>
<td><code>OFF</code></td></tr>
<tr class="a">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE"><code>SEVERE</code></a></td>
<td><code>ERROR</code></td></tr>
<tr class="b">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING"><code>WARNING</code></a></td>
<td><code>WARN</code></td></tr>
<tr class="a">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO"><code>INFO</code></a></td>
<td><code>INFO</code></td></tr>
<tr class="b">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG"><code>CONFIG</code></a></td>
<td><code>CONFIG</code></td></tr>
<tr class="a">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE"><code>FINE</code></a></td>
<td><code>DEBUG</code></td></tr>
<tr class="b">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER"><code>FINER</code></a></td>
<td><code>TRACE</code></td></tr>
<tr class="a">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST"><code>FINEST</code></a></td>
<td><code>FINEST</code></td></tr>
<tr class="b">
<td align="left"><a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL"><code>ALL</code></a></td>
<td><code>ALL</code></td></tr>
</tbody>
</table>
<h1>Log4j JDK Logging Bridge Handler</h1>
<p>The LogManager is not always useable because you have to set a JVM wide effective system
property - e.g. in web servers this is not possible if you are not the administrator.</p>
<p>The <code>Log4jBridgeHandler</code> is an
alternative that can be declaratively used via <code>logging.properties</code>.</p>
<p>It is less performant than the LogManager but still okay to use: the LogManager replaces the JDK
implementation, so your logging code (using JDK syntax) effectively directly uses log4j.
When using the BridgeHandler the original JDK implementation along with its configuration
(e.g. log levels) is still fully working but the log events are &#x201c;written&#x201d; via this handler to log4j
as if you would have called log4j.Logger.debug() etc.; it is like a FileHandler but instead of
writing to a file, it &#x201c;writes&#x201d; to log4j Loggers - thus there is some overhead compared to using
LogManager.</p></section></section><section>
<h2><a name="Usage"></a>Usage</h2>
<p>The JUL configuration file <code>logging.properties</code> needs the line</p>
<p><code>handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler</code></p>
<p>and JUL logs go to log4j2. Additionally, you typically want to use to following:</p>
<p><code>org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true</code></p>
<p>In a webapp on Tomcat (and maybe other servers, too), you may simply create a
<code>WEB-INF/classes/logging.properties</code> file with above content.
The bridge and the log levels defined in this file are only valid for your webapp and
do <i>not</i> have any impact on the other webapps on the same Tomcat instance.</p>
<p>Alternatively you may call <code>Log4jBridgeHandler.install()</code> inside your webapp's initialization code,
e.g. inside <code>ServletContextListener</code> or a <code>ServletFilter</code> static-class-init. or <code>contextInitialized()</code>.</p>
<p><b>Important:</b> Log levels of JDK should match the ones of log4j. You may do this manually or use the
automatic level propagation via <code>Log4jBridgeHandler.propagateLevels = true</code>.</p></section>
</main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p align="center">Copyright &copy; 1999-2023 <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>