Assure1 Metric Custom Poller Discovery Agent¶

Overview¶

The Assure1 Metric Custom Poller Discovery Agent uses rules to create metrics that will be polled from a device. This is accomplished by using the instance information that was previously gathered by other applications and entered into the Assure1 database.

For example, the default job and rules configuration will create the base metric entries for the following:

Interface Inbound and Outbound Bandwidth, Errors and Discards metrics can be created depending on the Device Type and Instance Name. There are rules for the Device Types of Server, Switch and Router that are provided by default, and each Device Type has separate set of Instance Name requirements that are needed for metric creation to occur. Other Device Types will not be processed.
Response Time metrics can be created depending on the Device Type and Instance Name. There are rules for the Device Types of Switch and Router that are provided by default, and both of those Device Types has separate set of Instance Name requirements that are needed for metric creation to occur. All instances for the Device Type of Server will be processed. Other Device Types will not be processed.
Ping Polling metrics can be created for all devices. There are no limitations done on Device Type in these rules, and the metrics will only be created on the "Device" instance, which is created by default for all devices.

Custom Poller Discovery Agent Setup¶

Devices must exist in the Device Catalog for this application to be able to function. Devices can be created in several different ways:
1. Using the Device Auto Discovery application (DeviceAutoDiscovery). See the application documentation for additional information.
2. Using the Manual Discovery UI:
  
  Configuration -> Device Discovery -> Manual Discovery
3. Manually entering all values using the Devices UI:
  
  Configuration -> Device Catalog -> Devices
Optional - The bandwidth metric creation functionality requires that instances have been discovered using the Metric SNMP Network Interface Discovery Agent job (which uses the SNMPInterfaceDiscoveryAgent application), or via another method.
Optional - The response time metric creation functionality requires that instances have been discovered using the Metric NMAP TCP Port Discovery job (which uses the PipeDisco application), or via another method.
Review the logic in the rules files referenced in the configuration to see the processing that will be done on the devices that are selected:
- LoadRules will be executed during application startup to load data that might be needed during processing.
- IncludeRules will be read during application startup to load additional files that might be called during processing. In a default configuration, there are several rules files that are included so they can be called from the BaseRules.
- BaseRules will be executed for each device that is selected based on the configuration.
Update the logic as needed.
Enable the default Job, unless a specific configuration option is needed.

Configuration -> Broker Control -> Jobs

Default Scheduled Job¶

Field	Value
Package Name	coreCollection-app
Job Name	Metric Custom Poller Discovery
Job Program	bin/core/collection/CustomPollerDisco
Job Arguments
Job Description	Rules-based Polling configuration agent
Failover Type	Standalone (Supported: Standalone, Primary/Backup)
Status	Disabled
Privileged	(Checked)
Minutes	59
Hours	0
Days	*
Months	*
WeekDays	0

Default Configuration¶

Name	Value	Possible Values	Notes
BaseRules	collection/metric/pollerdisco/custom/base.rules	Text, 255 characters	Relative path to Base Rules.
BranchDir	core/default	Text, 255 characters	relative path to Rules dir.
DeviceZoneID	Default First Zone	Integer	This entry is used to get a more specific list of devices to run the discovery agent against.
IncludeRules	collection/metric/pollerdisco/custom/base.includes	Text, 255 characters	Relative path to Include Rules.
LoadRules	collection/metric/pollerdisco/custom/base.load	Text, 255 characters	Relative path to Load Rules.
LogFile	logs/MetricPollerDiscovery.log	Text, 255 characters	Relative path to Log File.
LogLevel	ERROR	OFF, FATAL, ERROR, WARN, INFO, DEBUG	Logging level used by application.

Best Practices¶

The default job configuration is to run every Sunday at 12:59:00am.

Rules¶

This connector uses the Assure1 standard rules architecture. The rules are written in Perl syntax. Refer to the following guides for details on rules creation:

Tokens¶

The agent exposes the following tokens for rules processing.

Token	Description
$Instance->{CustomName}	The Metric Instance Custom Name for the device being processed.
$Instance->{DeviceID}	The Assure1 Device ID for the device being processed.
$Instance->{DevicePriorityID}	The Priority value for the device being processed.
$Instance->{DeviceStateID}	The State for the device being processed.
$Instance->{DeviceTypeCategoryID}	The Device Type Category ID for the device being processed.
$Instance->{DeviceTypeCategoryName}	The Device Type Category Name for the device being processed.
$Instance->{DeviceTypeName}	The Device Type Name for the device being processed.
$Instance->{DeviceTypeVendorID}	The Device Type Vendor ID for the device being processed.
$Instance->{DeviceTypeVendorName}	The Device Type Vendor Name for the device being processed.
$Instance->{DNSName}	The DNS Name for the device being processed.
$Instance->{InstanceID}	The Metric Instance ID for the instance being processed.
$Instance->{InstanceName}	The Metric Instance Name for the instance being processed.
$Instance->{IPv4}	The IP v4 for the device being processed.
$Instance->{IPv6}	The IP v6 for the device being processed.
$Instance->{SysName}	The System Name for the device being processed.
$Instance->{SysObjectID}	The System Object ID for the device being processed.
$AppConfig	Hash reference to the application configuration name-value pairs that were configured. (i.e. use $AppConfig->{'Host'} to retrieve the set value for 'Host'.)
$CustomHash	$Custom key, value cache available across all rules. Contents commonly defined in Load Rules then used in Base or other rules. NOTE: This variable is a shared object and any additional sub hashes or arrays must be shared before use or it will cause the error: "Invalid value for shared scalar". Instantiate the sub hash/array using '&share({})' e.g. $CustomHash->{SubObject} = &share({});

Example Enhancement¶

Adding Thresholds to Metrics¶

While the metrics are being created in the rules, various thresholds can also be added to the metrics automatically. Information regarding the default Thresholds that come with Assure1 is available via the Thresholds UI.

Configuration -> Metrics -> Thresholds -> Thresholds

Here is a snippet of the original code from the "ping.include.rules" that creates a latency metric:

    ($Error, $Message, $MetricID) = FindMetricID({
        DBH          => \$Assure1DBH, 
        StorageHash  => $MetricHash, 
        DeviceID     => $Instance->{'DeviceID'}, 
        InstanceID   => $Instance->{'InstanceID'}, 
        MetricTypeID => 60, 
        Factor       => 1, 
        Max          => 0, 
        PollInterval => $PollInterval, 
        Create       => 1
    });
    UpdateMethodOnMetric({
        DBH      => \$Assure1DBH, 
        MetricID => $MetricID, 
        MethodID => 0
    });

Here is the code that can be used after the above to add the thresholds:

    # Adds the "Device Down" threshold
    ($ErrorFlag, $Message) = AddThresholdToMetric({
        DBH         => \$Assure1DBH, 
        MetricID    => $MetricID, 
        ThresholdID => 1
    });

    # Adds the "Latency High" threshold
    ($ErrorFlag, $Message) = AddThresholdToMetric({
        DBH         => \$Assure1DBH, 
        MetricID    => $MetricID, 
        ThresholdID => 3
    });

Administration Details¶

The following list shows the technical details needed for advanced administration of the application:

Package - coreCollection-app
Synopsis - ./CustomPollerDisco [OPTIONS]

Options:

 -c, --AppConfigID N   Application Config ID (Service, Job, or Request ID)
 -d, --DeviceID N      DeviceID (Optional)
 -?, -h, --Help        Print usage and exit

Threaded - Single Threaded