ASF Bugzilla – Attachment 37741 Details for
Bug 65153
Update logging documentation
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
[patch]
New documentation
Update_logging_docs_for_Log4j_2.patch (text/plain), 9.83 KB, created by
Marius Volkhart
on 2021-02-21 22:44:01 UTC
(
hide
)
Description:
New documentation
Filename:
MIME Type:
Creator:
Marius Volkhart
Created:
2021-02-21 22:44:01 UTC
Size:
9.83 KB
patch
obsolete
>Index: src/documentation/content/xdocs/components/logging.xml >IDEA additional info: >Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP ><+>UTF-8 >=================================================================== >diff --git a/src/documentation/content/xdocs/components/logging.xml b/src/documentation/content/xdocs/components/logging.xml >--- a/src/documentation/content/xdocs/components/logging.xml (revision 1886770) >+++ b/src/documentation/content/xdocs/components/logging.xml (date 1613946449238) >@@ -24,6 +24,7 @@ > <title>Apache POI - Logging Framework</title> > <authors> > <person id="DS" name="Dominik Stadler" email="centic@apache.org"/> >+ <person id="MV" name="Marius Volkhart" email="marius@volkhart.com"/> > </authors> > </header> > >@@ -31,30 +32,23 @@ > <section> > <title>Introduction</title> > <p> >- POI uses a custom logging framework which allows to configure where logs are sent to. >+ POI uses the <a href="">Log4j 2</a> logging API. > </p> > <p> >- Logging in POI is used only as a debugging mechanism, not a normal runtime >- logging system. Logging on level debug/info is ONLY for autopsie type debugging, and should >+ 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> >- <p> >- The framework is extensible so that you can send log messages to any logging framework >- that your application uses. >- </p> >- <p> >- A number of default logging implementations are supported by POI out-of-the-box and can be selected via a >- system property. >- </p> > </section> >- <section><title>Enable logging</title> >+ <section><title>General logging behavior</title> > <p> >- By default, logging is disabled in POI. Sometimes it might be useful >- to enable logging to see some debug messages printed out which can >- help in analyzing problems. >+ 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> >- 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(): >+ All loggers are named <code>com.apache.poi.*</code>, so rules applied to <code>com.apache.poi</code> will >+ affect all POI loggers. > </p> > <source> > System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" ); >@@ -63,53 +57,101 @@ > 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>Available logger implementations</title> >+ <section><title>Log4j 2 Core Examples</title> > <p> >- The following logger implementations are provided by POI: >+ 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> >- <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> >- </table> >- </section> >- <section><title>Sending logs to a different log framework</title> > <p> >- You can send logs to other logging frameworks by implementing the interface <em>org.apache.poi.util.POILogger</em>. >+ 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>Implementation details</title> >+ <section><title>Logback Examples</title> > <p> >- Every class uses a <code>POILogger</code> to log, and gets it using a static method >- of the <code>POILogFactory</code> . >+ 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> >- Each class in POI can log using a <code>POILogger</code>, which is an abstract class. >- We decided to make our own logging facade because:</p> >- <ol> >- <li>we need to log many values and we put many methods in this class to facilitate the >- programmer, without having him write string concatenations;</li> >- <li>we need to be able to use POI without any logger package present.</li> >- </ol> >+ 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> > </body> > <footer>
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
Attachments on
bug 65153
: 37741