第 14 章 日志子系统
14.1. 介绍
14.1.1. 日志概述
JBoss EAP 6 提供了高度可配置的日志功能以用于内部或应用程序。日志子系统基于 JBoss LogManager，它还支持 JBoss Logging 以外的几个第三方应用程序日志框架。
日志子系统是通过日志类别和处理程序体系来进行配置的。日志类别（Category）定义了要记录哪些消息，而日志处理程序（Handler）则定义如何处理这些消息（写入到磁盘、发送到控制台等）。
日志配置集（Logging Profile）允许创建日志配置的唯一名称并分配给不依赖其他日志配置的应用程序。日志配置集的配置和主日志子系统的配置基本上是一样的。
14.1.2. JBoss LogManager 支持的应用程序日志框架
JBoss LogManager 支持下列日志框架：
- JBoss EAP 6 里包含的 JBoss Logging
- Apache Commons Logging - http://commons.apache.org/logging/
- Simple Logging Facade for Java (SLF4J) - http://www.slf4j.org/
- Apache log4j - http://logging.apache.org/log4j/1.2/
- Java SE Logging (java.util.logging) - http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html
14.1.3. 配置引导日志
引导日志（ JBoss Logging）记录服务器启动（或"引导"）时发生的事件。
服务器启动时如果有可用的
logging.properties 文件，这些属性配置会用来记录日志子系统初始还前发生的事件。此后，日志子系统将接管事件的记录。
在您用管理 CLI 修改
logging 子系统或手动编辑服务器配置文件时，它会更新 logging.properties 文件。
如果安装时缺失了
logging.properties，在初始化日志子系统前引导过程中出现的任何日志消息都会丢失。而一旦初始化了日志子系统，消息又会出现在日志里。
警告
我们建议您不要直接编辑
logging.properties 文件，除非引导服务器出现严重问题时需要主机或进程控制器的额外日志信息。
14.1.4. 关于垃圾收集日志
垃圾收集日志（Garbage Collection Logging）用普通文本日志文件记录所有的垃圾收集活动。这些日志文件可以用于诊断。从 JBoss EAP 6.3 开始，在所有被支持的配置里（除了 IBM JDK），对于
standalone 模式，垃圾收集日志默认都是启用的。
日志输出到
$EAP_HOME/standalone/log/gc.log.digit 文件。日志轮换已经启用，日志文件的数量限制为 5 且每个文件最大为 3MB。
14.1.5. 隐性的 Logging API 依赖关系
JBoss EAP 6 的日志子系统有一个控制容器是否添加隐性 Logging API 依赖关系到部署里的属性。这个属性默认被设置为
true，表示所有的隐性 Logging API 依赖关系都会被添加至部署里。如果设置为 false，隐性 Logging API 依赖关系就不会被添加。
add-logging-api-dependencies 属性可以用管理 CLI 进行配置。例如：
/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)14.1.6. 默认的日志文件位置
这些日志文件是为默认的日志配置创建的。默认的配置使用定时日志处理程序写入到服务器日志文件里。
| 日志文件 | 描述 |
|---|---|
EAP_HOME/standalone/log/server.log |
服务器日志包含了所有的服务器日志消息，其中包括服务器启动消息。
|
EAP_HOME/standalone/log/gc.log |
垃圾收集日志。包含所有垃圾收集的细节。
|
| 日志文件 | 描述 |
|---|---|
EAP_HOME/domain/log/host-controller.log |
主机控制器引导日志包含和主机控制器启动相关的日志消息。
|
EAP_HOME/domain/log/process-controller.log |
进程控制器引导日志包含和进程控制器启动相关的日志消息。
|
EAP_HOME/domain/servers/SERVERNAME/log/server.log |
名为 server. 的服务器日志包含了所有的服务器日志消息，其中包括服务器启动消息。
|
14.1.7. 日志的过滤器表达式
注意
为 root logger 指定的
filter-spec 不是从其他处理程序继承的。您必须为每个处理程序指定一个 filter-spec。
|
过滤器类型
表达式
| 描述 | 参数 |
|---|---|---|
|
Accept
accept
| 接受所有日志消息 | accept
|
|
Deny
deny
| 拒绝所有日志消息 | deny
|
|
Not
not[filter expression]
| 返回过滤器表达式的相反值 |
将单一过滤器表达式用作参数
not(match("JBAS"))
|
|
All
all[filter expression]
| 返回来自多个过滤器表达式的串联值 |
使用多个用逗号隔开的过滤器表达式
all(match("JBAS"),match("WELD"))
|
|
Any
any[filter expression]
| 返回一个来自多个过滤器表达式的值。 |
使用多个用逗号隔开的过滤器表达式
any(match("JBAS"),match("WELD"))
|
|
Level Change
levelChange[level]
| 用指定的级别修改日志记录 |
以单个字符串级别为参数
levelChange("WARN")
|
|
Levels
levels[levels]
| 用列表里的级别过滤日志消息 |
以用逗号隔开的基于多个字符串的级别为参数
levels("DEBUG","INFO","WARN","ERROR")
|
|
Level Range
levelRange[minLevel,maxLevel]
| 过滤指定级别范围内的日志消息。 |
过滤器表达式使用
[ 来指定最小包含级别以及用 ] 指定最大包含级别。 或者可以使用 ( 或 ) 来指定排除的级别。这个表达式的第一个参数是允许的最小级别，第二是允许的最大级别。
下面是一些例子。
|
Match (match["pattern"]) | 基于常规表达式的过滤器。根据表达式里的指定的模式使用未格式化的消息。 |
以常规表达式为参数
match("JBAS\d+")
|
Substitute (substitute["pattern","replacement value"]) | 这个过滤器用文本替换第一个匹配的模式 |
这个表达式的第一个参数是模式，而第二个参数是替换文本
substitute("JBAS","EAP")
|
Substitute All (substituteAll["pattern","replacement value"]) | 这个过滤器用文本替换所有匹配的模式 |
这个表达式的第一个参数是模式，而第二个参数是替换文本
substituteAll("JBAS","EAP")
|
14.1.8. 关于日志级别
日志级别是一系列排序的枚举值，表示日志消息的性质和严重性。给定日志消息的级别是开发人员用所选的日志框里合适的方法指定的。
JBoss EAP 6 支持受支持的应用日志框架使用的所有日志级别。最常用的 6 个日志级别是（从低到高）：
TRACE, DEBUG, INFO, WARN, ERROR 和 FATAL。
日志类别和处理程序使用日志级别来限制它们负责的日志消息。每个日志级别都分配有一个数值，表示相对于其他日志级别的顺序。日志类别和处理程序分配的日志级别限制它们只成立了该级别或更高级别的消息。例如，级别为
WARN 的日志处理程序只记录级别为 WARN、ERROR 和 FATAL 的日志消息。
14.1.9. 支持的日志级别
| 日志级别 | 值 | 描述 |
|---|---|---|
| FINEST | 300 |
-
|
| FINER | 400 |
-
|
| TRACE | 400 |
用于提供应用程序运行状态详细信息的消息。
TRACE 级别的消息通常在调试应用程序时被捕获。
|
| DEBUG | 500 |
用于指明应用程序的单独请求或活动进度的消息。
TRACE 级别的消息通常在调试应用程序时被捕获。
|
| FINE | 500 |
-
|
| CONFIG | 700 |
-
|
| INFO | 800 |
用于表示应用程序总体进度的消息。通常用于应用程序启动、关闭或其他主要的生命周期事件。
|
| WARN | 900 |
用于表示未发生错误但并不理想的情形。它可以表示某些在将来可能导致错误的情形。
|
| WARNING | 900 |
-
|
| ERROR | 1000 |
用于表示已经发生并会阻止当前活动或请求的完成、但不会阻止应用程序运行的错误。
|
| SEVERE | 1000 |
-
|
| FATAL | 1100 |
用于表示可能导致严重服务故障和应用程序关闭及 JBoss EAP 6 关闭的事件。
|
14.1.10. 关于日志类别
日志类别定义一系列要捕获的日志消息以及处理这些消息的处理程序。
要记录的日志消息是通过它们的原始 Java 软件包和日志级别来定义的。这些软件包里类的消息以及该日志级别或更低级别的消息将按日志类别记录并发送到指定的日志处理程序。
日志类别可以选择使用 Root Logger 的日志处理程序而不是自己的处理程序。
14.1.11. 关于 Root Logger
Root logger 将记录所有发送到服务器而未按照日志列别记录的日志消息（指定级别）。这些消息会被发送到一个或多个日志处理程序。
在默认情况下，我们配置 Root Logger 使用控制台和定期日志处理程序。定期日志处理程序写入文件
server.log。这个文件有时候被称为服务器日志（Server Log）。
14.1.12. 关于日志处理程序
日志处理程序（Log Handler）定义 JBoss EAP 6 如何记录捕获的日志消息。您可以配置 6 种处理程序类型：
Console、File、Periodic、Size、Async 和 Custom。
14.1.13. 日志处理程序的类型
- Console
- Console 处理程序写入日志消息到主机操作系统的标准输出流（stdout）或标准错误流 （stderr）。当通过命令行提示运行 JBoss EAP 6 时会显示这些消息。除非配置操作系统捕获标准输出和标准错误流，来自 Console 日志处理程序的消息不会被保存。
- File
- File 日志处理程序是最简单的处理程序，它将日志消息写入到指定文件里。
- Periodic
- Periodic 日志处理程序将日志消息写入到命名文件，直到指定的时间过期。一旦超过指定的时间，文件将通过附件指定的时间戳来改名，而处理程序继续写入到根据原来名称新创建的日志文件。
- Size
- Size 日志处理程序将日志消息写入到命名文件，直至到达指定的文件大小。一旦超过指定的大小，文件将通过数字前缀改名，而处理程序继续写入到根据原来名称新创建的日志文件。每个 Size 日志处理程序必须指定以这种方式保存的文件的最大数目。
- Async
- Async 日志处理程序是为一个或多个其他日志处理程序提供异步行为的 Wrapper 日志处理程序。这对于有高延迟性或其他性能问题的日志处理程序来说很有用，例如写入日志文件到网络文件系统。
- Custom
- Custom 日志处理程序让您可以配置新的日志处理程序类型。Custom 日志处理程序必须实现为继承
java.util.logging.Handler的 Java 类，并包含在模块里。 - syslog
- Syslog 处理程序用于发送消息到远程日志服务器。它允许多个应用程序发送它们的日志消息到相同的服务器，一起进行解析。
14.1.14. 关于日志格式器
日志格式器（Log Formatter）是日志处理程序的配置属性，它定义日志消息的外观。它是基于
java.util.Formatter 类的语法的子字符串。
例如 default 配置里的日志格式器
%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n，它创建这样的日志消息：
15:53:26,546 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990
14.1.15. 日志格式器语法
| 符号 | 描述 |
|---|---|
%c | 日志事件的类别 |
%p | 日志条目的级别（INFO/DEBUG/etc） |
%P | 日志条目的地区级别 |
%d | 当前的日期/时间：date/time (yyyy-MM-dd HH:mm:ss,SSS form) |
%r | 相对时间（日志被初始化起的毫秒数） |
%z | 时区 |
%k | 日志资源关键字（用于日志消息的本地化） |
%m | 日志消息（包含关于异常的跟踪信息） |
%s | 简单的日志消息（无异常跟踪信息） |
%e | 异常跟踪信息（无扩展模块信息） |
%E | 异常跟踪信息（有扩展模块信息） |
%t | 当前线程的名称 |
%n | 新行符号 |
%C | 调用日志方法（慢速）的代码的类 |
%F | 调用日志方法（慢速）的代码的文件名 |
%l | 调用日志方法（慢速）的代码的位置 |
%L | 调用日志方法（慢速）的代码的行号 |
%M | 调用日志方法（慢速）的代码的方法 |
%x | 嵌套的诊断上下文 |
%X | 消息诊断上下文 |
%% | 百分比（已完成） |
