記錄訊息系統#

Framegrabber SDK 的記錄訊息系統提供其他資訊，這對追蹤使用者應用程式中觀察到的問題非常有用。大約 1000 個個別訊息提供有關系統設定的資訊、當狀況不如預期時的警告，以及更詳細的錯誤描述。

記錄訊息系統的核心是一個分發器，它會將訊息轉發給 log4cpp^a 以及 siso_log library。GenICam 與 pylon SDK 使用記錄 library log4cpp 來提供將記錄輸出至主控台、記錄檔、syslog、pylon Event Logger Application 以及其他目的地的功能。透過 siso_log library，使用者應用程式可以註冊回呼處理常式以接收警告與錯誤訊息。

log4cpp 是 Log4j 的 C++ 改編版本，您可以在 SourceForge 上找到它。log4cpp 最初是在 Framegrabber SDK 5.11.3 版本中開始使用。舊版本的 Framegrabber SDK 使用的是 log4cxx，這是 log4cpp 的替代方案。 ↩

設定 Log4cpp 進行記錄#

影像 log4cpp library 可以使用設定檔進行設定。您可以在安裝目錄的下列檔案中找到 Framegrabber SDK 的預設設定 bin/BaslerFgSdkLogging.properties。若要變更設定，您可以編輯此檔案，或者提供您自己的設定檔並設定環境變數 BASLER_FGSDK_LOGGING_CONFIG 以指向該檔案的位置。

的設定檔是 log4cpp 一個文字檔。檔案中的每一行都可以包含一個設定選項，其格式如下 <key>=<value>，以及以 # 字元開頭的可選註解。亦允許使用空白行以及僅包含註解的行。

<key> 是一個階層式元素，各階層之間以 . 字元分隔。階層的最頂層始終為 log4cpp，或者您也可以使用 log4j。階層的第二層為 category （包含 rootCategory) 或 appender.

類別指定了日誌訊息的來源，而附加程式（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 library 的命名方式。例如，在使用 siso_log library 或 microDisplay X 中的 Debug 對話方塊時，您可能會遇到這些內部記錄層級。

嚴重性	siso_log	log4cpp
lower	TRACE	DEBUG
	DEBUG	INFO
	INFO	注意
	WARN	WARN
	ERROR	ERROR
較高	FATAL	CRIT、FATAL、ALERT

設定 Log4cpp 附加器#

若要將記錄訊息導向至特定目的地，您必須在設定檔中定義並設定 appender。該 appender 必須包含在設定檔的 category 設定中。

隨 Framegrabber SDK 一起安裝的 log4cpp 程式庫提供了不同類型的 appender。每種類型的 appender 都有一組可設定的參數，例如用於定義記錄檔的命名方式、儲存位置以及是否限制其大小。

若要定義附加程式，需將名稱作為 log4cpp.appender 階層中的鍵（key），並將類型指定為值（value）。例如，以下行定義了一個名為 stdout 的附加程式，它會將日誌訊息寫入主控台：

log4cpp.appender.stdout=ConsoleAppender

您可以在具名附加程式下方的階層中設定選項來進一步設定該附加程式。例如，以下行變更了日誌訊息的格式：

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

格式化記錄訊息#

所有附加程式 (Appender) 都共用一些通用選項，用於透過設定與配置來格式化日誌訊息 layout。有兩個簡單且無法進一步配置的固定版面配置 (Layout)： SimpleLayout 和 BasicLayout. PatternLayout 可以透過設定 ConversionPattern.

選項 ConversionPattern 是一個格式字串，可以包含下列格式規範以及應出現在所有日誌訊息中的文字：

指定符	含義
%%	字元 `%`
%c	Category
%d	日期（請參閱下方）
%m	記錄訊息
%n	換行符號
%p	Priority（嚴重性）
%r	自建立版面配置以來經過的毫秒數
%R	自 1970 年 1 月 1 日以來經過的秒數
%t	Thread ID
%u	Clock ticks since start of process

日期格式規範會根據系統指定的短日期格式新增日期與時間。若要自訂日期格式，可以在日期格式規範後面加上以大括號括起來的 strftime 格式規範 (%d{...})。請參閱 strftime documentation 以取得更多詳細資料。strftime 格式指定元的唯一變更為，指定元 %l 會印出補齊至三位數的毫秒數（前面補零）。例如，若要以包含毫秒的擴充 ISO 8601 格式列印日期和時間，請使用 %d{%FT%T.%l%z}或 %d{%Y-%m-%dT%H:%M:%S.%l%z}.

記錄至檔案#

有兩個將日誌訊息儲存至檔案的附加程式 (Appender)： 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 可以進行設定以變更輪替 (Rolling) 前的最大檔案大小。預設值 maxFileSize 為 10 MB。若要設定允許的備份檔案數量，您可以設定 maxBackupIndex。預設值 maxBackupIndex 為 1。

使用 Pylon Event Logger#

除了 log4cpp 程式庫之外，您也可以使用 pylon Event Logger Application 來顯示、篩選及反白顯示記錄訊息。

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

如果您以不同的方式啟動使用者應用程式，則 log4cpp 組態必須包含 EltAppender。Vignetting Correction EltAppender 透過網路介面傳送日誌訊息來運作，您必須使用以下項目指定所使用的連接埠 portNumber。此連接埠必須與 pylon 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 Library 接收記錄訊息#

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 Manual 的先決條件章節。

若要開始使用 siso_log 程式庫，請先呼叫 SisoLog_InitLibrary() 以執行初始化。

使用 SisoLog_RegisterLogMsgCallback() 您可以註冊一個型別為 FuncType_LogMsgCallback的函式，每當記錄訊息系統回報嚴重性為 WARN, ERROR或 FATAL 的記錄訊息時，就會呼叫該函式。在一個處理程序中，您只能註冊一個函式。

參數位於 SisoLog_RegisterLogMsgCallback() 回呼函式：

回呼函式的前兩個參數是處理程序 ID 與執行緒 ID。
第三個參數是記錄器（類別）的名稱。
第四個參數是嚴重性，也稱為「log level」或「priority」。
第五個參數是記錄訊息。
第六和第七個參數是標籤數量以及指向標籤陣列的指標。標籤可用於將額外的詮釋資料（例如裝置關聯）新增至記錄訊息中。
回呼函式的最後一個參數是在呼叫 SisoLog_RegisterLogMsgCallback() 時所提供的指標，可用作指向內容結構或類別的指標，例如代表使用者應用程式的類別實例的 this 指標。

註冊回呼函式後，應用程式必須呼叫 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().