In Tcl, commands can be queued for future processing by using the
after Tcl command. The most common use of this command is to correlate (gather and summarize) events over a fixed interval of time,
called the “correlation window.” Once the window of interest expires, the filter will need to “wake up,” and calculate or
summarize the events that occurred during the window, and often send out a new syslog message to report the events. This background
process is handled by the ESM Event Loop process, which allows the Tcl interpreter to execute queued commands after a certain
amount of time has passed.
If your syslog filter module needs to take advantage of correlation windows, it must use the
after Tcl command to call a summary procedure once the correlation window expires (see examples in the "Configuration Examples
for the Embedded Syslog Manager" section). Because there is no normal filter chain processing when background processes are
run, in order to produce output these filters must use one of two ESM Tcl extensions:
errmsg or
esm_errmsg .
During background processing, the commands that have been queued by the
after command are not run in the context of the filter chain (as in normal processing), but rather are autonomous procedures that
are executed in series by the Tcl interpreter. Thus, these background procedures should not operate on the normal Tcl global
namespace variables (except for setting the global namespace variables for the next filter when using
esm_errmsg ), but should operate on variables stored in their own namespace. If these variables are declared outside of a procedure definition,
they will be persistent from call to call.
The purpose of the
errmsg Tcl command is to create a new message and send it out for distribution, bypassing any other syslog filter modules. The syntax
of the
errmsg command is:
errmsg <severity> <stream> <message_string>
The purpose of the
esm_errmsg Tcl command is to create a new message, process it with any syslog filter modules below it in the filter chain, and then
send it out for distribution. The syntax of the
esm_errmsg command is:
esm_errmsg <module_position>
The key difference between the errmsg() Tcl function and the esm_errmsg() Tcl function is that
errmsg ignores the filters and directly queues a message for distribution, while
esm_errmsg will send a syslog message down the chain of filters.
In the following example, a new syslog message is created and sent out tagged as Alert severity 1 to the configured ESM logging
targets (stream 2). The purpose of this filter is to suppress the individual SYS-5-CONFIG messages over a thirty minute correlation
window, and send out a summary message at the end of the window.
errmsg 1 2 “*Jan 24 09:34:02.539: %SYS-1-CONFIG_I: There have been 12
configuration changes to the router between Jan 24 09:04:02.539 and Jan 24
09:34:01.324”
In order to use
esm_errmsg , because the remaining filters following this one will be called, this background process must populate the needed Tool Command
Language (Tcl) global namespace variables prior to calling
esm_errmsg . Passing the ::module_position tells the ESM framework which filter to start with. Thus, filters using the
esm_errmsg command should store their ::module_position (passed in the global namespace variables during normal processing) in their
own namespace variable for use in background processing. Here is an example:
proc ::my_filter_namespace::my_summary_procedure{}
{
set ::orig_msg “*Jan 24 09:34:02.539: %SYS-1-CONFIG_I: There have been 12
configuration changes to the router between Jan 24 09:04:02.539 and Jan 24
09:34:01.324”
set ::timestamp “*Jan 24 09:34:02.539”
set ::severity 1
set ::stream 2
set ::traceback “”
set ::pid “”
set ::process “”
set ::format_string “There have been %d configuration changes to the router
between %s and %s”
set ::msg_args {12 “Jan 24 09:04:01.539” “Jan 24 09:34:01.324”}
esm_errmsg $::my_filter_namespace::my_module_position
}
The benefit of setting all the global namespace variables for the
esm_errmsg command is that your filters will be modular, and the order they are used in the ESM framework will not matter. For example,
if you want all of the messages destined for the ESM targets to be suffixed with the message originator’s hostname, you could
write a one-line “hostname” filter and place it at the bottom of the filter chain:
return “$::orig_msg -- $::hostname”
In this example, if any of your filters generate new messages during background processing and they use
esm_errmsg instead of
errmsg , these messages will be clearly suffixed with the hostname.
Feedback