| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>Logging - Apache FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="Apache FreeMarker Manual"> |
| <meta property="og:title" content="Logging"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/pgui_misc_logging.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/pgui_misc_logging.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">Programmer's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_misc_logging.html"><span itemprop="name">Logging</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker Manual","Programmer\'s Guide","Miscellaneous","Logging"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="pgui_misc_logging" itemprop="headline">Logging</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_61" data-menu-target="autoid_61">Logging library selection</a></li><li><a class="page-menu-link" href="#autoid_62" data-menu-target="autoid_62">Logging categories</a></li></ul> </div> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_61">Logging library selection</h2> |
| |
| |
| <p>Is short, the recommended setup in contemporary application |
| (as of 2015) is using SLF4J API for logging everywhere. To get |
| FreeMarker 2.3.x. to use SLF4J, simply add the |
| <code class="inline-code">org.slf4j:log4j-over-slf4j</code> dependency to your |
| project, and ensure that <code class="inline-code">log4j:log4j</code> isn't |
| present. (Starting from FreeMarker 2.4.x you don't need |
| <code class="inline-code">log4j-over-slf4j</code> anymore, though it does no harm |
| either.)</p> |
| |
| <p>Read on if you are curious about the details, or if you can't |
| use SLF4J...</p> |
| |
| <p>FreeMarker integrates with the following logging libraries: |
| <a href="http://www.slf4j.org/">SLF4J</a>, <a href="http://commons.apache.org/logging/">Apache Commons |
| Logging</a>, <a href="http://jakarta.apache.org/log4j">Log4J</a> 1.x, <a href="http://jakarta.apache.org/avalon/logkit">Avalon |
| LogKit</a>, and <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a>. |
| By default, FreeMarker will look for the these logging libraries in |
| the following order, and will automatically use the first one it |
| finds (in 2.3.x): Log4J (will use SLF4J instead if it's a |
| properly installed <code class="inline-code">log4j-over-slf4j</code>, since |
| 2.3.22), Apache Avalon LogKit, <code class="inline-code">java.util.logging</code>. |
| As you can see, Log4j has the highest priority. The presence of |
| Log4j is simply detected from the presence of the |
| <code class="inline-code">org.apache.log4j.Logger</code> class, which means that |
| Log4j redirections like <code class="inline-code">log4j-over-slf4j</code> or |
| <code class="inline-code">log4j-1.2-api</code> will also get the highest |
| priority.</p> |
| |
| <p>Prior to FreeMarker 2.4, SLF4J and Apache Commons Logging |
| aren't searched automatically due to backward compatibility |
| constraints. But if you have |
| <code class="inline-code">org.slf4j:log4j-over-slf4j</code> properly installed |
| (means, you have no real Log4j in your class path, and SLF4J has a |
| backing implementation like <code class="inline-code">logback-classic</code>), |
| then FreeMarker will use the SLF4J API directly instead of the Log4j |
| API (since FreeMarker 2.3.22).</p> |
| |
| <p>Note that a similar trick can be applied for logging into |
| Log4j2: If <code class="inline-code">org.apache.logging.log4j:log4j-1.2-api</code> |
| is present, FreeMarker 2.3.x will pick that as it looks like Log4j, |
| but all the messages will actually go to Log4j2.</p> |
| |
| <p>If the auto detection doesn't give you the result that you |
| want, you can set the |
| <code class="inline-code">org.freemarker.loggerLibrary</code> system property to |
| select a logger library explicitly (since 2.3.22), like:</p> |
| |
| |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">java <em>...</em> -Dorg.freemarker.loggerLibrary=SLF4J</pre> </div> |
| |
| |
| <p>The supported system property values are: |
| <code class="inline-code">SLF4J</code>, <code class="inline-code">CommonsLogging</code>, |
| <code class="inline-code">JUL</code> (for <code class="inline-code">java.util.logging</code>), |
| <code class="inline-code">Avalon</code>, <code class="inline-code">auto</code> (the default |
| behavior), <code class="inline-code">none</code> (disables logging).</p> |
| |
| <p>Note that for reliable operation, the system property should |
| be set when the JVM starts (like above), not later from Java |
| code.</p> |
| |
| <p>Using SLF4J is recommended, as it works best with FreeMarker, |
| and also because it will be the highest priority auto detected |
| logger starting from FreeMarker 2.4.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_62">Logging categories</h2> |
| |
| |
| <p>All log messages produced by FreeMarker are logged with a |
| logger category that starts with <code class="inline-code">freemarker.</code>. The |
| currently used logger categories are:</p> |
| |
| <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Log category name</th> |
| |
| |
| <th>Purpose</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">freemarker.beans</code></td> |
| |
| |
| <td>Logs messages of the Beans wrapper module.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.cache</code></td> |
| |
| |
| <td>Logs messages related to template loading and |
| caching.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.runtime</code></td> |
| |
| |
| <td>Logs messages related to template execution that doesn't |
| fit any of the more specific categories. Most importantly, it |
| logs template exceptions thrown during template processing |
| (however that should be disabled in modern application; see |
| later).</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.runtime.attempt</code></td> |
| |
| |
| <td>Logs template exceptions thrown during template processing |
| and caught by |
| <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> |
| directives, with DEBUG severity. Note that such exceptions |
| will be still also logged with their normal logger (like |
| <code class="inline-code">freemarker.runtime</code>).</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.servlet</code></td> |
| |
| |
| <td>Logs messages of the <code class="inline-code">FreemarkerServlet</code> |
| class.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.jsp</code></td> |
| |
| |
| <td>Logs messages of the FreeMarker JSP support.</td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">freemarker.configuration</code></td> |
| |
| |
| <td>Logs messages related to configuring FreeMarker, and not |
| fitting any other categories.</td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| |
| <p>One quirk relating this is that FreeMarker will log exceptions |
| during template execution under the |
| <code class="inline-code">freemarker.runtime</code> category even if the exception |
| continues propagating and so eventually will be thrown by |
| <code class="inline-code">Template.process</code> or |
| <code class="inline-code">Environment.process</code> anyway. (Those are the API |
| calls with which the template was invoked from the application or |
| the application framework.) Well behaving applications log the |
| exceptions thrown at them, or rarely, handle them and deliberately |
| don't want to log them. But as FreeMarker has already logged that |
| exception, you will end up one more log entry than expected. To fix |
| that (since 2.3.22), set the |
| <code class="inline-code">log_template_exceptions</code> |
| (<code class="inline-code">Configurable.setLogTemplateExceptions(boolean)</code>) |
| setting to <code class="inline-code">false</code>.</p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
