Metrics
The Metrics library implements the functions for Metric rules.
Synopsis
use Assure1::Metrics;
Functions
The Metrics library contains the methods described below.
AddCollectionToPolicy
Adds a collection to a consolidation policy.
AddCollectionToPolicy(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
PolicyID - The consolidation policy to add the collection to.
CollectionID - The collection to add.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = AddCollectionToPolicy({
DBH => \$DBH,
PolicyID => $PolicyID,
CollectionID => $CollectionID
});
AddDisplayInstance
Adds a display instance.
AddDisplayInstance(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
DeviceID - The display device ID.
InstanceID - The source metric instance ID.
CustomName - The display label.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. DisplayID (int) undef on error
Synopsis
my ($ErrorFlag, $Message, $DisplayID) = AddDisplayInstance({
DBH => \$DBH,
DeviceID => $DeviceID,
InstanceID => $InstanceID,
CustomName => $CustomName
});
AddMetricToCollection
Adds a metric to a collection.
AddMetricToCollection(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
CollectionID - The ID of the collection to add the metric to.
MetricID - The ID of the metric to add to the collection.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = AddMetricToCollection({
DBH => \$DBH,
CollectionID => $CollectionID,
MetricID => $MetricID
});
AddThresholdToMetric
Adds a threshold to a metric.
AddThresholdToMetric(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
MetricID - The ID of the metric to add the threshold to.
ThresholdID - The ID of the threshold to add to the metric.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = AddThresholdToMetric({
DBH => \$DBH,
MetricID => $MetricID,
ThresholdID => $ThresholdID
});
CreateMeasurementFromMetricType
A helper function that converts a Unified Assurance MetricTypeName to an Influx Measurement.
CreateMeasurementFromMetricType($MetricType)
Arguments
MetricType - The Unified Assurance metric type name to convert.
Returns
1. Influx Measurement
Synopsis
my $Measurement = CreateMeasurementFromMetricType($MetricType);
FindCollectionID
Finds a collection by name. If the Create option is set to true (1), and no collection with the specified name exists, it will be automatically created.
FindCollectionID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
Name - The name of the collection to find.
Description - (Optional) Description
Create - (Optional) Set to 1 to create the collection if it does not exist, set to 0 otherwise.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Collection ID (Integer) or undef if not created
Synopsis
my ($ErrorFlag, $Message, $CollectionID) = FindCollectionID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Collection",
Description => "",
Create => 1
});
if (!$CollectionID) {
$Log->Message('ERROR', "Error Finding Collection: $Message");
}
OR
my $CollectionID = FindCollectionID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Collection",
Description => "",
Create => 1
});
if (!$CollectionID) {
$Log->Message('ERROR', "Error Finding Collection");
}
FindInstanceID
Find an instance by name and type. If the Create option is set to true (1), and no instance with the specified name exists, it will be automatically created.
FindInstanceID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
DeviceID - Device
Name - Instance Name
TypeID - Instance Type
0 - Unknown - N/A
1 - SNMP Interface
2 - SNMP Custom
3 - SNMP IPSLA
4 - Transaction
5 - Custom
6 - Service
Create - (Optional) Set to 1 to create the instance if it does not exist, set to 0 otherwise.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Instance ID (Integer) or undef if not created/updated
Synopsis
my ($ErrorFlag, $Message, $InstanceID) = FindInstanceID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Instance",
DeviceID => $DeviceID,
TypeID => 5,
Create => 1
});
if (!$InstanceID) {
$Log->Message('ERROR', "Error Finding Instance: $Message");
}
OR
my $InstanceID = FindInstanceID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Instance",
DeviceID => $DeviceID,
TypeID => 5,
Create => 1
});
if (!$InstanceID) {
$Log->Message('ERROR', "Error Finding Instance");
}
FindInstanceByIfIndex
Finds an instance by interface index and returns the instance ID. To use the IfIndex option to find instances, the SNMP Interface Discovery Agent must have been run to store DeviceInterfaces.
FindInstanceByIfIndex(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
DeviceID - Device
IfIndex - Interface Index
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Instance ID (Integer) or undef if not created/updated
Synopsis
my ($ErrorFlag, $Message, $InstanceID) = FindInstanceByIfIndex({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceID => $DeviceID,
IfIndex => $IfIndex
});
if (!$InstanceID) {
$Log->Message('ERROR', "Error Finding Instance: $Message");
}
OR
my $InstanceID = FindInstanceByIfIndex({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceID => $DeviceID,
IfIndex => $IfIndex
});
if (!$InstanceID) {
$Log->Message('ERROR', "Error Finding Instance");
}
FindMetricID
Finds metric and returns their IDs. If the Create option is set to true (1):
- When no matching metric is found, the metric will be automatically created.
- When the matching metric is found and the value specified for Max is different, the value of Max is updated.
FindMetricID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
DeviceID - Device
InstanceID - Instance
MetricTypeID - Metric Type
Factor - (Required if Create is set to 1) Metric Factor
Max - (Required if Create is set to 1) Metric Maximum
PollInterval - (Required if Create is set to 1) Poll Interval
Create - (Optional) Set to 1 to create the metric if it does not exist, or to update Max. Set to 0 otherwise.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Metric ID (Integer) or undef if not created
Synopsis
my ($ErrorFlag, $Message, $MetricID) = FindMetricID({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceID => $DeviceID,
InstanceID => $InstanceID,
MetricTypeID => $MetricTypeID,
Factor => 1,
Max => 0,
PollInterval => 300,
Create => 1
});
if (!$MetricID) {
$Log->Message('ERROR', "Error Finding Metric: $Message");
}
OR
my $MetricID = FindMetricID({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceID => $DeviceID,
InstanceID => $InstanceID,
MetricTypeID => $MetricTypeID,
Factor => 1,
Max => 0,
PollInterval => 300,
Create => 1
});
if (!$MetricID) {
$Log->Message('ERROR', "Error Finding Metric");
}
FindMetricTypeID
Finds metric types by name. If the Create option is set to true (1), and no metric type with the specified name exists, the metric type will be automatically created.
FindMetricTypeID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
Name - The name of the metric type
Measurement - Measurement
FormatID - Format:
0: integer
1: float
Direction - TopN sort:
0: Descending
1: Ascending
Unit - Unit Label (for example, Bytes/sec)
UnitDivision - What number to roll up (for example, 1024 = Bytes -> MegaBytes)
Abbreviation - Abbreviation on Graph
MaxDefault - MaxDefault
TopNTypeID - Top N type
TopNScopeID - Top N scope
MetricGroupID - (Optional) Metric group to assign
Create - (Optional) Set to 1 to create the metric type if it does not exist, set to 0 otherwise.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Metric Type ID (Integer) or undef if not created/updated
Synopsis
my ($ErrorFlag, $Message, $MetricTypeID) = FindMetricTypeID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Metric Type",
Measurement => $Measurement,
FormatID => 0,
Direction => 0,
Unit => "Bytes/sec",
UnitDivision => 1024,
Abbreviation => "bps",
MaxDefault => $MaxDefault,
TopNTypeID => $TopNType,
TopNScopeID => $TypNScope,
Create => 1
});
if (!$MetricTypeID) {
$Log->Message('ERROR', "Error Finding Metric Type: $Message");
}
OR
my $MetricTypeID = FindMetricTypeID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Metric Type",
Measurement => $Measurement,
FormatID => 0,
Direction => 0,
Unit => "Bytes/sec",
UnitDivision => 1024,
Abbreviation => "bps",
MaxDefault => $MaxDefault,
TopNTypeID => $TopNType,
TopNScopeID => $TypNScope,
Create => 1
});
if (!$MetricTypeID) {
$Log->Message('ERROR', "Error Finding Metric Type");
}
FindMetricSeries
Finds metric series by metric ID.
FindMetricSeries(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
MetricID - The ID of the metric to find the series for.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. MetricSeriesKey (String: Measurement | DeviceHost | InstanceName | DeviceZoneID | CachedTime)
Synopsis
my ($ErrorFlag, $Message, $MetricSeriesKey) = FindMetricSeries({
DBH => \$DBH,
StorageHash => $StorageHash,
MetricID => $MetricID
});
if (!$MetricSeriesKey) {
$Log->Message('ERROR', "Error Finding Metric Series: $Message");
}
OR
my $MetricSeriesKey = FindMetricSeries({
DBH => \$DBH,
StorageHash => $StorageHash,
MetricID => $MetricID
});
if (!$MetricSeriesKey) {
$Log->Message('ERROR', "Error Finding Metric Series");
}
FindMetricMax
Finds the metric Max by metric ID.
FindMetricMax(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
MetricID - The ID of the metric to find the Max for.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Metric ID (Integer)
Synopsis
my ($ErrorFlag, $Message, $MetricMax) = FindMetricMax({
DBH => \$DBH,
StorageHash => $StorageHash,
MetricID => $MetricID
});
if (!$MetricMax) {
$Log->Message('ERROR', "Error Finding Metric Max: $Message");
}
OR
my $MetricMax = FindMetricMax({
DBH => \$DBH,
StorageHash => $StorageHash,
MetricID => $MetricID
});
if (!$MetricMax) {
$Log->Message('ERROR', "Error Finding Metric Max");
}
FindShardID
Finds the shard ID for a device.
FindShardID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash) stores in $StorageHash->{'DeviceShard'} OR $StorageHash->{'MetricShard'} based on lookup option used
DeviceID - The ID of the device to find the shard for.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. ShardID (Integer) or undef if error
Synopsis
my $ShardID = FindShardID({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceID => $DeviceID
});
if (!$ShardID) {
$Log->Message('ERROR', "Error Finding ShardID for DeviceID=$DeviceID");
}
FindDeviceIDFromMetricID
Finds a device ID for a metric ID.
FindDeviceIDFromMetricID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
MetricID - The ID of the metric to find the device for.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. DeviceID (Integer) or undef if error
Synopsis
my ($ErrorFlag, $Msg, $DeviceID) = FindDeviceIDFromMetricID({
DBH => \$DBH,
StorageHash => $StorageHash,
MetricID => $MetricID
});
if (!$DeviceID) {
$Log->Message('ERROR', "Error Finding DeviceID for MetricID=$MetricID: $Msg");
}
FindThresholdID
Finds a threshold and returns its ID. If the Create option is set to true (1), and no threshold with the specified name exists, it will be automatically created.
FindThresholdID(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
Name - The name of the threshold to find or create.
Create - (Optional) Set to 1 to create the threshold if it does not exist, set to 0 otherwise.
Message - Notification message
Measurement - Measurement
ThresholdTypeID - Threshold Type:
Used by Standard Threshold Engine:
1: Standard
Used by Trend Threshold Engine:
10: Trend %
20: Trend Prediction
Used by Abnormal Threshold Engine:
14: Abnormal
Used by Missing Data Threshold Engine:
16: Missing Data
MetricField - InfluxDB field name:
- availability
- utilization
- value
TimeRange - (Except Abnormal Thresholds) The period of time where data points will be retrieved and evaluated.
Relative time (s, m, h, d)
Frequency - (Standard Thresholds only) How often the threshold is being checked by the threshold engine.
Relative time (s, m, h, d)
Offset - (Standard Thresholds only) The offset for the threshold engine to apply to TimeRange.
Relative time (s, m, h, d)
Function - (Standard Thresholds only) What function to apply when calculating if a threshold is breached.
ThresholdFunctionID:
1: Mean (default)
2: Minimum
3: Maximum
4: Standard Deviation
5: 95th Percentile
6: Count
StatusID - Status
0: Disabled
1: Enabled
WarningOperator - (Except for Abnormal Thresholds) The warning operator:
0: Equal to (=)
1: Greater than (>)
2: Greater than or equal to (>=)
3: Less than (<)
4: Less than or equal to (<=)
5: Not equal to (!=)
WarningValue - (Except for Abnormal Thresholds) The warning value
WarningSeverity - The warning severity
CriticalOperator - (Except for Abnormal Thresholds) The critical operator:
0: Equal to (=)
1: Greater than (>)
2: Greater than or equal to (>=)
3: Less than (<)
4: Less than or equal to (<=)
5: Not equal to (!=)
CriticalValue - (Except for Abnormal Thresholds) The critical value
CriticalSeverity - (Except for Abnormal Thresholds) The critical severity
ForecastTimeRange - (Trend Prediction only) The relative time (h, d ,w, m)
AbnormalProfileID - (Abnormal Profiles only) The Abnormal Profile
CheckLocation - (Standard Thresholds only) The location of threshold checking:
1: Threshold Engine (default)
2: Application
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Threshold ID (Integer) or undef if not found/created
Synopsis
my ($ErrorFlag, $Message, $ThresholdID) = FindThresholdID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Threshold",
Create => 1,
StatusID => 1,
TimeRange => '15m',
Frequency => '5m',
Offset => '0m',
Function => 1,
Message => $Message,
Measurement => $Measurement,
ThresholdTypeID => 1,
WarningOperator => '',
WarningValue => '',
WarningSeverity => '',
CriticalOperator => '==',
CriticalValue => 0,
CriticalSeverity => 3,
ForecastTimeRange => '15m',
AbnormalProfileID => 0,
CheckLocation => 1
});
if (!$ThresholdID) {
$Log->Message('ERROR', "Error Finding Threshold: $Message");
}
OR
my $ThresholdID = FindThresholdID({
DBH => \$DBH,
StorageHash => $StorageHash,
Name => "My Threshold",
Create => 1,
StatusID => 1,
TimeRange => '15m',
Frequency => '5m',
Offset => '0m',
Function => 1,
Message => $Message,
Measurement => $Measurement,
ThresholdTypeID => 1,
WarningOperator => '',
WarningValue => '',
WarningSeverity => '',
CriticalOperator => '==',
CriticalValue => 0,
CriticalSeverity => 3,
ForecastTimeRange => '15m',
AbnormalProfileID => 0,
CheckLocation => 1
});
if (!$ThresholdID) {
$Log->Message('ERROR', "Error Finding Threshold");
}
ProcessCounter
Interpolates a counter value. Returns the difference between previous and current values.
ProcessCounter(\%options)
Options
StorageHash - Cache (for example, $StorageHash)
MetricID - Metric
CurrentValue - Current value
SNMPIndex - OID Index
Returns
1. Counter Difference
Synopsis
my $Value = ProcessCounter({
StorageHash => $StorageHash,
MetricID => $MetricID,
CurrentValue => $Value,
SNMPIndex => $Index
});
SanitizeInfluxTag
A helper function that replaces combinations of \ and \, or trailing \ with an underscore in Influx tag values.
SanitizeInfluxTag($Tag)
**Arguments**
```
TagValue - The Influx tag value to run the function on.
```
**Returns**
```
1. Sanitized Influx tag value
```
Synopsis
my $SanitizedTagValue = SanitizeInfluxTag($TagValue);
SanitizeInfluxMeasurement
A helper function that replaces spaces and commas with an underscore in an Influx Measurement.
SanitizeInfluxMeasurement($Measurement)
**Arguments**
```
Measurement - The Influx measurement to run the function on.
```
**Returns**
```
1. Sanitized Influx measurement
```
Synopsis
my $SanitizedMeasurement = SanitizeInfluxMeasurement($Measurement);
UpdateDisplayInstance
Updates the display instance name.
UpdateDisplayInstance(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
DeviceID - Device
InstanceID - Metric Instance
CustomName - Display Name
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateDisplayInstance({
DBH => \$DBH,
DeviceID => $DeviceID,
InstanceID => $InstanceID,
CustomName => $CustomName
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Error Updating Display Instance: $Message");
}
UpdateMethodOnMetric
Updates metric configuration.
UpdateMethodOnMetric(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
MetricID - Metric
MethodID - Method:
0 = NA
1 = SNMP
2 = WMI
3 = Other
5 = Transaction
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateMethodOnMetric({
DBH => \$DBH,
MetricID => $MetricID,
MethodID => $MethodID
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Error Setting Method: $Message");
}
UpdateMetricMaximum
Updates the metric configuration maximum.
UpdateMetricMaximum(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
MetricID - Metric
Maximum - New Maximum
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateMetricMaximum({
DBH => \$DBH,
MetricID => $MetricID,
Maximum => $Max
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Error Setting Maximum: $Message");
}
UpdateMetricCustomMaximum
Updates the metric configuration custom maximum (overrides gathered maximum).
UpdateMetricCustomMaximum(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
MetricID - The metric to update.
Maximum - The new maximum.
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateMetricCustomMaximum({
DBH => \$DBH,
MetricID => $MetricID,
Maximum => $Max
});
if ($ErrorFlag) {
$Log->Message('ERROR', "Error Setting Maximum: $Message");
}
FindMetricFromSeries
Finds a metric ID by metric series.
FindMetricFromSeries(\%options)
Options
DBH - The Assure1 database handle reference (for example, \$DBH)
StorageHash - Cache (for example, $StorageHash)
DeviceHost - Device
InstanceName - Instance
Measurement - Measurement
DeviceZoneID - Device zone
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. MetricID (Integer) or undef if not created
Synopsis
my ($ErrorFlag, $Message, $MetricID) = FindMetricFromSeries({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceHost => $DeviceHost
InstanceName => $InstanceName
Measurement => $Measurement
DeviceZoneID => $DeviceZoneID
});
if (!$MetricID) {
$Log->Message('ERROR', "Error Finding MetricID: $Message");
}
OR
my $MetricID = FindMetricFromSeries({
DBH => \$DBH,
StorageHash => $StorageHash,
DeviceHost => $DeviceHost
InstanceName => $InstanceName
Measurement => $Measurement
DeviceZoneID => $DeviceZoneID
});
if (!$MetricID) {
$Log->Message('ERROR', "Error Finding MetricID");
}