Goal

This tutorial shows how a onePK application can register to receive syslog events from the network element it is connected to. As syslog messages enter the network element's logger, they are sent to the registered onePK application through a callback mechanism.

Tutorial Code

For this tutorial, you use the SyslogEventTutorial as a general guide for onePK syslog events.

The code used in this tutorial is available in the SyslogEventTutorial.py file located under <SDK Location>/python/tutorials/events.

Requirements/Prerequisites

  • These steps assume the application can connect properly to a network element. Please see the Connecting to a Network Element tutorial for information on how to make the initial connection.
  • For NX-OS platforms only: To configure the network element to run an Events tutorial, you must first enable the EVMED feature, which allows developers to use Embedded Event Manager (EEM) to monitor Application-, CLI-, and Interface Statistics-based events and then schedule actions on the occurrence of those events:
router(config)# feature evmed
router(config)# sh feature |i evmed
evmed           1               enabled

Network Configuration

If onePK is enabled on the network element, and a connection by the application is possible, no further configuration is needed to register for events. The events infrastructure for onePK is provided on the network element by the Embedded Event Manager (EEM) infrastructure. Various EEM commands can be run to show information such as registered events and an event history.

NE100#show event manager policy registered
NE100#show event manager history events

Steps In Detail

For every event, there is always a listener. The main purpose of a listener is to handle any incoming events from the network element. All listeners in the onePK API are Python Interfaces in which the application developer is responsible for writing concrete methods to handle the incoming onePK events. The following example shows a basic implementation of the SyslogListener. In this example, you handle the event by printing out the message that was received from the event.

Example Listener

class ExampleSyslogListener(SyslogListener):    
    name = str()
    
    """
      Creates an Example Syslog Event Listener.
      @param name
            Identifies the instance.
    """
    def __init__(self, name):        
        super(ExampleSyslogListener, self).__init__()
        self.name = name

    """
      Invoked when an event is received from a network element.
      @param event
                 An event object that indicates that an event has occurred in a network element.
      @param clientData
                 The clientData is an object that is passed in when the application calls an API to add/register
                 the event listener. The application is responsible for casting the input clientData to the
                 appropriate class before using it.
    """    
    def handle_event(self, event, clientData):
        print "---------------------------"
        print self.name + " has received SysLog Event\n"
        print "Message        = " + event.message
        print "Message Count  = " + str(event.msg_count)
        print "Priority       = " + onep.element.NetworkElement.OnepSyslogSeverity.enumval(event.priority)
        print "---------------------------\n"

Next, you register the listener that you have created to the onePK-enabled network element. In order to register first you need to create a SyslogFilter object to specify a particular Syslog message pattern. This SyslogFilter object with specified regular expression pattern is mandatory in order to register for syslog events. Optionally you could set the other parameters of the SyslogFilter such as its logging priority level, number of occurrences before the event is called and so on. Additionally the client_data (client context) can be passed in as the last parameter to the registration. This data is passed to the callback handler when the registered event triggers. Finally you receive back a handler in the form of a Python integer.

Register Listener

syslogListener = ExampleSyslogListener("Syslog Tutorial")
syslogFilter = SyslogFilter('Interface')
syslogFilter.periodMsec = 1000
syslogFilter.priority = onep.element.NetworkElement.OnepSyslogSeverity.ONEP_SYSLOG_NOTICE
clientData = None
network_element = tutorial.get_network_element()
#
# Add a syslog event listener
#
print 'Adding a Syslog event listener'
eventHandle = network_element.add_syslog_listener(syslogListener, syslogFilter, clientData)

You can then remove the listener by passing back the integer that you just received to the corresponding remove listener method. NOTE The listener is removed automatically once the onePK application terminates.

By using our same network_element object, we can register multiple listeners to the same network element. A full list of which listener types can be added to the network_element object, please view the onePK Network Element ePydoc documentation.

Result

Congratulations! By following this tutorial, you can now model an events listener on a network element.