Using Snippets to Collect SNMP Data

Download this manual as a PDF file

Snippets can be used to implement a variety of collection methods, including those that are built into SL1, such as SNMP collection. Although it is more convenient to use the built-in collection methods where possible, there are use cases when using a Snippet Dynamic Application for SNMP collection is appropriate. For example, you could use a Snippet Dynamic Application when you need to dynamically assemble OIDs using the results of several previous polls to gather the correct indexes to use. To create these types of OIDs with multiple indices, you can use a snippet that performs the polling and includes custom logic for assembly of special OIDs.

This section walks through snippet code that performs general purpose SNMP collection, and can be used as a starting point for special-purpose SNMP collection.

To use this example snippet code in a Dynamic Application, the value in the Snippet Argument field for each collection object must be an SNMP OID, the same way OIDs are specified for an SNMP Dynamic Application.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all of the menu options, click the Advanced menu icon ().

Creating the Dynamic Application

To create this example Dynamic Application, perform the following steps:

  1. Go to the Dynamic Applications Manager page (System > Manage > Dynamic Applications).
  2. Select the Actions button, then Create New Dynamic Application. The Create New Application page is displayed.
  3. Supply values in the following fields:
    • Application Name. The name of the Dynamic Application. This example is called "Snippet SNMP Example".
    • Application Type. This example is a Snippet Performance Dynamic Application. Select Snippet Performance in this field.
    • Poll Frequency. To see data as quickly as possible, select Every 1 Minute in this field.
  4. This example does not have specific requirements for the other settings defined in this page. You can leave the remaining fields set to the default values.
  5. Select the Save button.

Creating a Container for the Snippet

Because collection objects are assigned a specific snippet, you must create the container for the snippet code before creating the collection objects for this Dynamic Application. To create a container for the snippet code, perform the following steps:

  1. Select the Snippets tab.
  2. Supply values in the following fields:
    • Snippet Name. The name of the snippet. The snippet in this example is called "SNMP Collection".
    • Active State. To ensure that the snippet code is run by SL1, select Enabled in this field.
    • Required. Specifies whether this snippet is required for successful collection of all other snippet requests. Select Required - Stop Collection. If this snippet request fails, the platform will not attempt to execute any other snippet requests in this Dynamic Application. Dynamic Applications that consume the cache of this Dynamic Application will halt collection.
    • Snippet Code. Leave this field blank. You will add the snippet code later.
  3. Select the Save button.

Creating the Collection Objects

The snippet code for this example will retrieve SNMP data about the file systems on a device and write that data to the result_handler dictionary. Our collection objects will reference OID names from the HOST-RESOURCES-MIB that contain file system information.

To create the collection objects for this Dynamic Application, perform the following steps:

  1. Select the Collections tab in the Dynamic Application Editor pane.
  2. Supply values in the following fields to create the first object, which will collect the values from the hrStorageDescr OID:
    • Object Name. The name of the collection object. Enter "hrStorageDescr" in this field.
    • Snippet Arguments. The arguments to pass to the snippet. Enter ".1.3.6.1.2.1.25.2.3.1.3" in this field. This is the numeric OID name for the OID.
    • Class Type. Select 104 Label (Always Polled) in this field.
    • Snippet. There is only one snippet for this Dynamic Application. Select SNMP Collection in this field.
    • Group Number. Select Group 1.
    • Usage Type. Select Group Index.
  1. For the remaining fields, accept the default values. Select the Save button, then select the Reset button to clear the values you entered.
  2. Repeat steps two and three to create the collection object that will collect the values from the hrStorageSize OID:
  • Object Name. Enter "hrStorageSize".
  • Snippet Arguments. The arguments to pass to the snippet. Enter ".1.3.6.1.2.1.25.2.3.1.5" in this field.
  • Class Type. Select 4 Performance Gauge in this field.
  • Snippet. There is only one snippet for this Dynamic Application. Select SNMP Collection in this field.
  • Group Number. Select Group 1.
  1. For the remaining fields, accept the default values. Select the Save button, then select the Reset button to clear the values you entered.
  2. Repeat steps four and five to create the collection object that will collect the values from the hrStorageUsed OID:
  • Object Name. Enter "hrStorageUsed".
  • Snippet Arguments. The arguments to pass to the snippet. Enter ".1.3.6.1.2.1.25.2.3.1.6" in this field.
  • Class Type. Select 4 Performance Gauge in this field.
  • Snippet. There is only one snippet for this Dynamic Application. Select SNMP Collection in this field.
  • Group Number. Select Group 1.
  1. For the remaining fields, accept the default values. Select the Save button.

Full Snippet Code

To enter the Snippet code:

  1. Select the Snippets tab.
  2. In the Snippet Registry pane, select the SNMP Collection snippet in the Snippet Name drop-down and select its wrench icon ().
  3. In the Snippet Code field, enter the following code:

try:

snmp_h = em7_snippets.snmph_from_cred_id(self.cred_details['cred_id'], self.ip)

except ValueError, e:

COLLECTION_PROBLEM = True

PROBLEM_STR = e

else:

for collection in result_handler.iterkeys():

if collection[-2:] == ".0":

oid_val = snmp_h.get(collection)

walk_tuple = ((oid, oid_val[0]),)

else:

walk_tuple = snmp_h.walk(collection)

result_list = []

for row in walk_tuple:

result_list.append((row[0].split('.')[-1], row[1]))

result_handler[collection] = result_list

Creating the Presentation Object

When you create a collection object in a Dynamic Application of type Performance, SL1 automatically creates a presentation object that corresponds to that collection object. In this example, we will remove these presentation objects and create a new presentation object that displays file system usage in percent.

To create the presentation object:

  1. Select the Presentations tab. The Dynamic Applications Presentation Objects page appears.
  2. In the Dynamic Applications Presentation Objects page, the Storage Size and Storage Used collection objects have been created by default. Select each presentation object's bomb icon () to delete them.
  1. Select the Reset button. To create a new presentation object that displays storage used, in percent, enter values in the following fields:
  • Report Name. Enter "Percentage Used" in this field.
  • Summarization State. Select Enabled. SL1 will generate a report of the presentation object.
  • Data Unit. Enter "Percent" into this field.
  • Abbreviation/Suffix. Enter "%" into this field.
  • Show as Percent. Select Yes. The graph will display percent values.
  • Formula Editor. We want our graph to display Percentage Used, so we will use the following formula:

Storage Used/Storage Size * 100

We can enter this formula manually, or by selecting the Object IDs in the Formula Editor and selecting the Add button. Using the Object IDs provided by SL1, enter the following into the Formula Editor:

(o_5511)/(o_5513)*100

NOTE: The object IDs in your Dynamic Application will be unique to your system. In the provided formula, you must replace "o_5511" and "o_5513" with the object IDs for the Storage Used and Storage Size collection objects in your system.

  1. In this example, you can leave the remaining fields at their default value. Select the Save As button to save the presentation object.

Snippet Walkthrough

try:

snmp_h = em7_snippets.snmph_from_cred_id(self.cred_details['cred_id'], self.ip)

except ValueError, e:

COLLECTION_PROBLEM = True

PROBLEM_STR = e

 

  • The snippet uses the function snmph_from_cred_id to retrieve the SNMP handle. The function stores the SNMP handle in the variable snmp_h.
  • If the function snmph_from_cred_id fails, the snippet retrieves the error message from the ValueError variable and stores the error message in the variable e.
  • If an exception occurs, the snippet sets the value of COLLECTION_PROBLEM to TRUE, to indicate a collection error has occurred and the snippet sets the value of PROBLEM_STR to the error message stored in the variable e.

 

else:

for collection in result_handler.iterkeys():

if collection[-2:] == ".0":

oid_val = snmp_h.get(collection)

walk_tuple = ((oid, oid_val[0]),)

else:

walk_tuple = snmp_h.walk(collection)

result_list = []

for row in walk_tuple:

result_list.append((row[0].split('.')[-1], row[1]))

result_handler[collection] = result_list

 

  • If the snmph_from_cred_id function is successful, the snippet iterates over the result_handler dictionary. During each iteration "collection" is set to the key from the result_handler dictionary, which are the Snippet Arguments for each collection object. On each iteration, the collection variable will contain an SNMP OID to collect.
  • If the last two characters in the collection variable are ".0", the snippet uses the snmp_h.get method (an SNMP get) to request the OID. The response is re-formatted as a list that contains a single tuple, which is the format for returned values.
  • If the last two characters in the collection variable are not ".0", the snippet uses the snmp_h.walk method (an SNMP walk) to request the OID. The response is already formatted as a list of tuples, so no additional processing is required.
  • The first element in each tuple in the walk_tuple list is the full OID for the collection. The platform expects the first element in each tuple returned for a collection object to be the index for that value. The indexes are used to associate collection objects in the same group. In this example, the name, size, and usage values for a given file system should have the same index assigned. The SNMP index is used for this purpose by iterating over the walk_tuple list to create a new list.
  • The result for each collection object is returned by assigning the list of tuples to the appropriate key in the result_handler dictionary. The result_handler dictionary can be used because all the collection objects in this example are in the same group.

Using the Dynamic Application

To use the example Dynamic Application, you must first create an SNMP credential to align with the Dynamic Application. That SNMP credential must allow SL1 to retrieve data from each subscriber device.

You can use an existing SNMP credential or create a new SNMP credential. In our example, we used the default SNMP credential EM7 Default V2.

To create a new SNMP credential, perform the following steps:

  1. Go to the Credential Management page (System > Manage > Credentials).
  2. Select the Actions menu, then select Create SNMP Credential. The Credential Editor page is displayed.
  3. Supply values in the following fields:
  • Profile Name. Name of the profile. Can be any combination of alphanumeric characters.
  • SNMP Version. SNMP version. Choices are SNMP V1, SNMP V2, and SNMP V3.
  • Port. Port SL1 will use to communicate with the external device or application.
  • Timeout (ms). Time, in milliseconds, after which SL1 will stop trying to communicate with the SNMP device.
  • Retries. Number of times SL1 will try to authenticate and communicate with the external device.

SNMP V1/V2 Settings

These fields appear only if you selected SNMP V1 or SNMP V2 in the SNMP Version field. Otherwise, these fields are grayed out:

  • SNMP Community (Read Only). The SNMP community string (password) required for read-only access of SNMP data on the remote device or application.
  • SNMP Community (Read/Write). The SNMP community string (password) required for read and write access of SNMP data on the remote device or application.

SNMP V3 Settings

These fields appear only if you selected SNMP V3 in the SNMP Version field. Otherwise, these fields are grayed out:

  • Security Name. Name used for SNMP authentication.
  • Security Pass Phrase. Password used to authenticate the credential.
  • Authentication Protocol. Select an authentication algorithm for the credential. Choices are MD5 or SHA.
  • Security Level. Specifies the combination of security features for the credentials. Choices are:
  • No Authentication / No Encryption
  • Authentication Only
  • Authentication and Encryption
  • SNMP v3 Engine ID. The unique engine ID for the SNMP agent you want to communicate with. (SNMPv3 authentication and encryption keys are generated based on the associated passwords and the engine ID.)
  • Context Name. A context is a mechanism within SNMPv3 (and AgentX) that allows you to use parallel versions of the same MIB objects. For example, one version of a MIB might be associated with SNMP Version 2 and another version of the same MIB might be associated with SNMP Version 3. For SNMP Version 3, specify the context name in this field.
  • Privacy Protocol. The privacy service encryption and decryption algorithm. Choices are DES or AES.
  • Privacy Protocol Pass Phrase. Privacy password for the credential.
  1. Select the Save button.

Aligning the Dynamic Application with a Device

To align this Dynamic Application to a device, perform the following steps:

  1. Go to the Device Manager page (Devices > Device Manager).
  2. Select the wrench icon () for the device you want to align the Dynamic Application with. The Device Properties page is displayed.

TIP: To find a device to align with the Dynamic Application, go to the Device Hardware page (Registry > Devices > Hardware) and search for devices with Comp Type of File System.

  1. Select the Collections tab. The Dynamic Application Collections page is displayed.

  1. Select the Action menu and choose Add Dynamic Application.
  2. In the Dynamic Application Alignment modal page, select our example Dynamic Application, Snippet SNMP Example. Select the credential you created in the previous section.
  3. Select the Save button. The page refreshes, and the Snippet SNMP Example Dynamic Application is displayed in the list of Dynamic Applications.

Viewing Performance Data

The first collected values will be stored within one minute. To view the performance data for this Dynamic Application:

  1. Go to the Device Manager page (Devices > Device Manager).
  2. Select the graph icon () for the device you aligned the Dynamic Application with. The Device Summary page is displayed.
  3. Select the Performance tab. The Device Performance page is displayed.

  1. Select Snippet SNMP Example in the left Navbar, then the Storage Percent presentation object Dynamic Application. A performance graph will be displayed.