Assure1 Metric Transaction Poller

Overview

The Assure1 Metric Transaction Poller runs custom checks, such as on TCP Socket Response Time or Web Page Response Time, then stores the results into a specific metric type. The Transactions interface allows users to create transaction policies. From there the metric type, zone, as well as customer rules sets can be defined.

The Metric Transaction Poller service has been setup to poll a variety of external services:

• Active Directory
• Basic HTML Form
• DNS
• IMAP
• MySQL
• NTP
• POP3
• SMTP
• TCP Socket
• Web Transaction

Transaction Poller Setup

1. 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

2. Instances must exist for the ports to be polled. Depending on the data to be polled, one way this can be accomplished is by using the "Metric NMAP TCP Port Discovery" job, which uses the "Metric Pipe Instance Discovery" application:

   PipeDisco

3. Metrics must exist for the ports to be polled. Metrics can be created in several different ways:

   1. The default rules for the "Metric Custom Poller Discovery Agent" application will create the metrics for some TCP ports depending on the device type:

      CustomPollerDisco

   2. Using a polling policy to create metrics using whatever restrictions are needed. See the Polling Policies UI and "Metric Poller Discovery Agent" application documentation:

      Configuration -> Metrics -> Polling Policies

      Metric Poller Discovery Agent

   3. Using the Polling Assignments UI to manually select which devices and instances are processed. See the related documentation:

      Configuration -> Metrics -> Polling Assignments

4. Using the Transactions UI, enable some of the default transactions, if relevant to the environment:

   Configuration -> Metrics -> Transactions

5. Enable the default Service, unless a specific configuration option is needed:

   Configuration -> Broker Control -> Services

Default Service

Field	Value
Package Name	coreCollection-app
Service Name	Metric Transaction Poller
Service Program	bin/core/collection/TransactionPollerd
Service Arguments
Service Description	Policy-based Synthetic Transaction Poller
Failover Type	Standalone (Supported: Standalone, Primary/Backup, Cluster)
Status	Disabled
Privileged	(Checked)

Default Configuration

Name	Value	Possible Values	Notes
CheckTime	900	Integer	How often (in seconds) where the application checks to see if there are any relevant changes.
DeviceZoneID	Default First Zone	Integer	The poller will only retrieve devices in the specific zone.
LogFile	logs/MetricTransactionPoller.log	Text, 255 characters	Relative path to Log File.
LogLevel	ERROR	OFF, FATAL, ERROR, WARN, INFO, DEBUG	Logging level used by application.
PollTime	300	Integer	How often the poller will start a poll cycle, in seconds.
Threads	3	Integer	Number of process threads created. The aggregator takes a third of this value (rounded up) for database threads unless overridden by the "DBThreads" application configuration.
DBThreads		Integer	Optional - Number of database threads to be created. If not specified, defaults to a third (rounded up) of "Threads" application configuration.
DeviceGroupID		Integer	Optional - If specified, the poller will only retrieve devices in the specific group.
PreferIPv4	Enabled	Enabled/Disabled	Optional - Controls whether or not to prefer IPv4 transport to communicate with Devices. This option is only considered if both IPv4 and IPv6 are available for a device. If this config is missing, IPv6 will be preferred.
SendAllViolations	Disabled	Enabled/Disabled	Optional - If enabled, thresholds will send violation notifications every poll cycle rather than only on state change. Requires 'ThresholdThreads'
ThresholdThreads		Integer	Optional - Number of threshold threads to be created. Enables the checking of thresholds in the application instead of the Default Threshold Engine. If not specified, application threshold checking is disabled.

Transaction Code

The transaction code uses the Assure1 standard rules architecture, which are 100% Perl syntax. Refer to the following articles to assist in transaction code creation:

• Core Rules Functions

• Metric Rules Functions

• Application Logging

Tokens

The following tokens are exposed for processing.

Token	Description
$MetricID	MetricID from Assure1.Metrics Table
$MetricTypeID	MetricTypeID from Assure1.Metrics Table
$DeviceID	DeviceID from Assure1.Metrics Table
$DNS	DNSName for Device from Assure1.Devices Table
$IPv4	IPv4 Address for Device from Assure1.Devices Table
$IPv6	IPv6 Address for Device from Assure1.Devices Table
$IP	Preferred IP Address for Device calculated from $IPv4, $IPv6, and the PreferIPv4 application configuration
$Target	Default connection point for Device. Will be $DNS if $DNS is populated, otherwise $IP
$SysName	SNMP SysName for Device from Assure1.DeviceInfo Table. DEPRECATED
$Community	SNMP Community String for Device from Assure1.DiscoverySNMPAccess Table. DEPRECATED - See GetSNMPSessionByDeviceID()
$MetaTags	Hash reference of device meta tags by name. (e.g. to get the value of the 'Username' meta tag: $MetaTags->{'Username'}->{'Value'}). NOTE Passwords from meta tags are stored as the literal string '*****'; the decrypted value is stored in the $Passwords token.
$Passwords	Hash reference for all decrypted password values from meta tags of render type 'Password' stored by name. (e.g. to get the value of the 'SSHPassword' meta tag: $Passwords->{'SSHPassword'}).
$InstanceID	MetricID from Assure1.Metrics Table
$InstanceName	MetricID from Assure1.Metrics Table
$TransID	TransactionID from Assure1.PollerTransactions Table
$TransName	Name from Assure1.PollerTransactions Table
$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({});
$StorageHash	Internal cache used as the StorageHash option when calling rules functions such as FindDeviceID(). NOTE: The structure of this cache is subject to change! Not recommended for custom global storage or manual manipulation; use $CustomHash.

Best Practices

• Web/Web Form Transaction: Proxy settings can be brought in from environment variables using the LWP::UserAgent env_proxy() function.

Example Integrations

Custom Transaction Template

The below snippet is a basic template that can be used when creating custom transactions for checking other types of services.

# Regex matching the raw instance name the transaction is intended to test. For example, if the transaction is testing TCP port 25, the InstanceName and identifier would be: "tcp-25".
if ($InstanceName =~ /<INSTANCE IDENTIFIER>/) {
    my $CheckTime = [gettimeofday];
    my $Status = 0; # default to failure

    # Service, web, or port specific actions. The time it takes to run these custom series of actions is used to measure Response Time.
    <ACTIONS>

    # measure how long actions took
    $CheckTime = tv_interval($CheckTime);
    if ($Status != 1) {
        $Log->Message("WARN"," -> Custom Check -> Failed!\n");
        $CheckTime = 0;
    }
    else {
        $Log->Message("INFO"," -> Custom Check -> Success in [$CheckTime] secs");
        $Status = 1;
    }

    # Cleanup actions. e.g. open files, open connections
    <CLEANUP>

    # Insert data
    $DataQueue->enqueue($MetricID . ":" . $CheckTime . ":" . $Status . ":" . $CurrentTime);
}

Administration Details

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

• Package - coreCollection-app

• Synopsis - ./TransactionPollerd [OPTIONS]

• Options:

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

• Threaded - Multi-Threaded