記錄訊息系統#

Framegrabber SDK 的日誌訊息系統提供了額外資訊，這些資訊對於追蹤使用者應用程式中出現的問題頗有幫助。約有 1000 則獨立訊息，內容涵蓋系統配置資訊、當狀況與預期不符時的警告，以及更詳細的錯誤描述。

日誌訊息系統的核心是一個分派器，它會將訊息轉發至log4cpp^a 以及siso_log函式庫。GenICam 和 pylon SDK 皆採用log4cpp記錄函式庫，以將記錄輸出至控制台、日誌檔案、syslog、pylonEvent Logger 應用程式及其他目的地。透過siso_log函式庫，使用者應用程式可註冊回呼處理常式，以接收警告與錯誤訊息。

log4cpp是 Log4j 的 C++ 移植版本，您可以在SourceForge 上找到它。log4cpp首次出現在Framegrabber SDK 第 5.11.3 版中。Framegrabber SDK 的較早版本則使用log4cxx，這是log4cpp 的替代方案。↩

設定 Log4cpp 進行日誌記錄#

當 log4cpp 可透過設定檔來設定此函式庫。您可以在安裝目錄中的檔案內找到Framegrabber SDK 的預設設定，該檔案位於 bin/BaslerFgSdkLogging.properties. 若要變更設定，您可以編輯此檔案，或者提供您自己的設定檔並設定環境變數 BASLER_FGSDK_LOGGING_CONFIG 以指定檔案的位置。

的設定檔 log4cpp 是一個文字檔案。檔案中的每行可包含一個設定選項，其格式為 <key>=<value>，以及一段以 # 字元。空行以及僅包含註解的行亦被允許。

<key> 是一個層級元素，各層級之間以一個 . 字元。層級結構的頂層總是 log4cpp, 或者您也可以使用 log4j. 層級結構的第二層要麼是 category （包括 rootCategory）或 appender.

「類別」用來指定日誌訊息的來源，「附加器」則用來指定日誌訊息的傳送目的地。

設定 Log4cpp 類別#

某類別的選項有： <min-severity>[, <appender>[...]]. 該數值的值為 <min-severity> 可以是：

FATAL,
ALERT,
CRIT,
ERROR,
WARN,
NOTICE,
INFO，或
DEBUG

<min-severity> 指定該類別及其所有子類別中，需回報之日誌訊息的嚴重性閾值。此可選清單包含： <appender> 指定應將該類別及其所有子類別的日誌訊息轉發至哪個附加器。

類別選項會由所有子類別繼承，但若為某個子類別設定獨立的選項，即可覆寫該設定。同樣地，所有子子類別都會繼承該子類別的設定。

大多數設定檔都會先為所有類別設定合理的預設值，並使用特殊標記 rootCategory. 例如：

log4j.rootCategory=NOTICE, stdout

此設定選項會傳送所有嚴重程度為 FATAL, ALERT, CRIT, ERROR, WARN以及 NOTICE 傳送至附加器 stdout. 您必須依照以下說明，在配置檔中定義該附加器：設定 Log4cpp 附加器.

日誌等級對應表#

Framegrabber SDK 內部採用了一套不同的名稱來標示日誌訊息的嚴重程度，這些名稱遵循先前版本Framegrabber SDK 中所使用的log4cxx函式庫的命名規則。例如，當您使用siso_log函式庫或microDisplay X 中的「除錯」對話方塊時，可能會遇到這些內部日誌等級。

嚴重程度	siso_log	log4cpp
低於	TRACE	DEBUG
	DEBUG	資訊
	資訊	注意
	警告	警告
	錯誤	錯誤
較高	致命	CRIT、FATAL、ALERT

設定 Log4cpp 附加器#

若要將日誌訊息導向特定目的地，您必須在設定檔中定義並設定附加器。該附加器必須包含在設定檔中的類別設定中。

log4cpp函式庫提供了多種不同的附屬程式（appenders），該函式庫可透過安裝「Framegrabber SDK 」來取得。每種附屬程式都有一組可配置的參數，用以定義例如日誌檔案的命名方式、儲存位置，以及是否應限制其大小等。

要定義一個附加器，需將其名稱作為鍵指定於 log4cpp.appender 層級結構，且類型以值的形式指定。例如，以下這行程式碼定義了一個名為 stdout 該程式會將日誌訊息寫入控制台：

log4cpp.appender.stdout=ConsoleAppender

您可以透過在指定附錄器下方的層級中設定選項，進一步配置該附錄器。例如，以下幾行代碼會變更日誌訊息的格式：

log4cpp.appender.stdout.layout=PatternLayout
log4cpp.appender.stdout.layout.ConversionPattern=[%d:%t:%c] %p: %m%n

日誌訊息的格式設定#

所有附加器皆具備一些共通選項，可透過設定與配置來格式化日誌訊息， layout. 共有兩種簡單的固定版型，無法進行進一步設定： SimpleLayout 進行明確的生命週期管理即呼叫 BasicLayout. PatternLayout 可透過設定 ConversionPattern.

該選項 ConversionPattern 是一個格式字串，其中可包含以下格式指定符，以及應出現在所有日誌訊息中的文字：

指定符	含意
%%	這個角色 `%`
%c	類別
%d	日期（見下文）
%m	日誌訊息
%n	行分隔符
%p	優先級（嚴重程度）
%r	自建立版面以來經過的毫秒數
%R	自 1970 年 1 月 1 日以來的秒數
%t	Thread ID
%u	自流程開始以來，計時器持續計時

日期格式標示符會根據系統指定的簡短日期格式，加入日期與時間。若要自訂日期格式，可在日期格式標示符後加上以大括號包圍的 strftime 格式標示符（%d{...}). 請參閱 strftime 文件說明如需進一步詳情。strftime 格式指定符的唯一變更在於，該指定符 %l 會將毫秒數以零墊滿至三位數後輸出。例如，若要以包含毫秒的擴展 ISO 8601 格式輸出日期和時間，請使用以下任一方式： %d{%FT%T.%l%z}，或 %d{%Y-%m-%dT%H:%M:%S.%l%z}.

將日誌記錄至檔案#

有兩種附加程式可將日誌訊息儲存至檔案中： FileAppender 進行明確的生命週期管理即呼叫 RollingFileAppender.

當 FileAppender 有一個必選選項， fileName, 用於設定檔案名稱。例如，若要將訊息記錄至名為 fglib.log 除了主控台之外，設定檔可能如下所示：

log4cpp.rootCategory=NOTICE, stdout, logfile

log4cpp.appender.stdout=ConsoleAppender
log4cpp.appender.stdout.layout=SimpleLayout

log4cpp.appender.logfile=FileAppender
log4cpp.appender.logfile.fileName=fglib.log
log4cpp.appender.logfile.layout=BasicLayout

當 RollingFileAppender 僅會將資料寫入日誌檔案，直到達到指定的檔案大小為止，接著會建立該檔案的備份，並清空檔案以重新開始。與 FileAppender, fileName 用於指定日誌檔的名稱。此外， maxFileSize 可設定為在輪替前變更最大檔案大小。預設值為 maxFileSize 為 10 MB。若要設定允許的備份檔案數量，您可以設定 maxBackupIndex. 的預設值為 maxBackupIndex 是 1。

如何使用 PylonEvent Logger#

除了log4cpp函式庫之外，您也可以使用pylonEvent Logger 應用程式來顯示、篩選及標示日誌訊息。

若您從 pylonEvent Logger 應用程式啟動使用者應用程式，系統會自動產生並使用一個設定檔，以確保 pylonEvent Logger 應用程式能接收來自使用者應用程式的日誌訊息。

如果您以其他方式啟動使用者應用程式，那麼該 log4cpp 設定必須包含 EltAppender中。 EltAppender 其運作方式是透過網路介面傳送日誌訊息，您必須指定所使用的埠號 portNumber. 該連接埠必須與「Event Logger 」應用程式中的設定相符。此情境的預設設定如下所示：

log4j.rootCategory=NOTICE, pylonEventLogger, stdout

log4j.appender.stdout=ConsoleAppender
log4j.appender.stdout.layout=PatternLayout
log4j.appender.stdout.layout.ConversionPattern=[%d:%t:%c] %p: %m%n

log4j.appender.pylonEventLogger=org.apache.log4j.EltAppender
log4j.appender.pylonEventLogger.layout=org.apache.log4j.PatternLayout
log4j.appender.pylonEventLogger.layout.ConversionPattern=[%d:%t:%c] %p: %m%n
log4j.appender.pylonEventLogger.portNumber=12320

在應用程式中使用 siso_log 函式庫接收日誌訊息#

int SisoLog_InitLibrary();

typedef void FuncType_LogMsgCallback(
    tProcessId pid,
    tThreadId tid,
    const char * const logger,
    unsigned int level,
    const char * const msg,
    unsigned int tagcount,
    const tSisoLogTag * const tags,
    void * userdata
);

int SisoLog_RegisterLogMsgCallback(
    FuncType_LogMsgCallback * callback,
    void * userdata);

int SisoLog_SetMode(
    unsigned int mode);

int SisoLog_GetMode(
    unsigned int * mode);

若要接收來自Framegrabber SDK 日誌訊息系統的日誌訊息，請加入該函式庫 siso_log 加入您的應用程式專案，並包含 siso_log.h 在您的原始碼中。請參閱該章節先決條件詳情請參閱《Framegrabber API 》使用手冊。

要開始使用 siso_log 函式庫，首次呼叫 SisoLog_InitLibrary() 以執行初始化。

透過 SisoLog_RegisterLogMsgCallback() 您可以註冊一個類型為 FuncType_LogMsgCallback，該函式隨後會在出現嚴重程度為 WARN, ERROR，或 FATAL 此訊息由日誌訊息系統回報。您在一個程序中只能註冊一個函式。

的參數 SisoLog_RegisterLogMsgCallback() 回調函式：

回調函式的前兩個參數分別是程序和執行緒的 ID。
第三個參數是記錄器的名稱（類別）。
第四個參數是嚴重性，亦稱為「日誌等級」或「優先級」。
第五個參數是日誌訊息。
第六和第七個參數分別是標籤的數量以及指向標籤陣列的指標。標籤用於為日誌訊息新增額外的元資料，例如裝置關聯資訊。
回呼函式的最後一個參數是一個指標，該指標是在呼叫 SisoLog_RegisterLogMsgCallback() 且可用作指向上下文結構體或類別的指標，例如這個代表使用者應用程式的類別實例的指標。

在註冊回調函式之後，應用程式必須呼叫 SisoLog_SetMode() 並通過 SISOLOG_MODE_DEFAULT 以啟用轉發日誌訊息。

停止接收日誌訊息#

int SisoLog_RegisterLogMsgCallback(
    FuncType_LogMsgCallback * callback,
    void * userdata);

int SisoLog_SetMode(
    unsigned int mode);

int SisoLog_FreeLibrary();

若要停止接收來自Framegrabber SDK 日誌訊息系統的日誌訊息：

若要停用轉發日誌訊息，請呼叫 SisoLog_SetMode() 並通過 SISOLOG_MODE_OFF.
透過呼叫以下函式來取消註冊回呼函式： SisoLog_RegisterLogMsgCallback() 並通過 nullptr 無論是回調函式還是使用者上下文指標皆然。
在終止應用程式之前，請呼叫 SisoLog_FreeLibrary().