Unified Assurance Metric Transaction Poller

Overview

The Unified Assurance 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.

Configuration -> Metrics -> Transactions

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

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. See the application documentation for additional information.

      Core Device Auto Discovery

    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:

    Metric Pipe Instance Discovery

  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:

      Metric Custom Poller Discovery Agent

    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 Unified Assurance standard rules architecture, which are 100% Perl syntax. Refer to the following articles to assist in transaction code creation:

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

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: