You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ma...@apache.org on 2022/01/12 13:02:04 UTC
svn commit: r1896961 - in /poi/site: publish/components/logging.html src/documentation/content/xdocs/components/logging.xml
Author: mariusvolkhart
Date: Wed Jan 12 13:02:04 2022
New Revision: 1896961
URL: http://svn.apache.org/viewvc?rev=1896961&view=rev
Log:
Update logging docs since POI now uses the Log4j 2 API
Provide examples of how to configure logging using popular logging backends.
Modified:
poi/site/publish/components/logging.html
poi/site/src/documentation/content/xdocs/components/logging.xml
Modified: poi/site/publish/components/logging.html
URL: http://svn.apache.org/viewvc/poi/site/publish/components/logging.html?rev=1896961&r1=1896960&r2=1896961&view=diff
==============================================================================
--- poi/site/publish/components/logging.html (original)
+++ poi/site/publish/components/logging.html Wed Jan 12 13:02:04 2022
@@ -290,6 +290,16 @@ document.write("Last Published: " + docu
<h1>Apache POI - Logging Framework</h1>
<div id="front-matter"></div>
+<a name="Introduction"></a>
+<h2 class="boxed">Introduction</h2>
+<div class="section">
+<p>
+ Logging in POI is used primarily as a debugging mechanism, not a normal runtime
+ logging system. Logging at levels noisier than WARN is ONLY for autopsy type debugging, and should
+ NEVER be enabled on a production system.
+ </p>
+</div>
+
<a name="POI+5.0.0+and+above"></a>
<h2 class="boxed">POI 5.0.0 and above</h2>
<div class="section">
@@ -301,10 +311,245 @@ document.write("Last Published: " + docu
</p>
<p>
POI 5.1.0 goes further and specifically uses <a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> directly.
- If you want to continue to use another slf4j compatible logging framework, you can deploy the
+ If you want to continue to use another SLF4J compatible logging framework, you can deploy the
<a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar to
facilitate this.
</p>
+<p>
+ POI tries to name loggers after the canonical name of the containing class. For example,
+ <span class="codefrag">org.apache.poi.poifs.filesystem.POIFSFileSystem</span>. Use your logging framework's typical
+ mechanisms for activating and deactivating logging for specific loggers.
+ </p>
+<p>
+ All loggers are named <span class="codefrag">com.apache.poi.*</span>, so rules applied to <span class="codefrag">com.apache.poi</span>
+ will affect all POI loggers.
+ </p>
+</div>
+
+<a name="Logging+with+Log4j+2+Core"></a>
+<h2 class="boxed">Logging with Log4j 2 Core</h2>
+<div class="section">
+<p>
+ Capturing POI logs using Log4j 2 Core is as simple as including the
+ <a href="https://logging.apache.org/log4j/2.x/maven-artifacts.html"><span class="codefrag">log4j-core</span></a> JAR in
+ your project.
+ </p>
+<p>
+ The simplest configuration is to capture all POI logs at the same level as your application. You might
+ want to collect all messages <span class="codefrag">INFO</span> and higher, and are OK with capturing POI messages as well.
+ </p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><Configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Root level="INFO"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></Configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
+<p>
+ A more recommended configuration is to capture only messages from loggers you opt in to. For example,
+ you might want to capture all messages from <span class="codefrag">com.example.myapplication</span> at <span class="codefrag">INFO</span>
+ but only POI messages at <span class="codefrag">WARN</span> or more severe.
+ </p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><Configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Logger name="com.example.myapplication" level="INFO" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Logger name="org.apache.poi" level="WARN" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Root level="OFF"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></Configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
+<p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><Configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Logger name="org.apache.poi" level="OFF" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <Root level="INFO"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </Loggers></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></Configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
+</div>
+
+<a name="Logging+with+Logback"></a>
+<h2 class="boxed">Logging with Logback</h2>
+<div class="section">
+<p>
+ Capturing POI logs using Logback requires adding the
+ <a href="https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html">Log4j to SLF4J Adapter</a> to
+ your project, along with the standard Logback dependencies.
+ </p>
+<p>
+ The simplest configuration is to capture all POI logs at the same level as your application. You might
+ want to collect all messages <span class="codefrag">INFO</span> and higher, and are OK with capturing POI messages as well.
+ </p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <root level="INFO"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
+<p>
+ A more recommended configuration is to capture only messages from loggers you opt in to. For example,
+ you might want to capture all messages from <span class="codefrag">com.example.myapplication</span> at <span class="codefrag">INFO</span>
+ but only POI messages at <span class="codefrag">WARN</span> or more severe.
+ </p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <logger name="com.example.myapplication" level="INFO" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <logger name="org.apache.poi" level="WARN" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <root level="OFF"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
+<p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
+<div class="code">
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"><configuration ...></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <logger name="org.apache.poi" level="OFF" /></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> <root level="INFO"></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> ...</span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"> </root></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></configuration></span>
+</div>
+<div class="codeline">
+<span class="lineno"></span><span class="codebody"></span>
+</div>
+</div>
</div>
<a name="Legacy+POI+Logging+Framework+%28no+longer+supported+in+POI+5.0.0+and+above%29"></a>
@@ -332,13 +577,13 @@ document.write("Last Published: " + docu
<h2 class="boxed">POI 4.x and before: Enable Legacy POI Logging Framework</h2>
<div class="section">
<p>
- By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful
- to enable logging to see some debug messages printed out which can
- help in analyzing problems.
- </p>
+ By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful
+ to enable logging to see some debug messages printed out which can
+ help in analyzing problems.
+ </p>
<p>
- You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty():
- </p>
+ You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty():
+ </p>
<div class="code">
<div class="codeline">
<span class="lineno"></span><span class="codebody"></span>
@@ -351,8 +596,8 @@ document.write("Last Published: " + docu
</div>
</div>
<p>
- Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
- </p>
+ Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
+ </p>
</div>
<a name="POI+4.x+and+before%3A+Available+Legacy+POI+Logging+Framework+implementations"></a>
@@ -362,42 +607,42 @@ document.write("Last Published: " + docu
The following logger implementations are provided by POI 3 and 4:
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
-
-<tr>
+<tr>
+
<th colspan="1" rowspan="1">Class</th>
- <th colspan="1" rowspan="1">Type</th>
-
+ <th colspan="1" rowspan="1">Type</th>
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">org.apache.poi.util.SystemOutLogger</td>
- <td colspan="1" rowspan="1">Sends log output to the system console</td>
-
+ <td colspan="1" rowspan="1">Sends log output to the system console</td>
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">org.apache.poi.util.NullLogger</td>
- <td colspan="1" rowspan="1">Default logger, does not log anything</td>
-
+ <td colspan="1" rowspan="1">Default logger, does not log anything</td>
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">org.apache.poi.util.CommonsLogger</td>
- <td colspan="1" rowspan="1">Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging,
- log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td>
-
+ <td colspan="1" rowspan="1">Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging,
+ log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td>
+
</tr>
-
-<tr>
+<tr>
+
<td colspan="1" rowspan="1">org.apache.poi.util.DummyPOILogger</td>
- <td colspan="1" rowspan="1">Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source).
- Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
-
+ <td colspan="1" rowspan="1">Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source).
+ Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
+
</tr>
</table>
@@ -432,7 +677,7 @@ document.write("Last Published: " + docu
</div>
<p align="right">
-<font size="-2">by Dominik Stadler</font>
+<font size="-2">by Dominik Stadler, Marius Volkhart</font>
</p>
</div>
<!--+
Modified: poi/site/src/documentation/content/xdocs/components/logging.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/components/logging.xml?rev=1896961&r1=1896960&r2=1896961&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/components/logging.xml (original)
+++ poi/site/src/documentation/content/xdocs/components/logging.xml Wed Jan 12 13:02:04 2022
@@ -24,11 +24,20 @@
<title>Apache POI - Logging Framework</title>
<authors>
<person id="DS" name="Dominik Stadler" email="centic@apache.org"/>
+ <person id="MV" name="Marius Volkhart" email="mariusvolkhart@apache.org"/>
</authors>
</header>
<body>
<section>
+ <title>Introduction</title>
+ <p>
+ Logging in POI is used primarily as a debugging mechanism, not a normal runtime
+ logging system. Logging at levels noisier than WARN is ONLY for autopsy type debugging, and should
+ NEVER be enabled on a production system.
+ </p>
+ </section>
+ <section>
<title>POI 5.0.0 and above</title>
<p>
POI 5.0.0 switched to using <a href="https://www.slf4j.org/">SLF4J</a> for logging. If you want
@@ -38,10 +47,119 @@
</p>
<p>
POI 5.1.0 goes further and specifically uses <a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> directly.
- If you want to continue to use another slf4j compatible logging framework, you can deploy the
+ If you want to continue to use another SLF4J compatible logging framework, you can deploy the
<a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar to
facilitate this.
</p>
+ <p>
+ POI tries to name loggers after the canonical name of the containing class. For example,
+ <code>org.apache.poi.poifs.filesystem.POIFSFileSystem</code>. Use your logging framework's typical
+ mechanisms for activating and deactivating logging for specific loggers.
+ </p>
+ <p>
+ All loggers are named <code>com.apache.poi.*</code>, so rules applied to <code>com.apache.poi</code>
+ will affect all POI loggers.
+ </p>
+ </section>
+ <section>
+ <title>Logging with Log4j 2 Core</title>
+ <p>
+ Capturing POI logs using Log4j 2 Core is as simple as including the
+ <a href="https://logging.apache.org/log4j/2.x/maven-artifacts.html"><code>log4j-core</code></a> JAR in
+ your project.
+ </p>
+
+ <p>
+ The simplest configuration is to capture all POI logs at the same level as your application. You might
+ want to collect all messages <code>INFO</code> and higher, and are OK with capturing POI messages as well.
+ </p>
+ <source>
+ <Configuration ...>
+ <Loggers>
+ <Root level="INFO">
+ ...
+ </Root>
+ </Loggers>
+ </Configuration>
+ </source>
+
+ <p>
+ A more recommended configuration is to capture only messages from loggers you opt in to. For example,
+ you might want to capture all messages from <code>com.example.myapplication</code> at <code>INFO</code>
+ but only POI messages at <code>WARN</code> or more severe.
+ </p>
+ <source>
+ <Configuration ...>
+ <Loggers>
+ <Logger name="com.example.myapplication" level="INFO" />
+ <Logger name="org.apache.poi" level="WARN" />
+
+ <Root level="OFF">
+ ...
+ </Root>
+ </Loggers>
+ </Configuration>
+ </source>
+
+ <p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
+ <source>
+ <Configuration ...>
+ <Loggers>
+ <Logger name="org.apache.poi" level="OFF" />
+
+ <Root level="INFO">
+ ...
+ </Root>
+ </Loggers>
+ </Configuration>
+ </source>
+ </section>
+ <section>
+ <title>Logging with Logback</title>
+ <p>
+ Capturing POI logs using Logback requires adding the
+ <a href="https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html">Log4j to SLF4J Adapter</a> to
+ your project, along with the standard Logback dependencies.
+ </p>
+
+ <p>
+ The simplest configuration is to capture all POI logs at the same level as your application. You might
+ want to collect all messages <code>INFO</code> and higher, and are OK with capturing POI messages as well.
+ </p>
+ <source>
+ <configuration ...>
+ <root level="INFO">
+ ...
+ </root>
+ </configuration>
+ </source>
+
+ <p>
+ A more recommended configuration is to capture only messages from loggers you opt in to. For example,
+ you might want to capture all messages from <code>com.example.myapplication</code> at <code>INFO</code>
+ but only POI messages at <code>WARN</code> or more severe.
+ </p>
+ <source>
+ <configuration ...>
+ <logger name="com.example.myapplication" level="INFO" />
+ <logger name="org.apache.poi" level="WARN" />
+
+ <root level="OFF">
+ ...
+ </root>
+ </configuration>
+ </source>
+
+ <p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
+ <source>
+ <configuration ...>
+ <logger name="org.apache.poi" level="OFF" />
+
+ <root level="INFO">
+ ...
+ </root>
+ </configuration>
+ </source>
</section>
<section>
<title>Legacy POI Logging Framework (no longer supported in POI 5.0.0 and above)</title>
@@ -63,48 +181,48 @@
</p>
</section>
<section><title>POI 4.x and before: Enable Legacy POI Logging Framework</title>
- <p>
- By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful
- to enable logging to see some debug messages printed out which can
- help in analyzing problems.
- </p>
- <p>
- You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty():
- </p>
- <source>
- System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" );
- </source>
- <p>
- Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
- </p>
+ <p>
+ By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful
+ to enable logging to see some debug messages printed out which can
+ help in analyzing problems.
+ </p>
+ <p>
+ You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty():
+ </p>
+ <source>
+ System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" );
+ </source>
+ <p>
+ Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
+ </p>
</section>
<section><title>POI 4.x and before: Available Legacy POI Logging Framework implementations</title>
<p>
The following logger implementations are provided by POI 3 and 4:
</p>
<table>
- <tr>
- <th>Class</th>
- <th>Type</th>
- </tr>
- <tr>
- <td>org.apache.poi.util.SystemOutLogger</td>
- <td>Sends log output to the system console</td>
- </tr>
- <tr>
- <td>org.apache.poi.util.NullLogger</td>
- <td>Default logger, does not log anything</td>
- </tr>
- <tr>
- <td>org.apache.poi.util.CommonsLogger</td>
- <td>Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging,
- log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td>
- </tr>
- <tr>
- <td>org.apache.poi.util.DummyPOILogger</td>
- <td>Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source).
- Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
- </tr>
+ <tr>
+ <th>Class</th>
+ <th>Type</th>
+ </tr>
+ <tr>
+ <td>org.apache.poi.util.SystemOutLogger</td>
+ <td>Sends log output to the system console</td>
+ </tr>
+ <tr>
+ <td>org.apache.poi.util.NullLogger</td>
+ <td>Default logger, does not log anything</td>
+ </tr>
+ <tr>
+ <td>org.apache.poi.util.CommonsLogger</td>
+ <td>Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging,
+ log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td>
+ </tr>
+ <tr>
+ <td>org.apache.poi.util.DummyPOILogger</td>
+ <td>Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source).
+ Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
+ </tr>
</table>
</section>
<section><title>POI 4.x and before: Sending logs to a different log framework</title>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org