NMISNG Events

Overview

The NMIS event system consists of two main components:

NMISNG::Events - High-level event management operations
NMISNG::Event - Individual event object operations

Events track network issues like nodes down, interfaces down, threshold violations, and custom alerts. Version: 1.0.0 (Events), 9.6.5 (Event) Location: lib/NMISNG/Events.pm and lib/NMISNG/Event.pm

NMISNG::Events

The Events manager provides high-level operations for event management.

Constructor

use NMISNG::Events;

# Usually accessed via $nmisng->events()
my $events = $nmisng->events();

Event Operations

eventAdd()

Add a new event or update an existing stateless event.

node

NMISNG::Node

required

Node object

event

string

required

Event name (e.g., “Node Down”, “Interface Down”)

level

string

required

Event level: Normal, Warning, Minor, Major, Critical, Fatal

element

string

Event element (e.g., interface name)

details

string

Event details/description

stateless

boolean

default:"0"

Whether event is stateless (resets after dampening time)

context

hash

Additional context information

my $error = $nmisng->events->eventAdd(
    node => $node,
    event => "Interface Down",
    level => "Major",
    element => "GigabitEthernet0/0",
    details => "Interface operationally down for 5 minutes"
);

if ($error) {
    print "Failed to add event: $error\n";
}

error

string

Returns undef on success, error message on failure

eventExist()

Check if an event exists and is active.

node

NMISNG::Node

required

Node object

event

string

required

Event name

element

string

Event element (optional)

if ($nmisng->events->eventExist($node, "Node Down")) {
    print "Node is down\n";
}

if ($nmisng->events->eventExist($node, "Interface Down", "eth0")) {
    print "Interface eth0 is down\n";
}

exists

boolean

Returns 1 if event exists and is active, 0 otherwise

Only considers events that are both active (active=1) and non-historic (historic=0).

eventLoad()

Load detailed information for an event.

node_uuid

string

required

Node UUID

event

string

required

Event name

element

string

Event element

active

boolean

Filter by active status (0 or 1)

historic

boolean

default:"0"

Filter by historic status

my ($error, $event) = $nmisng->events->eventLoad(
    node_uuid => $node->uuid,
    event => "Node Down",
    element => ""
);

if (!$error && $event) {
    print "Event level: " . $event->level . "\n";
    print "Started: " . localtime($event->startdate) . "\n";
    print "Details: " . $event->details . "\n";
}

result

tuple

Returns (error, event_object)

eventUpdate()

Update an existing event or create if missing.

event

hash

required

Event data hash

create_if_missing

boolean

default:"0"

Create event if it doesn’t exist

my $error = $nmisng->events->eventUpdate(
    event => {
        node_uuid => $node->uuid,
        event => "Node Down",
        element => "",
        details => "Updated: Node still not responding",
        escalate => 1
    }
);

error

string

Returns undef on success, error message on failure

eventDelete()

Delete an event.

event

hash

required

Event identification hash

my $error = $nmisng->events->eventDelete(
    event => {
        node_uuid => $node->uuid,
        event => "Node Down",
        element => ""
    }
);

error

string

Returns undef on success, error message on failure

If keep_event_history is enabled, marks event as historic instead of deleting.

Event Queries

get_events_model()

Query events with filtering.

filter

hash

Filter criteria

query

hash

Direct MongoDB query (overrides filter)

sort

hash

Sort criteria

limit

integer

Maximum records to return

skip

integer

Records to skip (pagination)

# Get all active events
my $events_model = $nmisng->events->get_events_model(
    filter => {
        historic => 0,
        active => 1
    },
    sort => {startdate => -1}
);

if (my $error = $events_model->error) {
    die "Failed: $error";
}

print "Active events: " . $events_model->count . "\n";
foreach my $event (@{$events_model->data}) {
    print "$event->{node_name}: $event->{event}";
    print " ($event->{element})" if $event->{element};
    print " - $event->{level}\n";
}

model

NMISNG::ModelData

ModelData object with event records

Common Filter Fields:

node_uuid (string) - Node UUID
event (string) - Event name
element (string) - Event element
level (string) - Event level
active (0/1) - Active status
historic (0/1) - Historic status
stateless (0/1) - Stateless event
ack (0/1) - Acknowledged status
escalate (integer) - Escalation level

Event Logging

logEvent()

Write event to event log file.

node_name

string

required

Node name

event

string

required

Event name

level

string

required

Event level

element

string

Event element

details

string

Event details

my $error = $nmisng->events->logEvent(
    node_name => $node->name,
    event => "Node Up",
    level => "Normal",
    element => "",
    details => "Node responding after 10 minutes down"
);

error

string

Returns undef on success, error message on failure

Utility Methods

cleanNodeEvents()

Remove all active events for a node.

node

NMISNG::Node

required

Node object

caller

string

Caller identifier for logging

my $error = $nmisng->events->cleanNodeEvents($node, "admin_cleanup");
if ($error) {
    print "Failed: $error\n";
}

error

string

Returns undef on success, error message on failure

Marks all events as inactive and historic. Logs closure if event had logging enabled.

NMISNG::Event Object

The Event object represents a single event instance.

Constructor

event()

Create event object (usually via node->event() or events->event()).

my $event = $node->event(
    event => "Interface Down",
    element => "GigabitEthernet0/0",
    level => "Major",
    details => "No response from interface"
);

Event Properties

Core Properties

All properties have getter/setter methods:

# Get properties
my $event_name = $event->event();
my $level = $event->level();
my $element = $event->element();
my $details = $event->details();
my $node_uuid = $event->node_uuid();
my $node_name = $event->node_name();

# Set properties
$event->level("Critical");
$event->details("Interface down for 30 minutes");
$event->ack(1);
$event->user("admin");

Available Properties:

event (string) - Event name
element (string) - Event element
level (string) - Event level
details (string) - Event details
node_uuid (string) - Node UUID
node_name (string) - Node name
cluster_id (string) - Cluster ID
active (0/1) - Active status
historic (0/1) - Historic status
stateless (0/1) - Stateless flag
ack (0/1) - Acknowledged
user (string) - User who acknowledged
escalate (integer) - Escalation level (-1 = not escalated)
notify (string) - Notification status
startdate (integer) - Start timestamp
lastupdate (integer) - Last update timestamp
context (hash) - Additional context
inventory_id (ObjectId) - Related inventory ID

Event Operations

save()

Save event to database.

update

boolean

default:"0"

Set to 1 when just updating (skips eventAdd logic)

my $error = $event->save();
if ($error) {
    print "Failed to save event: $error\n";
}

error

string

Returns undef on success, error message on failure

load()

Load event from database.

force

boolean

default:"0"

Force reload even if already loaded

only_take_missing

boolean

default:"0"

Only populate fields that don’t already have values

my $error = $event->load();
if ($error) {
    print "Failed to load: $error\n";
} elsif ($event->exists) {
    print "Event found: " . $event->level . "\n";
}

error

string

Returns undef on success, error message on failure

delete()

Delete event or mark as historic.

my $error = $event->delete();
if ($error) {
    print "Failed to delete: $error\n";
}

error

string

Returns undef on success, error message on failure

If keep_event_history is enabled, marks as historic with expire_at. Otherwise permanently deletes.

acknowledge()

Acknowledge or un-acknowledge an event.

ack

boolean

required

Acknowledge (1) or un-acknowledge (0)

user

string

required

Username performing acknowledgment

my $error = $event->acknowledge(
    ack => 1,
    user => "admin"
);

if ($error) {
    print "Failed to acknowledge: $error\n";
}

error

string

Returns undef on success, error message on failure

Only active (non-historic) events can be acknowledged. TRAP events are deleted when acknowledged.

check()

Check if event should be closed (thing came back up).

sys

NMISNG::Sys

required

Sys object for the node

details

string

Override event details

level

string

Override event level

upevent

string

Override up event name (otherwise heuristic is used)

value

number

Current value (for threshold events)

reset

number

Reset value (for threshold events)

# Check if node is back up
my $event = $node->event(
    event => "Node Down",
    element => ""
);

$event->check(sys => $S);
# If event exists and node is up, creates "Node Up" event

Automatically converts down events to up events (e.g., “Node Down” → “Node Up”, “Interface Down” → “Interface Up”). Includes dampening for threshold events.

Event Status Methods

exists()

Check if event exists in database.

if ($event->exists) {
    print "Event found in database\n";
}

exists

boolean

Returns 1 if exists, 0 otherwise

Ignores active status - finds event whether active or inactive.

is_new()

Check if event is new (not yet saved).

if ($event->is_new) {
    print "Event not yet saved\n";
}

is_new

boolean

Returns 1 if new, 0 if exists in database

is_alert()

Check if event is a custom alert.

if ($event->is_alert) {
    print "This is a custom alert\n";
}

is_alert

boolean

Returns 1 if event name contains “Alert:”, 0 otherwise

is_proactive()

Check if event is a proactive/threshold event.

if ($event->is_proactive) {
    print "This is a threshold violation\n";
}

is_proactive

boolean

Returns 1 if event name contains “Proactive”, 0 otherwise

Logging Methods

log()

Log event to event log file.

node_name

string

Override node name

event

string

Override event name

level

string

Override level

element

string

Override element

details

string

Override details

$event->log(); # Use event's own properties

# Or override specific fields
$event->log(
    details => "Custom log message",
    level => "Warning"
);

error

string

Returns undef on success, error message on failure

getLogLevel()

Get event log level from model configuration.

sys

NMISNG::Sys

required

Sys object

event

string

Event name (uses event’s own if not provided)

level

string

Current level (uses event’s own if not provided)

my ($level, $log, $syslog) = $event->getLogLevel(sys => $S);

print "Level: $level\n";
print "Log: $log\n";     # "true" or "false"
print "Syslog: $syslog\n"; # "true" or "false"

result

tuple

Returns (level, log_enabled, syslog_enabled)

Event Levels

NMIS uses the following event levels:

Normal - Normal operation, used for “up” events
Warning - Warning condition
Minor - Minor issue
Major - Major issue (most down events)
Critical - Critical issue
Fatal - Fatal/catastrophic issue

Common Event Names

Node Events

Node Down / Node Up
SNMP Down
WMI Down
Node Polling Failover
Backup Host Down

Interface Events

Interface Down / Interface Up
High Input Utilization
High Output Utilization
Input Errors
Output Errors

Threshold Events

Proactive Disk Space (and variations)
Proactive CPU
Proactive Memory
Custom proactive events

Custom Events

Alert: <custom name>
TRAP

Configuration

Event behavior is controlled by:

Events.nmis - Event configuration table
- Controls logging, notification, status inclusion per event
- Located in conf/Events.nmis
Model files - Event levels and policies
- Per node role/type event levels
- Located in models/ directory
Configuration settings
- keep_event_history - Keep events historic vs delete
- purge_event_after - Time before historic events expire
- stateless_event_dampening - Stateless event reset time (default 900s)
- syslog_events - Enable syslog logging
- events_strip_non_ascii_characters - Strip non-ASCII from logs

Core Libraries

CLI Commands

​Overview

​NMISNG::Events

​Constructor

​Event Operations

​eventAdd()

​eventExist()

​eventLoad()

​eventUpdate()

​eventDelete()

​Event Queries

​get_events_model()

​Event Logging

​logEvent()

​Utility Methods

​cleanNodeEvents()

​NMISNG::Event Object

​Constructor

​event()

​Event Properties

​Core Properties

​Event Operations

​save()

​load()

​delete()

​acknowledge()

​check()

​Event Status Methods

​exists()

​is_new()

​is_alert()

​is_proactive()

​Logging Methods

​log()

​getLogLevel()

​Event Levels

​Common Event Names

​Node Events

​Interface Events

​Threshold Events

​Custom Events

​Configuration

​See Also

Build docs developers (and LLMs) love

Overview

NMISNG::Events

Constructor

Event Operations

eventAdd()

eventExist()

eventLoad()

eventUpdate()

eventDelete()

Event Queries

get_events_model()

Event Logging

logEvent()

Utility Methods

cleanNodeEvents()

NMISNG::Event Object

Constructor

event()

Event Properties

Core Properties

Event Operations

save()

load()

delete()

acknowledge()

check()

Event Status Methods

exists()

is_new()

is_alert()

is_proactive()

Logging Methods

log()

getLogLevel()

Event Levels

Common Event Names

Node Events

Interface Events

Threshold Events

Custom Events

Configuration

See Also