Initialization

As with all Python classes, you may choose to pass arguments to your constructor when creating an instance of your event handler. This is done via the standard method called __init__ in Python. In order to make the TelnetHost event handler generic, parameters such as host, port, username, password, and the command to execute should be passed at creation time:

class TelnetHostEventHandler(EventHandler):
    def __init__(self, host, port=23, user, password, command):
        self.host = host
        self.port = port
        self.user = user
        self.password = password
        self.command = command

By storing these values, the event handler can use them later when processing an event (the result of a matched line in a log). The above is sufficient if one is only ever going to use the LogWrap API directly. However, this tutorial is using the logwrap script and XML configuration file. In this mode of operation, the user does not invoke this constructor and thus cannot pass values to it.

It turns out that the LogWrap framework has a little bit of magic baked in to facilitate the passing of values to an event handler's constructor when using the XML configuration file. Users can specify values by setting XML attributes to the <handler> element in the configuration file. Each attribute's name must be the same as the name of the argument in the constructor. For example:

<handler type="CustomEventHandlers:TelnetHost"
         host="\1"
         user="kaz"
         password="blahblah"
         command="df"/>

The above XML sets four attributes (not counting the type attribute which you must set to specify the event handler). Each of the attribute names corresponds to the argument names in the constructor. Note: if an value is not passed (such as the port), it must have a default value set in the constructor (23 in this case). Sometimes passing values via XML attributes is not sufficient because you have multiline data to pass or characters that cannot appear in an XML attribute's value. In this case, an alternative syntax is provided:

<handler type="CustomEventHandlers:TelnetHost">
  <host>\1</host>
  <user>kaz</user>
  <password>blahblah</password>
  <command>df</command>
</handler>

Instead of passing the values as attributes, you can pass the values as the text of a child element whose name corresponds to the arguments in the constructor. When using this notation, you can also use CDATA blocks if desired.

Now that you've seen the magic that the LogWrap framework provides, there is one caveat the programmer must remember: If arguments are passed to an event handler's constructor via the XML configuration file, they are passed as strings. As such, you must handle the conversion of these strings to other data types as appropriate. In our simple event handler, none of the values passed are non-string objects, however, if we were to pass a port number via an XML attribute, it would be passed as a string. Thus, we should handle the conversion of this string to an integer in our constructor:

class TelnetHostEventHandler(EventHandler):
    def __init__(self, host, port=23, user, password, command):
        self.host = host
        self.port = int(port) # Convert to integer if not already
        self.user = user
        self.password = password
        self.command = command

You've now seen how an event handler is instantiated via the XML configuration file. The next section provides the details on the execution of the event handler.

Execution

A little background on the LogWrap event framework is first needed before proceeding with the implementation of the custom event handler. Included in the distribution of the LogWrap framework is a separate event framework. The event framework consists of two threads interconnected by an event queue. The first thread is responsible for the generation of events and the placement of these events into the event queue. The second thread is responsible for the dequeuing and processing of events. It is the latter thread that invokes all of the event handlers. See the following diagram:

                        |
                        |
                 +-------------+
Generator -----> | Event Queue | -----> Processor
                 +-------------+
                        |
              Thread 1  |  Thread 2

The fact that event processing occurs in a separate thread is important because your custom event handler does not have to be "spawned" off in another process or thread to avoid losing events. Event generation and queuing are not affected if your event handler takes a few seconds to execute because the event queue acts as a buffer. This simplifies the coding of event handlers.

On a side note, if your event handler is very slow, and you have an excessive amount of events being generated for a constant time, your queue will grow and grow and grow. At that point, you need to investigate the use of the frequency suppression event handlers included with the LogWrap framework. However, with that said, the most common scenario is that the queue will fluctuate over time growing larger when bursts of events arrive and emptying when there is little event generation taking place.

All event handlers are invoked by the EventProcessor which passes the Event as the only argument to the process_event method of the event handler. The following is a simple event handler that does nothing other than print the Event object to the screen:

class SimpleEventHandler(EventHandler):
    def process_event(self, event):
        print "event =", event
        return 1

It is important to note that this event handler returns 1 which indicates that subsequent handlers should be invoked if this event handler was part of a event handler chain (as described earlier). If you want to stop the execution of the chain, return a value of 0 instead.

In the next section, we will explore the Event object and all of the data it can provide to us when we write our implementation of our event handler.

Event Data

An event handler would not be very useful unless it had access to context information related to the event in question. Specifically, the timestamp, the originator of the event, the original line that triggered the event in the log file, as well as any grouped data specified in the regular expression that was used to match the event. Fortunately, all of the above are available to the programmer via the Event object when writing an event handler. The following event handler illustrates how one can access this information:

class ExamineEventHandler(EventHandler):
    def process_event(self, event):
        print "------------------"
        print "Creation Time:    ", time.ctime(event.time)
        print "Originator's Name:", event.originator
        print "Original Line:    ", event.data.line,
        print "Match Object:     ", event.data.match.groups()
        return 1

A more verbose description of each of the above is provided below:

event.time

Contains the time when this event was created. The value is stored as a number of seconds since Epoch.

event.originator

Contains a reference to the originator of this event. In the event framework, this refers to an EventGenerator. Within the LogWrap context, this object refers to the LogEncapsulator (a subclass of an EventGenerator). The string representation of the LogEncapsulator is simply its name. This is the same name that was specified in the <logEncapsulator> element.

event.data

Contains a reference to a piece of arbitrary data that has been associated with this event. The EventGenerator specifies the contents of this variable. In this context, the LogEncapsulator stores a reference to a LogMatch object.

event.data.line

Contains the original line that generated the event. This value is stored as part of the LogMatch object.

event.data.match

Contains a MatchObject (from the Python re module) which can be queried for items that were grouped in the regular expression. This enables the event handler to gain access to parts of the original log message. In this tutorial, this will be used to access the IP address of the host.

TelnetHost Implementation

You are now armed with all of the necessary information to write the full implementation of the TelnetHost custom event handler. The contents of following script must be located in a file called /home/kaz/src/CustomEventHandlers.py (unless you have changed the value of the <handlerDirectory> element in the XML configuration file):

from com.kazmier.event.Event import EventHandler

class TelnetHostEventHandler(EventHandler):  # Must extend EventHandler

    # The construct defines the args we expect in the XML file,
    # you'll notice for each arg here, there is a corresponding XML
    # attribute defined in the config file.
    def __init__(self, host, port=23, user, password, command):
        self.host = host
        self.port = int(port) # Handle the conversion from string to int
        self.user = user
        self.password = password
        self.command = command

    # This is the method that is called when the event handler is
    # invoked.  It is passed a reference to the event itself which
    # lets us do some nifty things like get at those parts of the
    # regular expression that we grouped using the parens.
    def process_event(self, event):
        import telnetlib

        # And here is the magic that converts "\1" into the IP
        # address that was sent to the log file.  This simply uses
        # the MatchObject from the re library to do the expansion.
        telnet = telnetlib.Telnet(event.data.match.expand(self.host))

        # Login to the host
        telnet.read_until("login: ")
        telnet.write(self.user + "\n")
        telnet.read_until("Password: ")
        telnet.write(self.password + "\n")

        # Run the command that was specified in the XML configuration  
        telnet.write(self.command + "\n")
        telnet.write("exit\n")
        output = telnet.read_all()
        telnet.close()

        # We'll probably want to do something other than just
        # printing the output to the screen, but this will suffice
        # for this tutorial.
        print output

        # Its important to return 1 if you want to permit other
        # event handlers defined in the configuration to run.  If
        # you don't, you effectively stop the event handler chain.
        # This is how the frequency suppression handler works.
        return 1

You can test this example with the following commands:

$ touch /var/log/app.log   # Create the file if it doesn't exit
$ logwrap path_to_xml_configuration_file

Then, in another shell (or window):

$ echo "WARNING: Disk Space Low on 10.11.12.13" >> /var/log/app.log

At this point, in the first window, you should see the output of the df command for the host 10.11.12.13.

Congratulations! You've successfully written your own custom event handler. Custom event handlers are useful if you are seeking functionality that isn't provided by an event handler included in the LogWrap distribution.