日志消息系统#

Framegrabber SDK 的日志消息系统提供了附加信息，有助于追踪用户应用程序中发现的问题。大约 1000 条独立消息提供了有关系统配置的信息、在条件不符合预期时的警告以及更详细的错误描述。

日志消息系统的核心是一个调度器，它将消息转发给 log4cpp^a 和 siso_log 库。GenICam 和 pylon SDK 使用日志库 log4cpp 来向控制台、日志文件、syslog、pylon Event Logger Application 以及其他目标位置输出日志。用户应用程序可以使用 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.

类别指定日志消息的来源，追加器（appender）指定日志消息的目标。

配置 Log4cpp 类别#

类别的选项为 <min-severity>[, <appender>[...]]。该值对应于 <min-severity> 可以是：

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

<min-severity> 指定了要为该类别及其所有子类别报告的日志消息的严重性阈值。的可选列表 <appender> 指定应将该类别及其所有子类别的日志消息转发到哪个 appender。

类别选项会被所有子类别继承，但可以通过为子类别提供单独的选项来覆盖。同样，所有孙类别也会继承子类别的配置。

大多数配置文件都是通过使用特殊指定项为所有类别设置合理的默认值来开始的 rootCategory。例如：

log4j.rootCategory=NOTICE, stdout

此配置选项发送该严重程度的所有消息 FATAL, ALERT, CRIT, ERROR, WARN和 NOTICE 到 appender stdout。您必须在配置文件中定义 appender，如配置 Log4cpp Appenders.

日志级别的映射#

中所述。

严重性	siso_log	log4cpp
较低	TRACE	DEBUG
	DEBUG	INFO
	INFO	注意
	警告	警告
	错误	错误
更高	致命	严重、致命、警报

配置 Log4cpp Appenders#

若要将日志消息定向至某个目标，必须在配置文件中定义并配置 appender。appender 必须包含在配置文件的 category 配置中。

随 Framegrabber SDK 一起安装的 log4cpp 库提供了不同类型的 appender。每种类型的 appender 都有一组可配置参数，用于定义例如日志文件的命名方式、保存位置以及是否应限制大小等。

若要定义 appender，名称将作为键给出 log4cpp.appender 层级，且类型指定为值。例如，以下行定义了一个名为 stdout 它将日志消息写入控制台：

log4cpp.appender.stdout=ConsoleAppender

您可以通过在具名 appender 下方的层级中设置选项来进一步配置该 appender。例如，以下行更改了日志消息的格式：

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

格式化日志消息#

所有 appender 都共享一些通用选项，用于通过设置和配置来格式化日志消息 layout。有两种简单、固定且无法进一步配置的布局： SimpleLayout 和 BasicLayout. PatternLayout 可以通过设置 ConversionPattern.

选项 ConversionPattern 是一个格式字符串，可以包含以下格式说明符以及应出现在所有日志消息中的文本：

说明符	含义
%%	字符 `%`
%c	Category
%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}.

记录日志到文件#

有两个将日志消息存储在文件中的 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 可以进行设置以更改轮转前的最大文件大小。默认值为 maxFileSize 为 10 MB。若要设置允许的备份文件数量，您可以设置 maxBackupIndex。默认值为 maxBackupIndex 为 1。

使用 Pylon Event Logger#

除了 log4cpp 库之外，您还可以使用 pylon Event Logger Application 来显示、过滤和高亮显示日志消息。

如果从 pylon Event Logger 应用程序启动用户应用程序，系统会自动生成并使用一个配置文件，从而确保 pylon Event Logger 应用程序能够接收来自用户应用程序的日志消息。

如果您以其他方式启动用户应用程序，则 log4cpp 配置必须包含 EltAppender。该 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 库接收日志消息#

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。
第三个参数是日志记录器（类别）的名称。
第四个参数是严重性，也称为“日志级别”或“优先级”。
第五个参数是日志消息。
第六和第七个参数是标签数量以及指向标签数组的指针。标签用于向日志消息添加附加元数据，例如设备关系。
回调函数的最后一个参数是指向随调用一同提供的指针 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().