Performance and Configuration Snippets

This section describes how to define collection objects and snippet code for the following types of Snippet Dynamic Applications:

Snippet Configuration
Snippet Performance
Bulk Snippet Configuration
Bulk Snippet Performance

All other elements of these Dynamic Applications, such as presentation objects and alerts, behave in the same manner as other Dynamic Application types.

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 ().

Collection Objects

Similar to other Dynamic Application types, Snippet Dynamic Applications contain collection objects. Collection objects for Snippet Dynamic Applications have characteristics common to collection objects for other Dynamic Application types, such as naming, data typing, and grouping.

Collection objects for Snippet Dynamic Applications have the following unique elements:

Snippet Arguments. When a snippet is executed by SL1, the snippet is passed information about each collection object defined in the Dynamic Application, including the name and class type for the collection object. The Snippet Arguments field is used to provide additional parameters to indicate to the snippet code how to perform collection for that collection object. For example, if the snippet code is using the SNMP protocol to collect data from the device, the Snippet Arguments might define the OID to walk for each collection object.
Snippet. Because a Snippet Dynamic Application can contain multiple snippets, each collection object in a Snippet Dynamic Application must be associated with a specific snippet that is responsible for collecting that collection object.

Snippet Code

Snippet Dynamic Applications must have one or more snippets defined under the Snippets tab in the Dynamic Application pane. Snippets have the following properties:

Snippet Name. The name of the snippet.
Active State. Specifies whether the snippet should be executed by SL1 when performing collection for the Dynamic Application. Choices are:

Enabled. SL1 will execute this snippet when performing collection for the Dynamic Application.
Disabled. SL1 will not execute this snippet when performing collection for the Dynamic Application.

Required. Specifies whether this snippet is required for successful collection of all other snippet requests. Choices are:

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.
Not Required - Continue Collection. If this snippet request fails, the platform will continue executing all remaining snippet requests in this Dynamic Application. Dynamic Applications that consume the cache of this Dynamic Application will continue collection.

Snippet Code. The python code that will be executed when SL1 performs collection for this Dynamic Application.

The snippet code must be a block of valid python code that performs collection and passes collected values to SL1 using the dictionary called result_handler. This section describes:

Using the result_handler dictionary.
The variables available to snippet code.
How to use aligned credentials.
How to log collection problems in snippet code.

Populating Collection Objects

To pass collected values back to SL1, snippet code must populate the result_handler dictionary.

NOTE: The legacy self.oids dictionary is no longer supported but will continue to work for older Dynamic Applications. ScienceLogic recommends using result_handler for all Dynamic Applications.

The snippet code must populate the result_handler dictionary. Before each snippet is executed, SL1 populates result_handler with information about all the collection objects in the current snippet. Some elements in the dictionary are left undefined and must be populated by your snippet code.

For Snippet Performance and Snippet Configuration Dynamic Applications, result_handler has the following structure:

oid: {'prime': , 'error_msg': , 'enum': , 'name': ,

'oid': , 'string_type': , 'class': , 'wm_walk_length': , 'oid_time': , 'result': , 'oid_type': , 'factor': '', 'trend_col': '', 'monitor_config': },

}

oid: {'prime': , 'error_msg': , 'enum': , 'name': ,

'oid': , 'string_type': , 'class': , 'wm_walk_length': , 'oid_time': , 'result': , 'oid_type': , 'factor': '', 'trend_col': '', 'monitor_config': },

}

For Bulk Snippet Performance and Bulk Snippet Configuration Dynamic Applications, result_handler has the following structure:

(device id, oid): {'prime': , 'error_msg': , 'enum': , 'name': ,

'oid': , 'string_type': , 'class': , 'wm_walk_length': , 'oid_time': , 'result': , 'oid_type': , 'factor': '', 'trend_col': '', 'monitor_config': },

}

(device id, oid): {'prime': , 'error_msg': , 'enum': , 'name': ,

'oid': , 'string_type': , 'class': , 'wm_walk_length': , 'oid_time': , 'result': , 'oid_type': , 'factor': '', 'trend_col': '', 'monitor_config': },

}

For Snippet Performance and Snippet Configuration Dynamic Applications, result_handler uses the oid value (Snippet Argument) as a key for each collection object. For Bulk Snippet Performance and Bulk Snippet Configuration Dynamic Applications, result_handler uses a tuple of the device ID and the oid value (Snippet Argument) as a key for each collection object, i.e. result_handler includes an entry for every collection object for every device that the snippet code has been assigned.

Each entry in result_handler has a dictionary that contains the following keys:

oid. The value defined in the Snippet Arguments field in the Collection Objects page for this collection object.
prime. The value defined for the Index checkbox in the Collection Objects page for this collection object.
error_msg. An optional error message associated with this collection object. Snippets should set this value to an error message string if this object cannot be collected.
enum. The value defined in the Enums field in the Collection Objects page for this collection object.
name. The value defined in the Object Name field in the Collection Objects page for this collection object.
oid. The value defined in the Snippet Arguments field in the Collection Objects page for this collection object.
string_type. This value refers to the internal operation of SL1's collection process. Do not modify this value.
class. The value defined in the Class Type field in the Collection Objects page for this collection object. class is set to the integer value that appears at the beginning of each Class Type option.
wm_walk_length. This value refers to the internal operation of SL1's collection process. Do not modify this value.
oid_time. Your snippet can optionally set this value to the amount of time in seconds it took to collect the object.
result. The collected value or values for this collection object. Your snippet code must populate result with a list of tuples. Each result tuple must contain two values: an index followed by a result string. The index can be any scalar type, but no two tuples can have the same index value.
oid_type. The ID number of the snippet responsible for collecting this collection object. Your snippet should use this value to determine whether the snippet should collect this object, i.e. compare this value to the value in the snippet_id variable.
factor. This value refers to the internal operation of SL1's collection process. Do not modify this value.
trend_col. This value refers to the internal operation of SL1's collection process. Do not modify this value.
monitor_config. This value refers to the internal operation of SL1's collection process. Do not modify this value.

To update the result value for a collection object using the result_handler dictionary, assign a value directly to the key for that collection object. Remember that the keys in result_handler are::

For Snippet Performance and Snippet Configuration Dynamic Applications, the value in the Snippet Arguments field.
For Bulk Snippet Performance and Bulk Snippet Configuration Dynamic Applications, a tuple that includes a device ID and the value in the Snippet Arguments field.

For example:

result_handler['cpu'] = [(0,0),]

cpu. This is the Snippet Argument, used to uniquely identify the collection object
0,0. At index zero, set the value to zero.

You can update the result value for all the collection objects at the same time by using the update() function of result_handler. For example:

result_handler.update(results)

The results parameter must be a dictionary that has the same keys as result_handler. Each key in the supplied dictionary must reference that value to be set as the result value for that collection object.

Available Variables

The following local variables are available to use in your snippet code for Snippet Performance and Snippet Configuration Dynamic Applications:

snippet_id. The ID number for this snippet.
this_device. A named tuple that contains information about the device for which collection is being performed.
parent_device. This variable is available for component devices and merged devices. A named tuple that contains information about the direct parent of the component device for which collection is being performed.
root_device. This variable is available only for component devices. A named tuple that contains information about the root device of the component device for which collection is being performed.
self.cred_details. A dictionary that contains information about the credential aligned with the Dynamic Application. For information about the structure of credential dictionaries, see the section Using Credential Dictionaries.
self.device_ip.The IP address of the target device for which collection is being performed. This variable is available for component or merged devices.
self.device_hostname. The hostname of the target device for which collection is being performed. This variable is available for component or merged devices.
self.device_pdu_packing. A boolean value indicating if PDU Packing is enabled on the target device for which collection is being performed. This variable is available for component or merged devices. PDU packing enables quicker collection of voluminous SNMP data. For more information, see Additional Configuration for Concurrent Network Interface Collection.
self.root_ip. The IP address of the root device of the component device for which collection is being performed. This variable is available for component or merged devices.
self.root_hostname. The hostname of the root device of the component device for which collection is being performed. This variable is available for component or merged devices.
self.root_pdu_packing. A boolean value indicating if PDU Packing is enabled on the root device of the component device for which collection is being performed. This variable is available for component or merged devices. PDU packing enables quicker collection of voluminous SNMP data. For more information, see Additional Configuration for Concurrent Network Interface Collection.

The this_device, parent_device, and root_device named tuples include the following values:

did. The device ID for the device.
name. The name of the device.
ip. The primary management IP address of the device.
snmp_cred_id. The ID of the SNMP read credential assigned to the device.
root_did. For component devices, the device ID of the root device associated with the device.
parent_did. For component devices, the device ID of the direct parent for the device.
unique_id. For component devices, the unique identifier of the component device. This variable is equivalent to the %U component identifier substitution variable for WMI, XSLT, and SOAP Dynamic Applications.
guid. For component devices, the globally unique identifier of the component device. This variable is equivalent to the %G component identifier substitution variable for WMI, XSLT, and SOAP Dynamic Applications.

For example, to use the name of the root device of the component device for which collection is being performed, you would use the variable root_device.name.

Available Variables for Bulk Performance and Bulk Configuration Snippets

The following local variables are available to use in your snippet code for Bulk Snippet Performance and Bulk Snippet Configuration Dynamic Applications:

snippet_id. The ID number for this snippet.
self.cred_details. A dictionary that contains information about the credential aligned with the Dynamic Application. For information about the structure of credential dictionaries, see the section Using Credential Dictionaries.
devices. A dictionary that contains information about the devices for which collection is being performed. During each collection, the platform will automatically assign one or more devices to each execution of your snippet code. The keys in the devices dictionary are the device IDs of the devices assigned to the snippet. The values in the devices dictionary are named tuples with the following values:

device. A named tuple that contains information about the component device for which collection is being performed.
parent_device. Contains the device ID of the direct parent of the component device for which collection is being performed.

The device named tuples in the devices dictionary include the following values:

did. The device ID for the device.
name. The name of the device.
ip. The primary management IP address of the device.
snmp_cred_id. The ID of the SNMP read credential assigned to the device.
root_did. For component devices, the device ID of the root device associated with the device.
parent_did. For component devices, the device ID of the direct parent for the device.
unique_id. For component devices, the unique identifier of the component device. This variable is equivalent to the %U component identifier substitution variable for WMI, XSLT, and SOAP Dynamic Applications.
guid. For component devices, the globally unique identifier of the component device. This variable is equivalent to the %G component identifier substitution variable for WMI, XSLT, and SOAP Dynamic Applications.

For example, to use the name of the device with ID 16, you would use the variable devices[16].device.name.

Using Credentials

When information about a credential is passed by SL1 to snippet code in a variable, the credential information is stored in a dictionary. This section describes the structure of credential dictionaries. Snippet Dynamic Applications can use any type of credential.

TIP: If your snippet code requires that a specific credential type be aligned with the Dynamic Application, you can examine the cred_type field and generate an appropriate error message if an incorrect credential is aligned. This check will ensure that your snippet code does not reference an entity in the credential dictionary that does not exist in the aligned credential.

Several elements in the credential dictionary are common to all credential types, and each credential type (other than Basic/Snippet) has unique elements that appear only in the credential dictionary for that credential type. The following elements are common to every type of credential dictionary:

cred_id. Integer. Unique credential ID.
cred_type. Integer. Type of credential .

1 SNMP. SNMP credentials allow SL1 to access SNMP data on a managed device.
2 DB. Database credentials allow SL1 to access data on a database on a managed device.
3 SOAP/XML. SOAP/XML credentials allow SL1 to access a web server on a managed device.
4 LDAP. LDAP or Active Directory credentials allow SL1 to access data on an LDAP server or Active Directory server.
5 Snippet. Basic/Snippet credentials define standard authentication parameters, but are not tied to a specific authentication protocol.
6 SSH. SSH/Key credentials specifies the hostname or IP address of the system you want to monitor, the port number used to access that system, and the private key used for authentication.
7 PowerShell. PowerShell credentials allow Dynamic Applications to retrieve data from Microsoft devices.

NOTE: For more information, the section on Credential Management.

cred_host. String. Host name or IP address (%D substitution string).
cred_port. Integer. TCP/IP port for connections.
cred_pwd. String. Password (encrypted in the database, stored as clear text in the dictionary).
cred_user. String. Username.
cred_timeout. Integer. Timeout in milliseconds.

The following elements are unique for SNMP credentials:

snmp_version. Integer. SNMP version, values 1, 2, 3.
snmp_ro_community. String. Read-only community string.
snmp_rw_community. String. Read/Write community string.
snmp_retries. Integer. Number of retries.
snmpv3_auth_proto. String. V3 auth. protocol,. Can be either MD5 or SHA.
snmpv3_sec_level. String. V3 security. Can be noAuthNoPriv, AuthNoPriv, or AuthPriv.
snmpv3_priv_proto. String. V3 privacy protocol. Can be : DES or AES.
snmpv3_priv_pwd. String. V3 password encrypted in the database and stored as clear text in the dictionary.
snmpv3_context. String. V3 context.

The following elements are unique for Database credentials:

db_type. Integer.

1 MySQL
2 MSSQL
3 Oracle
4 Postgress
5 DB2
6 Sybase
7 Informix
8 Ingress).

db_name. String. Initial database name.
db_sid. String. Database SID (Oracle only).
db_connect. String. Database connect string (Oracle only).

The following elements are unique for SOAP/XML credentials:

curl_url. String. URL.
curl_proxy_ip. String. Proxy server IP address.
curl_proxy_port. Integer. Proxy server TCP/IP port.
curl_proxy_acct. String. Proxy server account.
curl_proxy_passwd. String. Proxy server password.
curl_encoding. String. Encoding method (eg text/xml).
curl_post_or_get. Integer. HTTP method 0 – GET, 1- POST.
curl_http_version. HTTP version: 10 = 1.0, 11 = 1.1.
curl_request_sub_1. String. Substitution value to substitute into Snippet code.
curl_request_sub_2. String. Substitution value to substitute into Snippet code.
curl_request_sub_3. String. Substitution value to substitute into Snippet code.
curl_request_sub_4. String. Substitution value to substitute into Snippet code.
curl_headers. List of Strings. Each string is a HTTP key/value pair.
curl_opts. Dictionary of Curl options comprising a series of pairs of string key and corresponding string value.

Reporting Collection Status

Your snippet code must report when collection was successful. The following local variables are defined for this purpose:

COLLECTION_PROBLEM. By default, this variable is automatically instantiated. Its default value is False. When your snippet code completes, you can set this variable to True to indicate that there was a problem with collection (i.e. indicating a missed poll). When your snippet code completes, you can set this variable to False to indicate that collection was successful. This variable is set to True at the start of each collection; you must set this variable to False to report a successful collection.
PROBLEM_STR. This variable can be used with the COLLECTION_PROBLEM variable, to provide a description of the problem with collection. If you set the COLLECTION_PROBLEM variable to True (indicating a missed poll), you can additionally specify why the collection failed by assigning a string value to the PROBLEM_STR variable. SL1 will use the string value of PROBLEM_STR to generate an alert.

Generating Alerts

As with other Dynamic Application types, you can use alert formulas and linked event policies to generate events in response to Snippet polling of remote systems. You might also need to generate logs and events about the collection process itself. For example, you might want to generate an alert if an external device does not respond or if the supplied credential is invalid. There are three methods you can use to generate these logs:

Generate an internal alert for the problem. The alert will be associated with the device the Dynamic Application is currently collecting data from. SL1 includes event policies that will trigger if a snippet generates an internal alert.
Generate a custom alert for the problem. A custom alert does not have to be associated with the device the Dynamic Application is currently collecting data from; a custom alert can be associated with entity types other than devices, for example, an Organization or an Asset. You can define your own custom event policies for custom alerts.
Create one or more collection objects within your Dynamic Application to specifically monitor collection problems.

Generating an Internal Alert

Generating an internal alert is the method used to log collection problems in the examples in this document. During collection, SL1 maintains a list of internal alerts that are processed and can trigger events after collection is complete.

The data structure for internal alerts is a Python list of tuples. Each tuple has two elements: a message ID and supporting message text. You can use the following values for the message ID element:

257. Triggers a "General Collection Problem" event, which has a severity of "Major".
519. Triggers a "Dynamic Snippet Exception" event, which has a severity of "Minor".
518. Triggers a "Dynamic Snippet Message" event, which has a severity of "Notice".

To generate an event for a collection problem using the built-in method, append a tuple with your message to the self.internal_alerts list. For example:

self.internal_alerts.append((257, "Cannot connect to remote device"))

Generating a Custom Alert

To generate a custom alert, you can use the following function:

em7_snippets.generate_alert(message, xid, xtype, yid, ytype, yname, value, threshold)

You can define an event based on the alert; the event must have a Source of API and use pattern matching to match the alert. The arguments for the function are:

message. Required argument. The message text for the alert.

xid = value. Required argument. The entity to associate with the alert. Supply the numeric ID of an entity. For example, if you supply '1' in the xtype argument, supply a device ID in this argument.
xtype = value. Required argument. The type of entity for which you specified an ID in the xid argument. Supply one of the following integer values:

0. Organization
1. Device
2. Asset
4. Network
5. Interface
6. Vendor
7. User Account
8. Virtual Interface
9. Device Group
10. IT Service
11. Ticket

yid = value. The sub-entity to associate with the alert. Supply the numeric ID of a sub-entity. For example, if you supply '3' in the ytype argument, supply a file system ID in this argument.
ytype = value. Optional argument. The type of sub-entity for which you specified an ID in the yid argument. Supply one of the following integer values:

9. News Feed (if xtype is 0) or Process (if xtype is 1).
1. CPU. Can be specified only if xtype is 1 (Device).
2. Disk. Can be specified only if xtype is 1 (Device).
3. File System. Can be specified only if xtype is 1 (Device).
4. Memory. Can be specified only if xtype is 1 (Device).
5. Swap. Can be specified only if xtype is 1 (Device).
6. Hardware Component. Can be specified only if xtype is 1 (Device).
7. Interface. Can be specified only if xtype is 1 (Device).
10. Port. Can be specified only if xtype is 1 (Device).
11. Windows Service. Can be specified only if xtype is 1 (Device).
12. Web Content. Can be specified only if xtype is 1 (Device).
13. Email Monitor. Can be specified only if xtype is 1 (Device).

yname = value. Optional argument. The name of the sub-entity for which you specified an ID in the yid argument.
value= string. Optional argument. A value that will be passed with the alert message. This value is available in the %V substitution character for event policies.
threshold= string. Optional argument. A threshold value that will be passed with the alert message. This threshold value is available in the %T substitution character for event policies.

For example:

em7_snippets.generate_alert('Attempted File System Cleanup', '60', '1', '150', '3')

will generate an alert with the message "Attempted File System Cleanup" associated with the file system with ID 150 on the device with ID 60.

Self-Reporting Collection Objects

The self-reporting method uses one or more collection objects (that you define in your Dynamic Application) to report application-specific failures. You can additionally define alerts that evaluate the values returned for these collection objects.

For example, you might define a single un-grouped collection object called "Collection Status" and assign it a value specific to your collection method. If your snippet executes successfully, the snippet would set the value to "OK"; otherwise the snippet would set the value to a failure message, such as "authentication failed" or "connection timeout". Each of these can then be handled separately with appropriate alert definitions and associated event policies.

Writing Debug Information to silo.log

Using the following function, you can configure your snippet to write messages to silo.log:

em7_snippets.logger(filename)

For example:

logger=em7_snippets.logger(filename='/var/log/em7/silo.log')

Your snippet code will then write messages to the log file using the following syntax:

logger.debug("message")

Starting with SL1 version 11.3.0, you can no longer use this process to specify a "filename" for output. Instead SL1 will write to /var/log/sl1/snippets.log.

Debug messages will appear in the specified file on the Data Collector or All-In-One Appliance that runs the snippet. When SL1 executes snippet code for configuration Snippet and performance Snippet Dynamic Applications, the snippet code writes debug logs to silo.log regardless of the Debug Mode setting for the process "Data Collection: Dynamic App". Therefore, to avoid debug logging on production systems, you must use debug logging only when developing snippet code in a test environment, then remove or comment out debug statements when you have completed development and testing.