ACE日志使用指南.doc

ACE 日志使用指南 1 ACE 日志使用指南日志使用指南 2 目 录 1 ACE 日志概述日志概述 5 2 基本使用基本使用 5 2 1 日志输出宏 5 2 2 日志的等级 5 2 3 格式化指令 6 2 4 例 1 日志的简单示例 8 3 日志的输出过滤日志的输出过滤 9 3 1 输出过滤原理 9 3 2 编译时刻设定 9 3 3 运行时刻设定 11 3 4 例 2 运行时刻的日志过滤示例 12 4 日志的输出重定向日志的输出重定向 13 4 1 重定向涉及函数 13 4 2 重定向到标准错误 14 4 3 重定向到输出流 15 4 4 例 3 输出重定向综合示例 15 5 回调机制回调机制 16 5 1 使用步骤 16 5 2 例 4 回调机制示例 17 6 使用使用 LOGGING STRATEGY 进行运行时配置进行运行时配置 18 6 1 ACE LOGGING STRATEGY支持的参数 18 6 2 例 5 运行配置示例 19 7 C S 方式的日志方式的日志 20 7 1 代理方式 20 7 1 1 例6 代理方式的C S日志示例 20 7 2 直连方式 22 7 2 1 例7 直连方式的C S日志示例 22 7 定制定制 ACE 日志日志 25 ACE 日志使用指南 3 7 1 定制日志输出宏 25 7 1 1 定制涉及函数 25 7 1 2 例8 日志输出宏的定制示例 26 7 2 封装 ACE 日志 30 7 2 1 例9 ACE日志封装示例 30 4 1 ACE 日志概述 ACE 日志服务是 ACE 库的一个功能模块 具有线程安全 灵活 分级显示等特点 可以面向程序调试 运行 测试 和维护等全生命周期 可以选择将信息输出到屏幕 文件 系统日志 如 Windows 下的 Event log 甚至是远程服务器 除此之外 ACE 日志系统支持回调函数以及运行时刻动态配置 Runtime Configuration 2 基本使用 2 1 日志输出宏 ACE 日志的使用主要通过宏 ACE XXX severity formatting args 进行日志输出 其中 severity 为日志等级 参见 2 2 小节 formatting args 是要输出的内容 类似 printf 函数的可变参数 其中也可以包含以 开头的格式化指令 见 2 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 2 2 日志的等级 ACE 日志的的等级如表 2 1 所示 表 2 1 ACE 日志的等级 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 ACE 日志使用指南 5 special handling LM WARNINGWarning messages 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 2 3 格式化指令 ACE 日志支持的格式化指令如表 2 2 所示 表 2 2 ACE 日志支持的格式化指令 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 6 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 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 ACE 日志使用指南 7 N ASingle percent sign 2 4 例 1 日志的简单示例 ACE 日志简单示例如以下代码所示 define ACE NTRACE 0 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 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 注意头文件 ace Log Msg h 的包含 以及使用 2 1 小节介绍的日志输出宏进行的 日志输出 日志输出宏内层括号包括日志等级和日志内容两个参数 由于等级为 LM TRACE 的日志消息默认是被过滤的 因此本例中定义了宏 define ACE NTRACE 0 利用条件编译使其能够输出 具体参见 3 2 2 小节 输出结果 输出结果 5396 calling main in file D workspace c ACE 日志服务 SimpleExample main cpp on line 8 Hi Mom 5396 calling foo in file D workspace c ACE 日志服务 SimpleExample main cpp 8 on line 18 Howdy Pardner 5396 leaving foo Goodnight 5396 leaving main 3 日志的输出过滤 3 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 实例才混用了线程的概念 ACE Log Msg 在检测日志的等级时 将同时检测进程一级和实例一级的掩码 如果这两个级别中的任何一个允许输出该等级的日志 则该日志得以输出 默认情况 下 进程一级允许所有等级的日志输出 实例一级则不允许任何等级的日志输出 因 此默认是允许所有等级的日志输出 3 2 编译时刻设定 编译时刻可以通过条件编译的方式来设定输出过滤 通过在 include 之前定义一些宏实现在编译时刻 Enable Disable 日志输出宏 例如 define ACE NLOGGING disable ACE DEBUG and ACE ERROR undef ACE NLOGGING enable ACE DEBUG and ACE ERROR 缺省 undef ACE NDEBUG enable ACE ASSERT 缺省 define ACE NDEBUG disable ACE ASSERT define ACE NTRACE 0 enable ACE TRACE define ACE NTRACE 1 disable ACE TRACE 缺省 所有有效的宏如表 3 1 中的第 3 列所示 表 3 1 ACE 日志输出宏的条件编译选项 ACE 日志使用指南 9 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 NLOGGING ACE RETURN value No message is printed the calling function returns with value op status is set to value ACE NLOGGING ACE ERROR RETURN level string value Logs the string at the requested level The calling function then returns with value op status is set to value ACE NLOGGING ACE ERROR level string Sets the op status to 1 and logs the string at the requested level ACE NLOGGING ACE DEBUG level string Sets the op status to 0 and logs the string at the requested level ACE NLOGGING 10 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 NLOGGING 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 NLOGGING 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 NTRACE 3 3 运行时刻设定 运行时候有两种方式进行输出过滤 一种是通过 priority mask 方法进行掩码的设 置 priority mask 方法的定义为 u long priority mask MASK TYPE THREAD u long priority mask u long MASK TYPE THREAD 拥有一个参数的 priority mask 方法用来获取当前设置的掩码 参数可以指定掩码 类型是进程一级还是线程一级 拥有两个参数的 priority mask 方法则用来设置掩码 典型的使用 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 日志使用指南 11 掩码设置 该方法主要利用了 ACE Log Msg 单例的默认掩码 在使用 ACE Thread Manager 类创建线程时候可以利用该默认掩码进行统一设置 ACEL Log Msg 在实例化时将用到默认的掩码进行实例一级的掩码设置 该默认 的掩码被初始化为 0 即允许所有等级日志输出 由于 ACE 为主线程以及每个创建的线 程维护一个线程专有的 ACE Log Msg 单例 线程一级的掩码和实例一级的掩码概念 等同 因此可以在创建线程前利用默认的掩码统一初始化所创建的 ACEL Log Msg 实 例 disable debug messages 和 enable debug messages 的方法定义为 static void disable debug messages ACE Log Priority priority LM DEBUG static void enable debug messages ACE Log Priority priority LM DEBUG 方法 disable debug messages 为相应的日志等级设置掩码 方法 enable debug messages 则取消设置 典型的使用 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 4 例 2 运行时刻的日志过滤示例 ACE 运行时刻的日志过滤如以下代码所示 include ace Log Msg h void foo void int ACE TMAIN int ACE TCHAR ACE TRACE ACE TEXT main ACE LOG MSG priority mask LM DEBUG LM NOTICE ACE Log Msg PROCESS ACE DEBUG LM INFO ACE TEXT IHi Mom n foo ACE DEBUG LM DEBUG ACE TEXT IGoodnight n return 0 12 void foo void ACE TRACE ACE TEXT foo ACE DEBUG LM NOTICE ACE TEXT IHowdy Pardner n 由于设定了进程一级的 LM DEBUG 和 LM NOTICE 掩码 因此 LM DEBUG 和 LM NOTICE 等级的日志将被输出 其他等级的日志则被过滤 输出结果 输出结果 Howdy Pardner Goodnight 4 日志的输出重定向 ACE 日志默认的输出为标准错误 可以通过重定向将日志输出到输出流 output stream 例如文件 也可以重定向到系统 logger 例如 Unix 的 syslog 和 NT 的 Event Log 4 1 重定向涉及函数 可以通过 ACE Log Msg 的方法 open 设置或改变 ACE 日志输出目标 logging sink 另外可通过 set flags 和 clr flags 来配合实现输出到多个目标 open 方法的定义为 Initialize the ACE logging facility Supplies the program name 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 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 ACE 日志使用指南 13 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 第二个参数如表 4 1 所示 表 4 1 open 方法的第二个参数的允许取值 参数值参数说明 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 一旦调用了该方法 其后的输出将重新定位到第二个参数所指定的 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 则从中删除指定的输出目标 14 4 2 重定向到标准错误 ACE 默认将日志输出到标准错误 但某些时候也需要显示指定 例如当输出重定 向到包括标准错误的多个目标时 输出重定向到标准错误可以使用 open 方法 另外 也可以使用 set flags 方法 以下是使用 open 方法输出重定向到标准错误的示例代码 int ACE TMAIN int ACE TCHAR argv ACE LOG MSG open argv 0 ACE Log Msg STDERR 以下是使用 set flags 方法输出重定向到标准错误的示例代码 int ACE TMAIN int ACE TCHAR argv ACE LOG MSG set flags ACE Log Msg STDERR 注意如果需要改变输出到其他目标则可以通过调用 clr flags 方法实现 另外 如 果需要在重定之前将其他输出目标关闭也可以使用 clr flags 方法 4 3 重定向到输出流 由于 C 的流机制提供了比 C 语言 printf 族函数功能更强大的函数库 代码的可 读性也更强 因此 ACE Log Msg 提供了方法 msg ostream 以支持 C 输出流 output stream 将日志输出到输出流中 以下是重定向到输出流的示例代码 ACE OSTREAM TYPE output new std ofstream ostream output test ACE LOG MSG msg ostream output 1 ACE LOG MSG set flags ACE Log Msg OSTREAM ACE LOG MSG clr flags ACE Log Msg STDERR 4 4 例 3 输出重定向综合示例 以下是输出重定向到标准错误 文件流和系统 Logger 的示例代码 include ace Log Msg h include ace streams h ACE 日志使用指南 15 int ACE TMAIN int ACE TCHAR argv 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 TEXT syslog ACE LOG MSG clr flags ACE Log Msg OSTREAM delete output return 0 输出结果 输出结果 This will go to STDERR This goes to STDERR 2 创建类型为该派生类的回调对象 3 使用 ACE Log Msg 的 msg callback 方法将该回调对象注册 4 调用 ACE Log Msg 的 set flags 方法设置标记位 MSG CALLBACK 使得日志能 够输出到回调对象 使用 ACE 日志的回调机制时需要注意以下问题 第 3 4 步的操作仅作用于当前的 ACE Log Msg 实例 对于其他线程中的 ACE Log Msg 实例并不起作用 回调对象并不从 ACE Log Msg 派生 如果需要将其使用到多线程环境 需要注 意 为每一个线程提供适当的回调对象 如果 ACE Log Msg 实例还在使用已注册的回调对象 则不应该将该对象删除 5 2 例 4 回调机制示例 以下是从 ACE Log Msg Callback 派生子类 Callback 的示例代码 include ace streams h include ace Log Msg h include ace Log Msg Callback h include ace Log Record h class Callback public ACE Log Msg Callback public void log ACE Log Record log record print ACE TEXT ACE Log Msg VERBOSE cerr 以下是使用创建和注册 Callback 对象以及将日志输出重定向到标准错误的示例代 码 ACE 日志使用指南 17 include ace Log Msg h include Callback h int ACE TMAIN int ACE TCHAR Callback callback new Callback ACE LOG MSG set flags ACE Log Msg MSG CALLBACK ACE LOG MSG clr flags ACE Log Msg STDERR ACE LOG MSG msg callback callback ACE TRACE ACE TEXT main ACE DEBUG LM DEBUG ACE TEXT IHi Mom n ACE DEBUG LM INFO ACE TEXT IGoodnight n return 0 输出结果 输出结果 Hi Mom Sep 24 17 15 42 494 2007 4916 LM DEBUG Hi Mom Goodnight Sep 24 17 15 42 494 2007 4916 LM INFO Goodnight 6 使用 Logging Strategy 进行运行时配置 ACE 日志可以通过 ACE Logging Strategy 类实现运行时配置 主要涉及到 ACE 的服务配置器 Service Configurator 通过服务配置器 可以在配置文件中配置 ACE Logging Strategy 实例的创建并传递相应的参数 关于 ACE 的服务配置器请参考 其他资料 以下为一个配置文件的示例内容 其中的配置参数请参考 6 1 小节 dynamic Logger Service Object ACE make ACE Logging Strategy s log out f STDERR OSTREAM p INFO 18 6 1 ACE Logging Strategy 支持的参数 ACE Logging Strategy 支持参数如表 6 1 所示 表 6 1 ACE Logging Strategy 支持的参数 OptionArguments 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 NThe maximum number of log files to create oRequest the standard log file ordering keeps multiple log files in numbered order Default is not to order log files pPass in the processwide priorities to either enable DEBUG INFO WARNING NOTICE ERROR CRITICAL ALERT EMERGENCY or to disable DEBUG INFO WARNING NOTICE ERROR CRITICAL ALERT EMERGENCY sSpecify the file name used when OSTREAM is specified as an output target tPass in the per instance priorities to either enable DEBUG INFO WARNING NOTICE ERROR CRITICAL ALERT EMERGENCY or to disable DEBUG INFO WARNING NOTICE ERROR CRITICAL ALERT EMERGENCY 6 2 例 5 运行配置示例 以下是使用 ACE 的 Logging Strategy 进行运行时配置的示例代码 include ace Log Msg h include ace Service Config h int ACE TMAIN int argc ACE TCHAR argv if ACE Service Config open argc argv ACE 日志使用指南 19 ACE DEFAULT LOGGER KEY 1 0 1 open argv 0 ACE Log Msg LOGGER ACE DEFAULT LOGGER KEY ACE TRACE ACE TEXT main ACE 日志使用指南 21 ACE DEBUG LM DEBUG ACE TEXT IHi Mom n ACE DEBUG LM INFO ACE TEXT IGoodnight n return 0 注意使用 C S 方式的日志时必须使用 open 方法而不能用 set flags open 方法 的第三个参数是客户端监听的 logger key 它被设定为默认值 ACE DEFAULT LOGGER KEY 该值应该与客户端代理监听保持一致 如果客户端 的配置文件中使用了 k 参数指定了另外值 则 open 方法的第三个参数也必须相应改 变 保持一致 输出结果输出结果 Sep 25 11 12 13 078 2007 3568 LM DEBUG Logging Service starting up Logging Server at port 20009 on handle 1220 Sep 25 11 14 54 721 2007 localhost 1332 LM DEBUG Hi Mom Sep 25 11 14 54 721 2007 localhost 1332 LM INFO Goodnight 7 2 直连方式 使用直连方式的 C S 日志时 日志请求直接发送到服务器 需要在理解日志逻辑 和连接基础上进行编程 另外服务器由于数据量带来的压力增加 直连方式主要利用 回调机制获取封装了日志消息的 ACE Log Record 实例 然后将其直接发送到服务器 ACE Log Record 的主要成员变量如表 7 1 所示 表 7 1 ACE Log Record 的主要成员变量 AttributeDescription typeSeverity Level prioritySynonym for type priority nameThe log record s priority name lengthThe length of the log record set by the creator of the log record time stampThe timestamp generally creation time of the log record set by the creator of the log record pidID of the process that created the log record instance 22 msg dataThe textual message of the log record msg data lenLength of the msg data attribute 7 2 1 例 7 直连方式的 C S 日志示例 以下是回调对象对应类 Callback 的代码示例 include ace streams h include ace Log Msg h include ace Log Msg Callback h include ace Log Record h include ace SOCK Stream h include ace SOCK Connector h include ace INET Addr h define LOGGER PORT 20009 class Callback public ACE Log Msg Callback public Callback this logger new ACE SOCK Stream ACE SOCK Connector connector ACE INET Addr addr LOGGER PORT ACE DEFAULT SERVER HOST if connector connect this logger addr 1 delete this logger this logger 0 virtual Callback if this logger ACE 日志使用指南 23 this logger close delete this logger void log ACE Log Record return size t len log record length log record encode if this logger send n char this logger 0 private ACE SOCK Stream logger 在 Callback 的构造函数中建立了和服务器的直接连接 由于 ACE Log Record 的一 些成员是数字 在 log 方法中发送日志消息到服务器之前需要调用 encode 保证正确 的字节顺序 以下是客户端的示例代码 include ace Log Msg h include Callback h 24 int ACE TMAIN int ACE TCHAR Callback callback new Callback ACE LOG MSG set flags ACE Log Msg MSG CALLBACK ACE LOG MSG clr flags ACE Log Msg STDERR ACE LOG MSG msg callback callback ACE TRACE ACE TEXT main ACE DEBUG LM DEBUG ACE TEXT IHi Mom n ACE DEBUG LM INFO ACE TEXT IGoodnight n return 0 输出结果 输出结果 Sep 25 15 16 51 078 2007 3568 LM DEBUG Logging Service starting up Logging Server at port 20009 on handle 1220 Sep 25 15 16 51 54 721 2007 localhost 1332 LM DEBUG Hi Mom Sep 25 15 16 51 54 721 2007 localhost 1332 LM INFO Goodnight 7 定制 ACE 日志 7 1 定制日志输出宏 7 1 1 定制涉及函数 表 7 1 定制输出宏涉及的 Log Msg Msg 成员方法 MethodPurpose op statusThe return value of the current function By convention 1 indicates an error condition errnumThe current errno value linenumThe line number on which the message was generated fileFile name in which the message was generated msgA message to be sent to the log output target ACE 日志使用指南 25 incIncrements nesting depth Returns the previous value decDecrements the nesting depth Returns the new value trace depthThe current nesting depth start tracing stop tracing tracing enabled Enable disable query the tracing status for the current ACE Log Msg instance The tracing status of a thread s ACE LOG MSG singleton determines whether an ACE Trace object generates log messages priority maskGet set the set of severity levels at instance or process level for which messages will be logged log priority enabledReturn non zero if the requested priority is enabled setSets the line number file name op status and several other characteristics all at once conditional setSets the line number file name op status and errnum values for the next log message however they take effect only if the next logging message s severity level is enabled 7 1 2 例 8 日志输出宏的定制示例 本例将定制 ACE 日志输出宏 使得输出跟踪消息时 得以输出定制的前缀 函数 名 适当的缩进 文件名以及行号 输出其他等级消息得以输出定制的前缀以及适当 的缩进 以下是新定义的日志输出宏的示例代码 定制