Logging
Page Contents
记录库选择
简而言之，当前应用程序中推荐的设置(自 2015 年起)是使用 SLF4J API 到处记录。要获取 FreeMarker2.3.x。要使用 SLF4J，只需将org.slf4j:log4j-over-slf4j依赖项添加到您的项目中，并确保log4j:log4j不存在。 (从 FreeMarker 2.4.x 开始，您不再需要log4j-over-slf4j了，尽管它也没有害处.)
如果您对详细信息感到好奇，或者无法使用 SLF4J，请 continue 阅读...
FreeMarker 与以下日志记录库集成：SLF4J，Apache Commons 日志记录，Log4J 1.x，Avalon LogKit和java.util.logging。默认情况下，FreeMarker 将按照以下 Sequences 查找这些日志库，并将自动使用它找到的第一个日志库(在 2.3.x 中)：Log4J(如果安装正确，则将使用 SLF4J log4j-over-slf4j，因为 2.3.22 起) ，Apache Avalon LogKit java.util.logging。如您所见，Log4j 具有最高优先级。仅从org.apache.log4j.Logger类的存在中检测出 Log4j 的存在，这意味着像log4j-over-slf4j或log4j-1.2-api这样的 Log4j 重定向也将获得最高优先级。
在 FreeMarker 2.4 之前，由于向后兼容限制，不会自动搜索 SLF4J 和 Apache Commons Logging。但是，如果您正确安装了org.slf4j:log4j-over-slf4j(意味着，您的 Classpath 中没有 true 的 Log4j，并且 SLF4J 具有像logback-classic这样的支持实现)，那么 FreeMarker 将直接使用 SLF4J API 而不是 Log4j API(因为 FreeMarker 2.3.22 起) 。
请注意，可以使用类似的技巧来登录 Log4j2：如果存在org.apache.logging.log4j:log4j-1.2-api，则 FreeMarker 2.3.x 会选择它类似于 Log4j，但实际上所有消息都将进入 Log4j2.
如果自动检测无法提供所需的结果，则可以将org.freemarker.loggerLibrary系统属性设置为显式选择 Logger 库(自 2.3.22 起)，例如：
java ... -Dorg.freemarker.loggerLibrary=SLF4J
支持的系统属性值是：SLF4J，CommonsLogging，JUL(对于java.util.logging)，Avalon，auto(默认行为)，none(禁用日志记录)。
请注意，为了可靠地操作，应该在 JVM 启动时(如上)设置系统属性，而不是稍后从 Java 代码设置。
建议使用 SLF4J，因为它最适合 FreeMarker，并且因为它将是从 FreeMarker 2.4 开始自动检测到的最高优先级 Logger。
Logging categories
FreeMarker 产生的所有日志消息均以freemarker.开头的 Logger 类别记录。当前使用的 Logger 类别为：
| 日志类别名称 | Purpose |
|---|---|
freemarker.beans | 记录 Bean 包装器模块的消息。 |
freemarker.cache | 记录与模板加载和缓存有关的消息。 |
freemarker.runtime | 记录与模板执行相关的，不适合任何更具体类别的消息。最重要的是，它记录了在模板处理过程中引发的模板异常(但是应在现代应用程序中将其禁用；请参阅下文)。 |
freemarker.runtime.attempt | 记录在模板处理期间抛出的模板异常，并由attempt/recover指令捕获，并具有 DEBUG 严重性。请注意，此类异常仍将使用其常规 Logger(如freemarker.runtime)记录下来。 |
freemarker.servlet | 记录FreemarkerServlet类的消息。 |
freemarker.jsp | 记录 FreeMarker JSP 支持的消息。 |
freemarker.configuration | 记录与配置 FreeMarker 相关的消息，不适合任何其他类别。 |
一个与此相关的怪癖是，即使模板 continue 传播，FreeMarker 也会在模板执行期间将异常记录在freemarker.runtime类别下，因此无论如何最终还是会被Template.process或Environment.process抛出。 (那些是从应用程序或应用程序框架中调用模板的 API 调用.)行为良好的应用程序会记录在它们处抛出的异常，或者很少会处理它们，并且故意不想记录它们。但是由于 FreeMarker 已经记录了该异常，因此您将得到比预期多的一个日志条目。要解决此问题(自 2.3.22 开始)，请将log_template_exceptions(Configurable.setLogTemplateExceptions(boolean))设置设置为false。
