Events
Description
Implements the functions for Event rules.
Synopsis
use Assure1::Events;
AddJournal
Insert a new journal entry for a given EventID in the real-time events database.
AddJournal(\%options)
Options
DBH -> Events Database Handle reference (i.e. \$EventDBH)
EventID -> Event EventID to update
Username -> Unified Assurance username
TimeStamp -> epoch time stamp of when the journal was created
Entry -> Journal Message (no size limitations)
ShardID -> (Optional) ShardID of Events (default: 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. New Journal Entry ID (Integer) - undef on error
Synopsis
my ($ErrorFlag, $Message) = AddJournal({
DBH => \$EventDBH,
EventID => '1',
TimeStamp => time(),
Username => 'admin',
Entry => 'New Entry',
ShardID => 1
});
AddVisionData
Adds information required to display event in Vision
AddVisionData(\%options)
Options
Event -> Event reference (i.e. $Event)
Type -> (Optional) Vision type, can be `dDevice`, `dLink`, `pLink` or `point`. Defaults to `dDevice`.
StartName -> (Optional) Vision Entity to associate event with (defaults to $Event->{Node} (required where Vision type is `pLink` and should be set to start device for link)
EndName -> (Optional) Vision Entity to associate with end of link (required where Vision type is `pLink`)
LinkNode -> (Optional) Unified Assurance Node name for pLink events. Generally not a device but reference to a link between devices, defaults to $Event->{Node} (required where Vision type is `pLink`)
Interface -> (Optional) Unified Assurance Instance name for Interface on start device for link events (required where Vision type is `dLink`)
Layer -> (Optional) Vision layer the event will be added to. For `dDevice`, `dLink` and `point` events defaults to `unknown`,
required where Vision type is `pLink`.
Source -> (Optional) Vision source ID representing this system (defaults to 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($Error, $Message) = AddVisionData({
Event => $Event,
Type => 'point',
StartName => $Event->{Node},
Layer => 'Switch',
Source => 1
});
ConvertAlarmToEventFields
Converts Assure1v4 Alarm structure fields to Unified Assurance Event structure fields for rules.
ConvertAlarmToEventFields($Event)
Arguments
Event -> The structure which necessitates field conversion
Returns
Event -> Structure with all fields converted
Synopsis
my $Event = ConvertAlarmToEventFields($Event);
CreateEvent
Create a Meta Event in the real-time events database using a Meta Event ID.
CreateEvent(\%options)
Options
EventDBH -> Events Database Handle reference (i.e. $EventDBH)
Assure1DBH -> Assure1 Database Handle reference(i.e. $Assure1DBH)
EventID -> Meta Event ID
Values -> Name/Value Pairs to map to Meta Event Template
ShardID -> (Optional) Event Database ShardID to send event data (defaults to 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = CreateEvent({
EventDBH => \$EventDBH,
Assure1DBH => \$Assure1DBH,
EventID => 1, # Generic Service Event
Values => {
SERVICENAME => 'Critical Test',
EventID => '1',
SERVICEID => '1',
STATE => '1',
TIMESTAMP => time()
},
ShardID => 1
});
CreateSLMFilter
Creates SLM Event Filter and returns the new ID.
CreateSLMFilter(\%options)
Options
DBH -> Assure1 Database Handle Reference (i.e. \$DBH)
FilterName -> SLM Filter Name
CompareField -> Event Field to compare (exact name)
CompareMetric -> Metric to perform on Event Field:
1 = COUNT
2 = SUM
3 = MIN
4 = MAX
5 = AVG
CompareOperator -> Threshold compare:
0 = '='
1 = '>'
2 = '>='
3 = '<'
4 = '<='
5 = '!='
CompareValue -> Threshold Value (float)
Weight -> Weight to give threshold
WhereClause -> SQL to filter events for CompareMetric
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. SLM Filter ID (Integer) or undef if not created
Synopsis
my ($ErrorFlag, $Message, $SLMFilterID) = CreateSLMFilter({
DBH => \$DBH,
FilterName => "My SLM Filter",
CompareField => 'EventID',
CompareMetric => 1,
CompareOperator => 1,
CompareValue => 0,
Weight => 1,
WhereClause => 'Severity = 5'
});
if (!$SLMFilterID) {
$Log->Message('ERROR', "Error Creating SLM Filter: $Message");
}
OR
my $SLMFilterID = CreateSLMFilter({
DBH => \$DBH,
FilterName => "My SLM Filter",
CompareField => 'EventID',
CompareMetric => 1,
CompareOperator => 1,
CompareValue => 0,
Weight => 1,
WhereClause => 'Severity = 5'
});
if (!$SLMFilterID) {
$Log->Message('ERROR', "Error Creating SLM Filter");
}
DeleteEvent
Delete an event by EventID in the real-time events database.
DeleteEvent(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to delete
ShardID -> (Optional) ShardID of Event (defaults to 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = DeleteEvent({
DBH => \$EventDBH,
EventID => 1,
ShardID => 1
});
FindEventID
Retrieve all the EventIDs given a filter. Note: Does not support shards; use FindEventIDByShard instead
FindEventID(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
Filter -> Filter of which event EventIDs you want retrieved
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Array of EventIDs (Ref) - undef on error
Synopsis
my ($ErrorFlag, $Message, $EventRef) = FindEventID({
DBH => \$EventDBH,
Filter => $Filter
});
if (!$EventRef) {
$Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]: $Message");
}
OR
my $EventRef = FindEventID({
DBH => \$EventDBH,
Filter => $Filter
});
if (!$EventRef) {
$Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]");
}
FindEventIDByShard
Retrieve all the EventIDs and their associated shard given a filter.
FindEventIDByShard(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
Filter -> Filter of which event EventIDs you want retrieved
ShardID -> (Optional) search only the specified ShardID for results (defaults to 0: all shards)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Array of hashes containing EventID and ShardID (Ref) - undef on error
Synopsis
my ($ErrorFlag, $Message, $EventRef) = FindEventIDByShard({
DBH => \$EventDBH,
Filter => $Filter,
ShardID => 1
});
if (!$EventRef) {
$Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]: $Message");
}
OR
my $EventRef = FindEventIDByShard({
DBH => \$EventDBH,
Filter => $Filter,
ShardID => 1
});
if (!$EventRef) {
$Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]");
}
GetEventField
Retrieve a single field value given the EventID.
GetEventField(\%options)
Options
DBH -> Events Database Handle Reference (i.e. $EventDBH)
EventID -> EventID of the Event you wish to retrieve
Field -> Field Name of the Event column you wish to retrieve (i.e. Node)
ShardID -> (Optional) ShardID of Event (default: 1, 0 for all)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Field Value - undef on error
Synopsis
my ($ErrorFlag, $Message, $EventHash) = GetEventField({
DBH => \$EventDBH,
EventID => $EventID,
Field => $FieldName,
ShardID => 1
});
if (!$EventHash) {
$Log->Message('ERROR', "Error retrieving Event Field [$EventID:$FieldName]: $Message");
}
OR
my $EventHash = GetEventField({
DBH => \$EventDBH,
EventID => $EventID,
Field => $FieldName,
ShardID => 1
});
if (!$EventHash) {
$Log->Message('ERROR', "Error retrieving Event Field [$EventID:$FieldName]");
}
GetEventHash
Retrieve all the fields in a name/value hash given the EventID.
GetEventHash(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> EventID of the Event you wish to retrieve
ShardID -> (Optional) ShardID of Event (default: 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Hash of Event in FieldName => Field Value pairings - undef on error
Synopsis
my ($ErrorFlag, $Message, $EventHash) = GetEventHash({
DBH => \$EventDBH,
EventID => $EventID,
ShardID => 1
});
if (!$EventHash) {
$Log->Message('ERROR', "Error retrieving EventHash [$EventID]: $Message");
}
OR
my $EventHash = GetEventHash({
DBH => \$EventDBH,
EventID => $EventID,
ShardID => 1
});
if (!$EventHash) {
$Log->Message('ERROR', "Error retrieving EventHash [$EventID]");
}
GetEventMetric
Retrieve event metric value given a metric operator & filter search criteria.
GetEventMetric(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
Metric -> Metric Operator (i.e. "count(*)" or "avg(Severity)")
Filter -> Filter Clause (i.e. "Severity > 0")
ShardID -> (Optional) search only the specified ShardID for results (defaults to 0: all shards)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Value (Number) - undef on error
Synopsis
my ($ErrorFlag, $Message, $Value) = GetEventMetric({
DBH => \$EventDBH,
Metric => $Metric,
Filter => $Filter,
ShardID => 1
});
if (!$Value) {
$Log->Message('ERROR', "Error retrieving EventMetric [$Metric : $Filter]: $Message");
}
OR
my $Value = GetEventMetric({
DBH => \$EventDBH,
Metric => $Metric,
Filter => $Filter,
ShardID => 1
});
if (!$Value) {
$Log->Message('ERROR', "Error retrieving EventMetric [$Metric : $Filter]");
}
GetJournals
Retrieve a list of journal entries for a given EventID in the real-time events database.
GetJournals(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to update
ShardID -> (Optional) ShardID of Event (default: 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
3. Journals (Array)
Synopsis
my ($ErrorFlag, $Message, @JournalsArray) = GetJournals({
DBH => $EventDBH,
EventID => 1,
ShardID => 1
});
StoreValue
Set or Retrieve a name/value pair in the Storage Hash.
StoreValue(\%options)
Options
Store -> Thread Safe Custom Hash reference to share/save data
Name -> Value Reference Name (required)
Value -> Value of Reference Name (required to Set)
Returns
1. Value
Synopsis
# Set
StoreValue({
Store => $StorageHash,
Name => '123',
Value => 'Test Data'
});
# Get
my $Value = StoreValue({
Store => $StorageHash,
Name => '123'
});
UpdateEvent
Update a field set given an EventID in the real-time events database.
UpdateEvent(\%options)
Options
DBH -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to update
Values -> Field Name/Value Pairs to update in the event (all other field will be untouched)
ShardID -> (Optional) ShardID of Event (defaults to 1)
Returns
1. ErrorFlag (0 Good, 1 Bad)
2. Message (String)
Synopsis
my ($ErrorFlag, $Message) = UpdateEvent({
DBH => \$EventDBH,
EventID => 1,
ShardID => 1,
Values => {
Node => 'localhost',
Summary => 'New Status'
}
});