Table of Contents
Table of Contents |
---|
Creating an opEvents Object inside a parser plugin
This example shows how we can create the opEvents object for use inside a parser plugin.
If you have opEvents installed in another location dir=> "/usr/local/omk/conf" will need to change to reflect the full path of your conf directory
Code Block | ||||
---|---|---|---|---|
| ||||
package Event_State_Example;
our $VERSION="0.0.0";
use lib "/usr/local/omk/lib";
use strict;
use OMK::Common;
use OMK::opEvents;
use OMK::Log;
# arguments: the line (currently being parsed),
# and reference to the live event properties
# returns: (status-or-error)
#
# zero or undef: parsing for this event is aborted,
# and no event is created.
# 1: indicates success, event is created and changed event
# properties are incorporated.
# any other value: treated as error message, changed event
# properties are NOT incorporated but event parsing continues.
sub parse_enrich
{
my ($line, $event) = @_;
my $confCommon = loadOmkConfTable(conf=> "opCommon", dir=> "/usr/local/omk/conf");
my $logger = OMK::Log->new(level => $confCommon->{"omkd_log_level"} || 'info',
path => $confCommon->{'<omk_logs>'}."/opEvents.log");
my $OPE = OMK::opEvents->new(config => $confCommon,
logprefix => "Plugin::Event_State_Example",
log => $logger);
$OPE->getDb();
$event->{Plugin_Used} = "Event_State_Example";
return 1;
}
|
getEventLogsModel
# args: at least log_name (=db collection, log_name can be: events, rawLogs, logArchive, or actionlog)
# and time_start/end AND/OR a set of any
# of id, node_uuid or node_name,
# type/element/details/action/archive/entry/acknowledged/escalate/priority/event_id
# to select events
#
# arg sort: mongo sort criteria
# arg limit: return only N records at the most
# arg skip: skip N records at the beginning. index N in the result set is at 0 in the response
# arg paginate: sets the pagination mode, in which case the result array is fudged up sparsely to
# return 'complete' result elements without limit! - a dummy element is inserted at the 'complete' end,
# but only 0..limit are populated
In this example we are getting an event by its ID
getEventLogsModel will always return an array and should be expected to not have any values
Code Block | ||
---|---|---|
| ||
my $modelData = $OPE->getEventLogsModel(log_name => "events", id => '60516246c6c2b17094225a9c');
my $otherEvent = $modelData->[0];
#Lets set a new property on our newly parsed event to the nodes_uuid of a unrelated event.
$event->{other_event_nodeuuid} = $otherEvent->{node_uuid}; |
Sample data from the event with id 60516246c6c2b17094225a9c
Code Block | ||
---|---|---|
| ||
{"_id":{"$oid":"60516246c6c2b17094225a9c"},"acknowledged":0,"action_checked":1,"actions":[{"action":"tag","comment":"set to FALSE","date":"2021-03-18T10:49:59","details":"outageCurrent","event":"SNMP Down","node_uuid":"3f49619e-b8ae-4e96-b56a-a7331baf71d3","time":1616028599}],"count":1,"date":"2021-03-18T10:48:28","delayedaction":1616028598,"details":"get SNMP Service Data: No response from remote host \"13.56.2.146\"","element":"","escalate":null,"event":"SNMP Down","friendly_acknowledged":0,"friendly_element":"","friendly_escalate":"","host":"demo.opmantek.com","lastupdate":1616028599,"level":"Major","node":"demo.opmantek.com","node_uuid":"3f49619e-b8ae-4e96-b56a-a7331baf71d3","nodeinfo":{"configuration_group":"DataCentre","configuration_location":"test"},"priority":6,"state":"down","stateful":"SNMP","status_history":[[1616028509.42444,null,"received",null],[1616028599.84117,null,"action_processing","complete"]],"tag_outageCurrent":"FALSE","time":1616028508,"type":"nmis_eventlog"} |
Multiple events
getEventLogsModel needs time_start and time_end if you are searching for events not by id, this is for safety and performance .
In this example we are looking for events with the name 'My_Monkey_Event' which have not been acknowledged and from the last 24 hours. These arguments are compounded into a AND query, some arguments are faster to find that others depending on indexes. If the query takes too long opEvents action parser might kill the script before anything is returned.
Code Block | ||
---|---|---|
| ||
my $toBeAcknowledged = $OPE->getEventLogsModel(log_name => "events", event => 'My_Monkey_Event', acknowledged => 0, time_start=> time - 86400, time_end => time);
foreach my $e (@{$toBeAcknowledged}){
} |
Full list of arguments to search by
Code Block | ||
---|---|---|
| ||
'_id' => $arg{id},
'time' => { '$gte' => $time_start, '$lt' => $time_end },
'event' => $arg{event},
'node_uuid' => $arg{node_uuid},
'type' => $arg{type},
'element' => $arg{element},
'details' => $arg{details},
'eventid' => $arg{event_id}, # only useful in actionlog
'action' => $arg{action}, # only useful in actionlog
'archive' => $arg{archive}, # only useful in archive log
'entry' => $arg{entry}, # only in raw log
'state' => $arg{state},
'nodeinfo.configuration.location' => {'$regex' => $arg{'nodeinfo.configuration_location'} || $arg{location}},
'nodeinfo.configuration.group' => {'$regex' => $arg{'nodeinfo.configuration_group'} || $arg{group}},
'acknowledged' => numify($arg{acknowledged}),
'escalate' => numify($arg{escalate}),
'priority' => numify($arg{priority}), }); |
Updating Events
# updates an event with the given details
# args: _id (for finding the event), _constraints (to disable db key munging),
# everyting else is set as record content, as-is - except "status_history", "trigger_eventids"
#
# Table of Contents
Table of Contents |
---|
Creating an opEvents Object inside a parser plugin
opEvents Object is the object core to process and parse all the events.
This example shows how we can create the opEvents object for use inside a parser plugin.
If you have opEvents installed in another location dir=> "/usr/local/omk/conf" will need to change to reflect the full path of your conf directory
Code Block | ||||
---|---|---|---|---|
| ||||
package Event_State_Example;
our $VERSION="0.0.0";
use lib "/usr/local/omk/lib";
use strict;
use OMK::Common;
use OMK::opEvents;
use OMK::Log;
# arguments: the line (currently being parsed),
# and reference to the live event properties
# returns: (status-or-error)
#
# zero or undef: parsing for this event is aborted,
# and no event is created.
# 1: indicates success, event is created and changed event
# properties are incorporated.
# any other value: treated as error message, changed event
# properties are NOT incorporated but event parsing continues.
sub parse_enrich
{
my ($line, $event) = @_;
my $confCommon = loadOmkConfTable(conf=> "opCommon", dir=> "/usr/local/omk/conf");
my $logger = OMK::Log->new(level => $confCommon->{"omkd_log_level"} || 'info',
path => $confCommon->{'<omk_logs>'}."/opEvents.log");
my $OPE = OMK::opEvents->new(config => $confCommon,
logprefix => "Plugin::Event_State_Example",
log => $logger);
$OPE->getDb();
$event->{Plugin_Used} = "Event_State_Example";
return 1;
}
|
Getting events: getEventLogsModel
We can get a list of events using getEventLogsModel. This method takes the following arguments:
- log_name (=db collection, log_name can be: events, rawLogs, logArchive, or actionlog)
- time_start/end and/or a set of any of id, node_uuid or node_name type/element/details/action/archive/entry/acknowledged/escalate/priority/event_id to select events
Optional arguments:
- sort: mongo sort criteria
- limit: Return only N records at the most
- skip: skip N records at the beginning. Index N in the result set is at 0 in the response.
- paginate: sets the pagination mode, in which case the result array is fudged up sparsely to return 'complete' result elements without limit! - a dummy element is inserted at the 'complete' end, but only 0..limit are populated
getEventLogsModel will always return an array and should be expected to not have any values
In this example we are getting an event by its ID:
Code Block | ||
---|---|---|
| ||
my $modelData = $OPE->getEventLogsModel(log_name => "events", id => '60516246c6c2b17094225a9c');
my $otherEvent = $modelData->[0];
#Lets set a new property on our newly parsed event to the nodes_uuid of a unrelated event.
$event->{other_event_nodeuuid} = $otherEvent->{node_uuid}; |
Sample data from the event with id 60516246c6c2b17094225a9c
Code Block | ||
---|---|---|
| ||
{"_id":{"$oid":"60516246c6c2b17094225a9c"},"acknowledged":0,"action_checked":1,"actions":[{"action":"tag","comment":"set to FALSE","date":"2021-03-18T10:49:59","details":"outageCurrent","event":"SNMP Down","node_uuid":"3f49619e-b8ae-4e96-b56a-a7331baf71d3","time":1616028599}],"count":1,"date":"2021-03-18T10:48:28","delayedaction":1616028598,"details":"get SNMP Service Data: No response from remote host \"13.56.2.146\"","element":"","escalate":null,"event":"SNMP Down","friendly_acknowledged":0,"friendly_element":"","friendly_escalate":"","host":"demo.opmantek.com","lastupdate":1616028599,"level":"Major","node":"demo.opmantek.com","node_uuid":"3f49619e-b8ae-4e96-b56a-a7331baf71d3","nodeinfo":{"configuration_group":"DataCentre","configuration_location":"test"},"priority":6,"state":"down","stateful":"SNMP","status_history":[[1616028509.42444,null,"received",null],[1616028599.84117,null,"action_processing","complete"]],"tag_outageCurrent":"FALSE","time":1616028508,"type":"nmis_eventlog"} |
Getting multiple events
getEventLogsModel needs time_start and time_end if you are searching for events not by id, this is for safety and performance .
In this example we are looking for events with the name 'My_Monkey_Event' which have not been acknowledged and from the last 24 hours. These arguments are compounded into a AND query, some arguments are faster to find that others depending on indexes. If the query takes too long opEvents action parser might kill the script before anything is returned.
Code Block | ||
---|---|---|
| ||
my $toBeAcknowledged = $OPE->getEventLogsModel(log_name => "events", event => 'My_Monkey_Event', acknowledged => 0, time_start=> time - 86400, time_end => time);
foreach my $e (@{$toBeAcknowledged}){
} |
Full list of arguments to search by
Code Block | ||
---|---|---|
| ||
'_id' => $arg{id},
'time' => { '$gte' => $time_start, '$lt' => $time_end },
'event' => $arg{event},
'node_uuid' => $arg{node_uuid},
'type' => $arg{type},
'element' => $arg{element},
'details' => $arg{details},
'eventid' => $arg{event_id}, # only useful in actionlog
'action' => $arg{action}, # only useful in actionlog
'archive' => $arg{archive}, # only useful in archive log
'entry' => $arg{entry}, # only in raw log
'state' => $arg{state},
'nodeinfo.configuration.location' => {'$regex' => $arg{'nodeinfo.configuration_location'} || $arg{location}},
'nodeinfo.configuration.group' => {'$regex' => $arg{'nodeinfo.configuration_group'} || $arg{group}},
'acknowledged' => numify($arg{acknowledged}),
'escalate' => numify($arg{escalate}),
'priority' => numify($arg{priority}), }); |
Creating Events
opEvents object provides an easy way to create an event:
Code Block |
---|
# Tell opEvents object to create the event
my ($error, $eventid) = $OPE->createEvent(event => $event); |
It will return an error in case the event hasn't been created, or the eventId otherwise.
We first need to create the event. This is an example:
Code Block |
---|
# Create Event Object
my $event = {};
my @maybeprops = grep($_ !~ /^(act|debug|quiet|conf|confdir|baseurl|username|password)$/, keys %$Q);
if (@maybeprops)
{
my @rawinputs;
for my $key (@maybeprops)
{
next if ($Q->{$key} eq ''); # supress empty properties
die "argument $key cannt be set multiple times!\n" if (ref($Q->{$key}) eq "ARRAY");
# ensure numeric values for anything numeric, or mongo comparison ops will
# fail badly (especially true for time, which breaks the gui)
$event->{$key} = numify($Q->{$key});
push @rawinputs, "'$key=$Q->{$key}'";
}
$event->{entry} = join(" ", @rawinputs);
} |
Updating Events
opEvents object also provides an easy way to update an event. We will need to pass the following arguments:
- _id: for identify the event to be updated
- _constraints: to disable db key munging
Everything else will be recorded as content, as-is, except "status_history" and "trigger_eventids":
- status_history: optional but special: must be array and this array will be
...
- ADDED to an existing status_history array.
- trigger_eventids: always saved as array, and a new value is ADDED.
- buttons: always saved as array, and a new value is ADDED.
returns undef if ok, error message otherwise (also logged)
As an example:
Code Block |
---|
my $failure = $OPE->updateEvent( "_id" => $e->{_id},
priority => 5,
status_history => [ $now, $thisuser, "priority", 5 ], ); |
Acknowledging an event
We can acknowledge an event by setting acknowledged => 1, and give it status history so we know who and when triggered the event to be acknowledged
...
Code Block | ||
---|---|---|
| ||
package Event_State_Example; our $VERSION="0.0.0"; use lib "/usr/local/omk/lib"; use strict; #use func; use OMK::Common; use Data::Dumper; use OMK::opEvents; use OMK::Log; # arguments: the line (currently being parsed), # and reference to the live event properties # returns: (status-or-error) # # zero or undef: parsing for this event is aborted, # and no event is created. # 1: indicates success, event is created and changed event # properties are incorporated. # any other value: treated as error message, changed event # properties are NOT incorporated but event parsing continues. sub parse_enrich { my ($line, $event) = @_; my $confCommon = loadOmkConfTable(conf=> "opCommon", dir=> "/usr/local/omk/conf"); my $logger = OMK::Log->new(level => $confCommon->{"omkd_log_level"} || 'info', path => $confCommon->{'<omk_logs>'}."/opEvents.log"); my $OPE = OMK::opEvents->new(config => $confCommon, logprefix => "Plugin::Event_State_Example", log => $logger); $OPE->getDb(); #We can get an event with an id my $modelData = $OPE->getEventLogsModel(log_name => "events", id => '60516246c6c2b17094225a9c'); my $otherEvent = $modelData->[0]; $event->{other_event_ack} = []; my $thisuser = "Plugin::Event_State_Example"; #lets get an event by name and mark them acknowledged #you must pass time start and end if we are looking for events and not and event by an id #lets ack them foreach my $e (@{$toBeAcknowledged}){ my $now = time; my $failure = $OPE->updateEvent( "_id" => $e->{_id}, acknowledged => 1, status_history => [ $now, $thisuser, "acknowledged", 1 ], ); push @{$event->{other_event_ack}}, $e->{_id}->to_string; #TODO better error handling return if($failure); } $event->{Plugin_Used} = "Event_State_Example"; $event->{node} = "fulla-localhost"; $event->{host} = "127.0.0.1"; $event->{other_event} = $otherEvent->{_id}->to_string; return 1; } |
Lookup node by node name
The first option, Build up a search hash and pass this to getEventLogsModel
Code Block |
---|
my $search = { node => "MYNODENAME" }; $OPE->getEventLogsModel(event => "SNMP Down", search => $search |
...
After checking the logs you would then send an up event.
Process is.:
- Edit plugin.
- Restart daemon
- Send “down” event.
- Check opEvents log
- Send “up” event.
- Check opEvents log
- Repeat as needed.
...