log4cpp快速使用指南

log4cpp是個基於LGPL的開源項目，是基於優秀的日誌處理跟蹤項目Java語言的log4j移植過來的。
 

log4j介紹的文檔很多，在java領域使用的也比較廣泛，而這個功能強大的庫對國內的C++語言開發人員卻使用的不多。這裏從開發人員使用的角度介紹這個庫，使開發人員用最少的代價儘快掌握這種技術。下面先簡單介紹一下這個項目的優點（也是log4j的優點），然後分原理，手動使用步驟，配置文件驅動方式使用步驟，其他考慮等方面進行討論。以下討論基於log4cpp0.3.4b。

0. 優點

• 提供應用程序運行上下文，方便跟蹤調試；
• 可擴展的、多種方式記錄日誌，包括命令行、文件、回捲文件、內存、syslog服務器、Win事件日誌等；
• 可以動態控制日誌記錄級別，在效率和功能中進行調整；
• 所有配置可以通過配置文件進行動態調整；
• 多語言支持，包括Java（log4j），C++（log4cpp、log4cplus），C（log4c），python（log4p）等；

回頁首

 

1. 原理

log4cpp有3個主要的組件：categories（類別）、appenders（附加目的地）、和 layouts（佈局）。（爲了方便大家理解，文中儘量使用英文原詞）

layout類控制輸出日誌消息的顯示樣式（看起來像什麼）。log4cpp當前提供以下layout格式：

log4cpp::BasicLayout 	   // 以“時間戳 優先級（priority，下文介紹）
                        // 類別（category，下文介紹）
		   // NDC標籤（nested diagnostic contexts 下文介紹）: 日誌信息”。
	             // 如：1056638652 INFO main : This is some info
log4cpp::PatternLayout 	// 讓用戶根據類似於 C 語言 printf 函數的轉換模式來指定輸出格式。格式定義見代碼附帶文檔。
log4cpp::SimpleLayout 	// 以“優先級（priority） - 日誌信息”格式顯示。 

 

appender類用來輸出日誌（被layout格式化後的）到一些設備上。比如文件、syslog服務、某個socket等。可以定義自己的appender類輸出日誌信息到別的設備上，比如應用自身的日子處理進程、數據庫等。appender和layout的關係是layout附在appender上，appender類調用layout處理完日誌消息後，記錄到某個設備上。log4cpp當前提供以下appender：

log4cpp::IdsaAppender 			// 發送到IDS或者logger, 詳細見 http://jade.cs.uct.ac.za/idsa/
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列表。

爲了更好的理解上面的概念下面以手動使用方式舉例。

回頁首

 

2. 手動使用步驟

手動使用log4cpp的基本步驟如下：

1. 實例化一個layout 對象；
2. 初始化一個appender 對象；
3. 把layout對象附着在appender對象上；
4. 調用log4cpp::Category::getInstance("name"). 實例化一個category對象；
5. 把appender對象附到category上（根據additivity的值取代其他appender或者附加在其他appender後）。
6. 設置category的優先級；

// FileName: test_log4cpp1.cpp
// Test log4cpp by manual operation.
// Announce: use as your own risk.
// Compile : g++ -otest1 -llog4cpp test_log4cpp1.cpp
// Run     : ./test1
// Tested  : RedHat 7.2 log4cpp0.3.4b
// Author  : liqun ([email protected])
// Data    : 2003-6-27

#include	"log4cpp/Category.hh"
#include	"log4cpp/FileAppender.hh"
#include	"log4cpp/BasicLayout.hh"

int main(int argc, char* argv[])
{
        // 1實例化一個layout 對象
        log4cpp::Layout* layout = 
        new log4cpp::BasicLayout();

        // 2. 初始化一個appender 對象
	log4cpp::Appender* appender = new 
              log4cpp::FileAppender("FileAppender",
              "./test_log4cpp1.log");


	// 3. 把layout對象附着在appender對象上
	appender->setLayout(layout);

	// 4. 實例化一個category對象
	log4cpp::Category& warn_log = 
        log4cpp::Category::getInstance("mywarn");

	// 5. 設置additivity爲false，替換已有的appender
        warn_log.setAdditivity(false);

	// 5. 把appender對象附到category上
	warn_log.setAppender(appender);

	// 6. 設置category的優先級，低於此優先級的日誌不被記錄
	warn_log.setPriority(log4cpp::Priority::WARN);

	// 記錄一些日誌
	warn_log.info("Program info which cannot be wirten");
	warn_log.debug("This debug message will fail to write");
	warn_log.alert("Alert info");

	// 其他記錄日誌方式
	warn_log.log(log4cpp::Priority::WARN, "This will be a logged warning");
	log4cpp::Priority::PriorityLevel priority;
	bool this_is_critical = true;
	if(this_is_critical)
		priority = log4cpp::Priority::CRIT;
	else
		priority = log4cpp::Priority::DEBUG;
	warn_log.log(priority,"Importance depends on context");
	
	warn_log.critStream() << "This will show up << as " 
	<< 1 << " critical message" 
	<< log4cpp::CategoryStream::ENDLINE;

	// clean up and flush all appenders
	log4cpp::Category::shutdown();
	return 0;
}

回頁首

 

3. 配置文件驅動方式使用步驟

另一個非常優秀的特徵就是通過讀取配置文件，確定category、appender、layout等對象。也是我們非常推薦的使用方式，可以靈活地通過配置文件定義所有地對象及其屬性，不用重新編碼，動態更改日誌記錄的策略。

Log4cpp主要提供了 log4cpp::PropertyConfigurator 和log4cpp::SimpleConfigurator兩種機制（文件格式），但 log4cpp::SimpleConfigurator將來不再支持了，而且格式非常簡單，這裏就不多說明，自己看源碼吧。

配置文件的格式和log4j的配置文件一樣，是標準的java屬性文件格式。下面是附帶的例子配置文件：

# a simple test config
#定義了3個category sub1, sub2, sub1.sub2
log4j.rootCategory=DEBUG, rootAppender
log4j.category.sub1=,A1
log4j.category.sub2=INFO
log4j.category.sub1.sub2=ERROR, A2

# 設置sub1.sub2 的additivity屬性
log4j.additivity.sub1.sub2=false

#定義rootAppender類型和layout屬性
log4j.appender.rootAppender=org.apache.log4j.ConsoleAppender
log4j.appender.rootAppender.layout=org.apache.log4j.BasicLayout

#定義A1的屬性
log4j.appender.A1=org.apache.log4j.FileAppender
log4j.appender.A1.fileName=A1.log
log4j.appender.A1.layout=org.apache.log4j.SimpleLayout

#定義A2的屬性
log4j.appender.A2=org.apache.log4j.ConsoleAppender
log4j.appender.A2.layout=org.apache.log4j.PatternLayout
log4j.appender.A2.layout.ConversionPattern=The message '%m' at time %d%n 

 

配置文件語法如下，不是很規範，結合上面的例子，應該可以看懂。

		log4j / log4cpp . [category / appender].[category or appender 's name].[category or appender 's property] 
= [Appender / Layout / property's value / Priority, appender name1 [appender name2 ...]]

	[appender]
		{ConsoleAppender}
		{FileAppender}	// 當appender的類型是FileAppender時，可以定義它下面的屬性。
			[fileName]	string	foobar	// 格式是：屬性名 值的類型 缺省值
			[append]	bool	true
		{RollingFileAppender}
			[fileName] 	string	foobar
			[maxFileSize]	num	10*1024*1024
			[maxBackupIndex]	num	1
			[append]	bool	true
		{SyslogAppender}
			[syslogName]	string	syslog
			[syslogHost]	string	localhost
			[facility]	num	-1	// * 8 to get LOG_KERN, etc. compatible values. 
			[portNumber]	num	-1
		{IdsaAppender}
			[idsaName]	string	foobar
		{Win32DebugAppender}
		{NTEventLogAppender}
			[source]	string	foobar
			
			[threshold]	string ""	// 全部 
			// 如果此類型appender需要layout，必須定義此appender的下面屬性
			[layout]
				{BasicLayout}	
				{SimpleLayout}
				{PatternLayout}		// 當layout的值是BasicLayout時，需要定義下面的屬性。
					[ConversionPattern]
					
	[rootCategory]
	[additivity]
		[category name]	bool	true
		

 

基本使用步驟是：

1. 讀取解析配置文件；
2. 實例化category對象；
3. 正常使用這些category對象進行日誌處理；

下面是個簡單的使用代碼，使用起來是非常方便的：

// FileName: test_log4cpp2.cpp
// Test log4cpp by config file.
// Announce: use as your own risk.
// Compile : g++ -llog4cpp test_log4cpp2.cpp
// Run     : ./a.out
// Tested  : RedHat 7.2 log4cpp0.3.4b
// Author  : liqun ([email protected])
// Data    : 2003-6-27

#include "log4cpp/Category.hh"
#include "log4cpp/PropertyConfigurator.hh"

int main(int argc, char* argv[])
{
	// 1 讀取解析配置文件
	// 讀取出錯, 完全可以忽略，可以定義一個缺省策略或者使用系統缺省策略
	// BasicLayout輸出所有優先級日誌到ConsoleAppender
    try { 
		log4cpp::PropertyConfigurator::configure("./log4cpp.conf");
	} catch(log4cpp::ConfigureFailure& f) {
		std::cout << "Configure Problem " << f.what() << std::endl;
        return -1;
    }
	
	// 2 實例化category對象
	// 這些對象即使配置文件沒有定義也可以使用，不過其屬性繼承其父category
	// 通常使用引用可能不太方便，可以使用指針，以後做指針使用
	// log4cpp::Category* root = &log4cpp::Category::getRoot();
    log4cpp::Category& root = log4cpp::Category::getRoot();
	
    log4cpp::Category& sub1 = 
        log4cpp::Category::getInstance(std::string("sub1"));

    log4cpp::Category& sub3 = 
        log4cpp::Category::getInstance(std::string("sub1.sub2"));

	// 3 正常使用這些category對象進行日誌處理。
	// sub1 has appender A1 and rootappender.
	sub1.info("This is some info");
	sub1.alert("A warning");
	
	// sub3 only have A2 appender.
	sub3.debug("This debug message will fail to write");
	sub3.alert("All hands abandon ship");
	sub3.critStream() << "This will show up << as " << 1 << " critical message" 
	<< log4cpp::CategoryStream::ENDLINE;
	sub3 << log4cpp::Priority::ERROR 
              << "And this will be an error"  
              << log4cpp::CategoryStream::ENDLINE;
	sub3.log(log4cpp::Priority::WARN, "This will be a logged warning");
	
	return 0;
}

回頁首

 

4. 相關考慮

性能問題，可能是很多想使用log4cpp的程序員關心的問題。在參考資料2中有一段描述。結論就是log4j以及log4cpp是以性能爲首要目標的；如果關閉日誌記錄的話，對性能影響可以忽略；打開日誌記錄，主要消耗是在記錄動作，而不是庫的管理過程；所以你儘可放心的使用。實在要深究性能的話。可以從下面方面提高：

輸出的日誌消息不要使用複雜的轉換或者處理，比如： sub1.debug(string("Current num is") + i + GetCurStat()); 這種情況即使不進行日誌處理，括號中的語句還是會執行。變通方法是：

if(sub1.isDebugEnabled())
{
	sub1.debug(string("Current num is") + i + GetCurStat());
}

 

安全性問題對於商業軟件開發可能也是問題。可能不希望別人通過修改配置文件獲取程序的調試等程序內部運行情況的日誌信息。比較穩妥的方案或者是加密配置文件，運行中解密，輸出到臨時文件後讀取；或者在發行版本里讀取配置文件後，強行把低於某個優先級的category設到比較高的優先級。

多線程安全性問題。當前log4cpp還沒有宣稱自己是多線程安全的，不過其代碼中大多數可能衝突的地方都增加了線程互斥控制，對多線程環境應該問題不大。但爲了加入這個特性，linux下編譯log4cpp時，configure請加入--with-pthreads 或者--with-omnithreads選項。Win版本已經加入對MS線程的支持。