舫摘

知人者智 自知者明 胜人者有力 自胜者强

0%

Log4cpp配置文件格式说明

Posted on Edited on In Disqus:

log4cpp有3个主要的组件：categories（类别）、appenders（附加目的地）、和 layouts（布局），layout类控制输出日志消息的显示样式（看起来像什么）。log4cpp当前提供以下layout格式：

1
2
3
log4cpp::BasicLayout    // 以“时间戳 优先级（priority，下文介绍） 类别（category，下文介绍） NDC标签”
log4cpp::PatternLayout  // 让用户根据类似于 C 语言 printf 函数的转换模式来指定输出格式。
log4cpp::SimpleLayout   // 以“优先级（priority） - 日志信息”格式显示。

appender类用来输出日志（被layout格式化后的）到一些设备上。比如文件、syslog服务、某个socket等。可以定义自己的appender类输出日志信息到别的设备上，比如应用自身的日子处理进程、数据库等。appender和layout的关系是layout附在appender上，appender类调用layout处理完日志消息后，记录到某个设备上。log4cpp当前提供以下appender：

1
2
3
4
5
6
7
8
9
log4cpp::IdsaAppender         // 发送到IDS或者logger,
log4cpp::FileAppender         // 输出到文件
log4cpp::RollingFileAppender  // 输出到回卷文件，即当文件到达某个大小后回卷
log4cpp::OstreamAppender      // 输出到一个ostream类
log4cpp::RemoteSyslogAppender // 输出到远程syslog服务器
log4cpp::StringQueueAppender  // 内存队列
log4cpp::SyslogAppender       // 本地syslog
log4cpp::Win32DebugAppender   // 发送到缺省系统调试器
log4cpp::NTEventLogAppender   // 发送到win 事件日志

category 类真正完成记录日志功能，两个主要组成部分是appenders和priority（优先级）。优先级控制哪类日志信息可以被这个category记录，当前优先级分为：NOTSET, DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, ALERT 或 FATAL/EMERG 。每个日志信息有个优先级，每个category有个优先级，当消息的优先级大于等于category的优先级时，这个消息才会被category记录，否则被忽略。优先级的关系如下。category类和appender的关系是，多个appender附在category上，这样一个日志消息可以同时输出到多个设备上。
NOTSET < DEBUG < INFO < NOTICE < WARN < ERROR < CRIT < ALERT < FATAL = EMERG category被组织成一个树，子category创建时优先级缺省NOTSET，category缺省会继承父category的appender。而如果不希望这种appender的继承关系，log4cpp允许使用additivity标签，为false时新的appender取代category的appender列表。
log4cpp可以用手动方式使用，也可以使用配置文件使用，用配置文件的方式简单，便捷。所有，现在都用配置文件的方式。

log 的优先级别解读，参阅源码log4cpp-0.3.5rc3\include\log4cpp\Priority.hh

由高到低

1
2
3
4
5
6
7
8
9
10
EMERG
FATAL
ALERT
CRIT
ERROR
WARN
NOTICE
INFO
DEBUG
NOTSET

对应到 Category 相应函数，参阅源码log4cpp-0.3.5rc3\include\log4cpp\Category.hh

1
2
3
4
5
6
7
8
9
Category::emerg()
Category::fatal()
Category::alert()
Category::crit()
Category::error()
Category::warn()
Category::notice()
Category::info()
Category::debug()

以上函数都有 2 个重载函数，可分别接受格式化字串或 std::string，例如 debug()，有

1
2
void debug(const char *stringFormat, ...) throw();
void debug(const std::string &message) throw();

关于优先级别使用的建议

  • 开发运行时，设为 DEBUG 级，而正式运营时，则设为 NOTICE ；
  • 一定要显示出来的信息则可以用 NOTICE 或以上级别；
  • 跟踪函数运行痕迹的信息用 INFO 级别；
  • 运行时调试的信息用 DEBUG 级别；
    举例说明
    1
    2
    3
    4
    5
    6
    7
    void initialize(int argc, char *argv[]) {
      log.info("initialize() : argc=%d", argc);
      for (int i = 0; i < argc; ++i) {
        log.debug("initialize() : argv[%d]=%s", i, argv[i]);
      }
      log.notice("initialize() : done");
    }
    log4cpp 的 category 分为 rootCategory 和其它自定义的 category。
    而每个 category 都可以输出到多个 appender。并且 category 也是有包含关系的。
    例如 rootCategory 就是所有 category 的根。而自定义的 category 也可以在配置文件中定义其包含关系。
    先看一个 rootCategory 的配置
    log4cpp.rootCategory=DEBUG, console, sample
    这个定义里，指定了 rootCategory 的 log 优先级是 DEBUG，其 appender 有 2 个，分别是 console 和 sample。
    即是说，等号右边内容以逗号分隔，第一项是优先级别，接下来的都是 appender 名字，可以有一个或多个。
    现在来看看自定义的 category
    log4cpp.category.demo=DEBUG, sample
    这里定义了一个名字为 demo 的 category，其优先级为 DEBUG，appender 为 sample。
    注意， category 和 appender 名字可以完全相同。
    再来看看有包含关系的 category 的定义
    1
    2
    log4cpp.category.demo.son=DEBUG, son
    log4cpp.category.demo.daughter=DEBUG, daughter
    以上定义了 2 个 category，名字分别为 son 和 daughter，其父 category 为 demo。
    son 产生的 log 会写到 son 和 demo 的 appender 中。同理，daughter 的 log 会写到 daughter 和 demo 的 appender 中。
    现在来看看 appender 的定义。appender 有很多种，我这里只介绍几种，分别是
  • ConsoleAppender : 控制台输出，即 std::cout
  • Win32DebugAppender : VC IDE 的输出，即 ::OutputDebugString
  • FileAppender : 文件输出
  • RollingFileAppender : 有待研究

现在看一个 ConsoleAppender 的例子

1
2
3
log4cpp.appender.console=ConsoleAppender
log4cpp.appender.console.layout=PatternLayout
log4cpp.appender.console.layout.ConversionPattern=%d [%p] - %m%n

以上信息解释为：一个名为 console 的 appender，其类型为 ConsoleAppender，即 控制台输出 log 输出的布局是 指定的样式
输出的格式 是%d [%p] - %m%n(稍后再解释)
再看一个 FileAppender 的例子

1
2
3
4
log4cpp.appender.sample=FileAppender
log4cpp.appender.sample.fileName=sample.log
log4cpp.appender.sample.layout=PatternLayout
log4cpp.appender.sample.layout.ConversionPattern=%d [%p] - %m%n

以上信息解释为：一个名为 sample 的 appender，其类型为 FileAppender，即 文件输出指定的 log 文件名为 sample.log，输出的布局是 指定的样式，输出的格式 是%d [%p] - %m%n
对应 category 和 appender 的配置方式，可以发现

  • category 是 “log4cpp.category.” + “category name”
  • category 名字可以用 “.” 分隔，以标识包含关系
  • appender 是 “log4cpp.appender.” + “appender name”
  • appender 名字 不能 用 “.” 分隔，即是说 appender 是没有包含关系的
  • 现在看一个完整的配置文件例子
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    #定义 root category 的属性
    log4cpp.rootCategory=DEBUG, console

    #定义 console 属性
    log4cpp.appender.console=ConsoleAppender
    log4cpp.appender.console.layout=PatternLayout
    log4cpp.appender.console.layout.ConversionPattern=%d [%p] - %m%n

    #定义 sample category 的属性
    log4cpp.category.sample=DEBUG, sample

    #定义 sample appender 的属性
    log4cpp.appender.sample=FileAppender
    log4cpp.appender.sample.fileName=sample.log
    log4cpp.appender.sample.layout=PatternLayout
    log4cpp.appender.sample.layout.ConversionPattern=%d [%p] - %m%n

    #定义 sample.son category 的属性
    log4cpp.category.sample.son=DEBUG, son

    #定义 son appender 的属性
    log4cpp.appender.son=FileAppender
    log4cpp.appender.son.fileName=son.log
    log4cpp.appender.son.layout=PatternLayout
    log4cpp.appender.son.layout.ConversionPattern=%d [%p] - %m%n

    #定义 sample.daughter category 的属性
    log4cpp.category.sample.daughter=DEBUG, daughter

    #定义 daughter appender 的属性
    log4cpp.appender.daughter=FileAppender
    log4cpp.appender.daughter.fileName=daughter.log
    log4cpp.appender.daughter.layout=PatternLayout
    log4cpp.appender.daughter.layout.ConversionPattern=%d [%p] - %m%n
    ConversionPattern 参数解读，参阅源码 log4cpp-0.3.5rc3\src\PatternLayout.cpp
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    %m log message 内容, 即 用户写 log 的具体信息
    %n 回车换行
    %c category 名字
    %d 时间戳
    %p 优先级
    %r 距离上一次写 log 的间隔, 单位毫秒
    %R 距离上一次写 log 的间隔, 单位秒
    %t 线程名
    %u 处理器时间
    %x NDC ?
    窃以为，以下格式就足够了，即输出 “时间 [线程名] 优先级 - log内容 回车换行”
    %d [%t] %p - %m%n
    配置的知识就差不多了，现在看看实际代码应用
    首先是初始化 log4cpp 的配置，例如我的配置文件名是 log4cpp.properties
    1
    2
    3
    4
    5
    try {
      log4cpp::PropertyConfigurator::configure("log4cpp.properties");
    } catch (log4cpp::ConfigureFailure &f) {
      std::cerr << "configure problem " << f.what() << std::endl;
    }
    初始化完成后，就可以这样用了
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    log4cpp::Category &log = log4cpp::Category::getInstance(std::string("sample"));
    log.debug("test debug log");
    log.info("test info log");

    // 用 sample.son
    log4cpp::Category &log = log4cpp::Category::getInstance(std::string("sample.son"));
    log.debug("test debug log of son");
    log.info("test info log of son");

    // 用 sample.daughter
    log4cpp::Category &log = log4cpp::Category::getInstance(std::string("sample.daughter"));
    log.debug("test debug log of daughter");
    log.info("test info log of daughter");

再举一个在自定义类中的使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// demo.h
#include <log4cpp/Category.hh>

namespace demo {

class Sample {
public:
    Sample();
    ~Sample();

public:
    Testing(int i);

private:
    static log4cpp::Category &log;
};

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// demo.cpp
#include "Sample.h"

namespace demo {

log4cpp::Category &Sample::log = log4cpp::Category::getInstance(std::string("sample"));

Sample::Sample() {
    log.debug("Sample::Sample()");
}

Sample::~Sample() {
    log.debug("Sample::~Sample()");
}

Sample::Testing(int i) {
    log.debug("Sample::Testing() : i=%d", i);
}

}