7.10 The log Module

The log utility module redefines a single variable:

bro_log_file : file

A special Bro variable used internally to specify a file where Bro should record messages logged by log statements (as well as generating real-time alerts via syslog).

Default: if the $BRO_LOG_SUFFIX environment variable is defined, then log.<$BRO_LOG_SUFFIX>, otherwise bro.log.

Note: This value is slightly different than that returned by open_log_file, because the latter would return log if $BRO_LOG_SUFFIX wasn't defined, and that name seems too easy to confuse with other uses.

See bro_log_file for further discussion.

If you do not include this module, then Bro records log messages to stderr. Here is a sample definition of log_hook:

     global msg_count: table[string] of count &default = 0;
     
     event log_summary(msg: string)
         {
         log fmt("(%s) %d times", msg, msg_count[msg]);
         }
     
     function log_hook(msg: string): bool
         {
         if ( ++msg_count[msg] == 1 )
             # First time we've seen this message - log it.
             return T;
     
         if ( msg_count[msg] == 5 )
             # We've seen it five times, enough to be worth
             # summarizing.  Do so five minutes from now,
             # for whatever total we've seen by then.
             schedule +5 min { log_summary(msg) };
     
         return F;
         }
     

You can also control Bro's log processing by defining the special function log-hook. It takes a single argument, msg: string, the message in a just-executed log statement, and returns a boolean value: true if Bro should indeed log the message, false if not. The above example shows a definition of log_hook that checks each log message to see whether the same text has been logged before. It only logs the first instance of a message. If a message appears at least five times, then it schedules a future log_summary event for 5 minutes in the future; the purpose of this event is to summarize the total number of times the message has appeared at that point in time.