日志系统之ACE日志服务.doc

日志系统之 ACE 日志服务 1 日志系统之日志系统之 ACE 日志服务日志服务 2007 8 22 目 录 1 基本使用 2 1 1 日志输出宏 2 1 2 日志的等级 2 1 3 格式化指令 3 1 4 例 1 日志的简单示例 4 2 日志的输出过滤 5 2 1 输出过滤原理 5 2 2 编译时刻设定 6 2 3 运行时刻设定 8 3 日志的输出重定向 9 3 1 输出重定向的涉及函数 9 3 2 例 2 输出重定向的综合示例 10 4 使用 LOGGING STRATEGY 进行运行时配置 11 4 1 配置选项 11 4 2 例 3 运行配置示例 12 2 ACE 日志服务是 ACE 库的一个功能模块 具有线程安全 灵活 分级显示等特点 可以面向程序调试 运行 测试 和维护等全生命周期 可以选择将信息输出到屏幕 文件 系统日志 如 Windows 下的 Event log 甚至是远程服务器 除此之外 ACE 日志系统支持回调函数以及运行时刻动态配置 Runtime Configuration 1 基本使用 1 1 日志输出宏 ACE 日志的使用主要通过宏 ACE XXX severity formatting args 进行日志输出 其中 severity 为日志等级 见 1 2 小节 formatting args 是要输出的内容 类似 printf 函 数的可变参数 其中也可以包含以 开头的格式化指令 见 1 3 小节 注意日志输出宏包括两层圆括号 外层括号是为了宏展开时指定宏的参数 内层 的括号则为了宏展开成函数后指定函数参数 日志输出宏包括 ACE ERROR level string ACE DEBUG level string ACE TRACE string ACE ASSERT test ACE HEX DUMP level buffer size text ACE RETURN value ACE ERROR RETURN level string value ACE ERROR INIT value flags ACE ERROR BREAK level string 1 2 日志的等级 Severity LevelMeaning LM TRACEMessages indicating function calling sequence LM DEBUGDebugging information LM INFOMessages that contain information normally of use only when debugging a program LM NOTICEConditions that are not error conditions but that may require special handling LM WARNINGWarning messages 日志系统之 ACE 日志服务 3 Severity LevelMeaning LM ERRORError messages LM CRITICALCritical conditions such as hard device errors LM ALERTA condition that should be corrected immediately such as a corrupted system database LM EMERGENCYA panic condition normally broadcast to all users 1 3 格式化指令 CodeArgument TypeDisplays AACE timer tFloating point number long decimal number if platform doesn t support floating point a Aborts the program after displaying output ccharSingle character Cchar Character string narrow characters i dintDecimal number I Indents output according to the nesting depth obtained from ACE Trace get nesting indent e E f F g GdoubleDouble precision floating point number l Line number where logging macro appears M Text form of the message severity level m Message corresponding to errno value as done by strerror for example N File name where logging macro appears n Program name given to ACE Log Msg open ointOctal number P Current process ID pACE TCHAR Specified character string followed by the 4 CodeArgument TypeDisplays appropriate errno message that is as done by perror QACE UINT64Decimal number rvoid Nothing calls the specified function RintDecimal number SintSignal name of the numbered signal sACE TCHAR Character string narrow or wide according to ACE TCHAR type T Current time as hour minute sec usec D Timestamp as month day year hour minute sec usec t Calling thread s ID 1 if single threaded uintUnsigned decimal number wwchar tSingle wide character Wwchar t Wide character string x XintHexadecimal number void Pointer value in hexadecimal N ASingle percent sign 1 4 例 1 日志的简单示例 include ace Log Msg h void foo void int ACE TMAIN int ACE TCHAR ACE TRACE ACE TEXT main ACE DEBUG LM INFO ACE TEXT IHi Mom n foo 日志系统之 ACE 日志服务 5 ACE DEBUG LM INFO ACE TEXT IGoodnight n return 0 void foo void ACE TRACE ACE TEXT foo ACE DEBUG LM INFO ACE TEXT IHowdy Pardner n 输出结果 输出结果 1024 calling main in file Simple1 cpp on line 7 Hi Mom 1024 calling foo in file Simple1 cpp on line 18 Howdy Pardner 1024 leaving foo Goodnight 1024 leaving main 2 日志的输出过滤 2 1 输出过滤原理 在 ACE 日志系统中主要是通过 ACE Log Msg 类实现日志消息的格式化功能 ACE 为主线程以及每个创建的线程维护一个线程专有的 ACE Log Msg 单例 宏 ACE LOG MSG 的作用就是为获得该 ACE Log Msg 单例 所有的 ACE 日志输出宏 都使用宏 ACE LOG MSG 所有很少会直接使用 ACE Log Msg 单例 ACE 日志系统通过使用掩码的方式进行输出过滤 具体来说具有进程一级的掩码 和线程一级的掩码控制 这里所说的线程概念在 ACE 中被误用了 线程一级和 ACE Log Msg 实例一级的掩码等同 ACE 在假定一个线程只有一个 ACE Log Msg 实 例才混用了线程的概念 2 2 编译时刻设定 编译时刻可以通过条件编译的方式来设定输出过滤 例如 6 在 include 之前定义一些宏 可以在编译时刻 Enable Disable logging Macros disable ACE DEBUG and ACE ERROR define ACE NLOGGING enable ACE DEBUG and ACE ERROR 缺省 undef ACE NLOGGING enable ACE ASSERT 缺省 undef ACE NDEBUG disable ACE ASSERT define ACE NDEBUG enable ACE TRACE define ACE NTRACE 0 disable ACE TRACE 缺省 define ACE NTRACE 1 MacroFunctionDisabled by ACE ASSERT test Much like the assert library call If the test fails an assertion message including the file name and line number along with the test itself will be printed and the application aborted ACE NDEBUG ACE HEX DUMP level buffer size text Dumps the buffer as a string of hex digits If provided the optional text parameter will be printed prior to the hex string The op status a is set to 0 ACE NLOGGIN G ACE RETURN value No message is printed the calling function returns with value op status is set to value ACE NLOGGIN G ACE ERROR RETURN level string value Logs the string at the requested level The calling function then returns with value ACE NLOGGIN G 日志系统之 ACE 日志服务 7 MacroFunctionDisabled by op status is set to value ACE ERROR level string Sets the op status to 1 and logs the string at the requested level ACE NLOGGIN G ACE DEBUG level string Sets the op status to 0 and logs the string at the requested level ACE NLOGGIN G ACE ERROR INIT value flags Sets the op status to value and the logger s option flags to flags Valid flags values are defined in Table 3 5 ACE NLOGGIN G ACE ERROR BREAK level string Invokes ACE ERROR followed by a break Use this to display an error message and exit a while or for loop for instance ACE NLOGGIN G ACE TRACE string Displays the file name line number and string where ACE TRACE appears Displays Leaving string when the ACE TRACE enclosing scope exits ACE 2 3 运行时刻设定 运行时候可以有两种方式可以设置输出过滤 一种是通过 priority mask 方法进行 设置和获取掩码 priority mask 方法的定义为 Get the current ACE Log Priority mask u long priority mask MASK TYPE THREAD 8 Set the ACE Log Priority mask returns original mask u long priority mask u long MASK TYPE THREAD 例如典型的使用 ACE LOG MSG priority mask 0 ACE Log Msg PROCESS ACE LOG MSG priority mask LM DEBUG LM NOTICE ACE Log Msg THREAD 另外一种方法是使用 disable debug messages 和 enable debug messages 方法进行 掩码设置 它们主要是利用 ACE Log Msg 单例的默认掩码 在使用 ACE Thread Manager 类创建线程时候可以利用该默认掩码进行统一设置 简化操作 方法定义为 static void disable debug messages ACE Log Priority priority LM DEBUG static void enable debug messages ACE Log Priority priority LM DEBUG 例如典型的使用 ACE LOG MSG priority mask 0 ACE Log Msg PROCESS ACE Log Msg enable debug messages ACE Thread Manager instance spawn service ACE Log Msg disable debug messages ACE Thread Manager instance spawn n 3 worker 3 日志的输出重定向 ACE 日志默认的输出为标准错误 可以他通过重定向将日志输出到输出流例如文 件 也可以重定向到系统 logger 例如 Unix 的 syslog 和 NT 的 Event Log 3 1 输出重定向的涉及函数 设置或改变 ACE 日志输出目标 logging sink 可以通过 ACE Log Msg 的方法 open 来完成 另外可通过 set flags 和 clr flags 来配合实现输出到多个目标 open 方法的定义为 Initialize the ACE logging facility Supplies the program name 日志系统之 ACE 日志服务 9 that is available to each logging message call Default arguments set up logging to STDERR only param prog name The name of the calling program param options flags A bitwise or of options flags used to set the initial behavior and logging sink s see the enum above for the valid values param logger key The name of ACE FIFO rendezvous point where the local client logger daemon is listening for logging messages Only meaningful if the LOGGER bit is set in the a flags argument int open const ACE TCHAR prog name u long options flags ACE Log Msg STDERR const ACE TCHAR logger key 0 第一个参数 prog name 表示程序名称 可以任意设置 可通过 ACE Log Msg 的 program name 方法获取 另外当第二个参数设置中有 ACE Log Msg VERBOSE 时 会在输出信息前加上前缀 前缀中就包含该 program name 第二个参数可以是 参数值参数说明 STDERR Write messages to STDERR LOGGER Write messages to the local client logger daemon OSTREAMWrite messages to the assigned output stream MSG CALLBACKWrite messages to the callback object VERBOSE Prepends program name timestamp host name process ID and message priority to each message VERBOSE LITE Prepends timestamp and message priority to each message SILENT Do not print messages at all SYSLOGWrite messages to the system s event log CUSTOM Write messages to the user provided back end 第三个参数 logger key 是针对第二个参数为 LOGGER C S 结构 时需要设置的 表示客户端程序端口值 比如 ACE DEFAULT LOGGER KEY 10 一旦调用了该方法 其后的输出将重新定位到第二个参数所指定的 sink 上 set flags clr flags 的定义为 Enable the bits in the logger s options flags void set flags unsigned long f Disable the bits in the logger s options flags void clr flags unsigned long f 参数含义同 open 函数的第二个参数 options flags 其中 set flags 调用可在现有输 出目标基础上增加新的输出目标 叠加 clr flags 则从中删除指定的输出目标 3 2 例 2 输出重定向的综合示例 include ace Log Msg h include ace streams h int ACE TMAIN int ACE TCHAR argv Output to default destination stderr ACE LOG MSG open argv 0 ACE TRACE ACE TEXT main ACE OSTREAM TYPE output new std ofstream ostream output test ACE DEBUG LM DEBUG ACE TEXT IThis will go to STDERR n ACE LOG MSG open argv 0 ACE Log Msg SYSLOG ACE TEXT syslogTest ACE LOG MSG set flags ACE Log Msg STDERR ACE DEBUG LM DEBUG ACE TEXT IThis goes to STDERR ACE LOG MSG msg ostream output 0 ACE LOG MSG set flags ACE Log Msg OSTREAM ACE DEBUG LM DEBUG ACE TEXT IThis will go to STDERR 日志系统之 ACE 日志服务 11 ACE TEXT syslog ACE LOG MSG clr flags ACE Log Msg OSTREAM delete output return 0 4 使用 Logging Strategy 进行运行时配置 ACE 通过 ACE Logging Strategy 类实现运行时配置 涉及到 ACE Service Configurator 机制 通过该机制在配置文件中创建和配置一个 ACE Logging Strategy 实 例 一个配置文件示例为 dynamic Logger Service Object ACE make ACE Logging Strategy s log out f STDERR OSTREAM p INFO 4 1 配置选项 Option Arguments and Meaning fSpecify ACE Log Msg flags OSTREAM STDERR LOGGER VERBOSE SILENT VERBOSE LITE used to control logging iThe interval in seconds at which the log file size is sampled default is 0 do not sample by default kSpecify the rendezvous point for the client logger mThe maximum log file size in Kbytes nSet the program name for the n format specifier