TransactionPollerd

The Oracle Communications 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, and customer rules sets can be defined.

Configuration -> Metrics -> Transactions

The Metric Transaction Poller service has been set up to poll a variety of external services like:

You can run this application as a service using the Services UI.

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 Core Device Auto Discovery application.

    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.

  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.

    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

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

      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

The following table shows the settings for the default service. Actual values are in bold, descriptions of values are in plaintext.

Field Value
Package coreCollection-app
Name Metric Transaction Poller
Program bin/core/collection/TransactionPollerd
Arguments This field is blank. There is no default value.
Description Policy-based Synthetic Transaction Poller
Failover Type Standalone (Supported: Standalone, Primary, Redundant/Backup, Cluster)
Status Disabled
Privileged This option is selected.

See Services in Unified Assurance User's Guide for general information about the settings for services.

See Using Application Primary/Backup Failover and Using Application Clustering for more information about the different failover types.

Default Configuration

The following table shows the default configurations for the application. Actual values are in bold, descriptions of values are in plaintext.

Name Default Value Possible Values Notes
CheckTime 900 An integer How often (in seconds) where the application checks to see if there are any relevant changes.
DeviceZoneID Default First Zone All Zones or the name of any available device zone. The poller will only retrieve devices in the specific zone.
LogFile logs/MetricTransactionPoller.log Text, 255 characters The relative path to the log file.
LogLevel ERROR OFF, FATAL, ERROR, WARN, INFO, DEBUG The logging level for the application.
PollTime 300 An integer How often the poller will start a poll cycle, in seconds.
Threads 3 An 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 This field is blank. There is no default value. An integer (Optional) Number of database threads to be created. If not specified, defaults to a third (rounded up) of Threads application configuration.
DeviceGroupID This field is blank. There is no default value. The name of any available device group. (Optional) If specified, the poller will only retrieve devices in the specific group.
PreferIPv4 Enabled Enabled or 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 or Disabled (Optional) If enabled, thresholds will send violation notifications every poll cycle rather than only on state change. Requires 'ThresholdThreads'
ThresholdThreads This field is blank. There is no default value. An 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 in Perl syntax. For information about creating rules, see the following in Unified Assurance Developer's Guide:

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 DEPRECATED The SNMP SysName for Device from Assure1.DeviceInfo Table.
$Community DEPRECATED See GetSNMPSessionByDeviceID(). The SNMP Community String for Device from Assure1.DiscoverySNMPAccess Table.
$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 you will need for advanced administration of the application: