How To Use sxe log Logging

This page describes the features of the sxe-log logging package. It can be used as a reference, but describes the features in order of how often a programmer will likely use them, and so can also be used as a tutorial.

How To Log

The simplest functions in sxe-log allow you to log a single line. For example:

SXEL2("Hello, world");

This logs the message 'Hello, world' at log level 2 (ERROR). The message can be a printf-like format followed by additional arguments. There are 7 possible log levels:

Level #	Level Symbol	Equivalent Syslog Level	Use
1	FATAL	Critical	Used for abort messages to indicate a fatal error
2	ERROR	Error	Used to indicate an external error
3	WARN	Warning	Used to warn about unexpected or unusual behavior
4	INFO	Notice	Used to note high level behavior
5	DEBUG	Informational	Used to give more information
6	TRACE	NO EQUIVALENT	Used for entry and exit messages to allow execution to be traced
7	DUMP	Debug	Used to dump packets and provide extra information for debugging the code

Levels 6 and 7 are only compiled into your code if you specify -DSXE_DEBUG=1 when building. This will be the case if you're using the mak build and run

make debug

If you want to trace the execution of your code, you use matched pairs of entry and return log functions:

{
    SXEE6("(arg1=%d,arg2='%s')", arg1, arg2);
    // The body of the function
OUT:
    SXER6("return %s", retval);
    return retval;
}

Beginning the format string of the entry function with '(' causes sxe-log to insert the function name before the '(' in the log line. Every line logged between the entry and the return function will be indented by 2 additional columns, making the log much easier to read. Note that there can only be one return log function, so any internal return points in the function must use a goto to a label like OUT. Mismatching entry and return macros will lead to a compiler error. Entry and exit functions are only available for levels 5, 6, and 7.

To abort a program with a log message, use the **SXEA1 **or **SXEA6 **function. SXEA1 will abort if you built without -DSXE_DEBUG=1, but SXEA6 will only abort a debug build.

To dump a packet (or any structure) in hexadecimal/ASCII, use the dump function. For example:

SXED6("Hello, world!\nGoodbye.\n", 23);

This will produce log output like:

48 65 6C 6C 6F 2C 20 77 6F 72 64 21 0A 47 6F 6F Hello, world!.Goo
64 62 79 65 2E 0A                               dbye..

There are a few other logging functions. The SXEV6 verify function will assert on failure, but in a non-debug build, the function being tested will still be executed. The SXEL#A6 functions allow logging in a non-debug build on a condition, but asserting in a debug build. The SXE_X_#I functions allow an additional identifier parameter to be passed and displayed in the identifier column of the log.

Other Functions

You can set the global log level with sxe_log_set_level. Whichever level you set, higher numbered levels will not be displayed. This allows you to run in production with only critical messages and errors logged by default (by passing SXE_LOG_LEVEL_ERROR), but override the level when trying to debug a problem. sxe_log_decrease_level is like set_log_set_level, but won't ever increase the level. sxe_log_get_level gets you the current setting.

You can set the per thread transaction identifier with sxe_log_set_thread_id, or clear it by passing SXE_LOG_NO_ID.

There are a few options that can be set with sxe_log_set_options. Multiple options can be passed by combining them with a bitwise or ('|'). The following options are supported:

Option	Description
SXE_LOG_OPTION_LEVEL_TEXT	Log levels are three letters instead of numbers
SXE_LOG_OPTION_ID_HEX	The transaction identifier is in hexadecimal instead of decimal

By default, log lines are sent to stderr. You can hook your own function in to receive them with sxe_log_hook_line_out by passing it a function that takes the SXE_LOG_LEVEL and a string pointer (to the line). sxe_log_use_syslog will divert all log messages to the syslog.

sxe_log_hook_buffer_prefix allows you to hook in your own function to override the default function that formats the beginning of each log line. sxe_log_control_forget_all_levels lets you signal that some of the environmental log level settings have been changed and that all log levels should be rechecked.