alert_api API

Trigger alert

local device_connection_alert = alerts:newAlert({
  entity = "mac",
  type = "device_connection",
  severity = "info",
})

device_connection_alert:trigger("00:11:22:33:44:55",
   "The device 00:11:22:33:44:55 has connected to the network")

Metadata

Metadata mandatory params:
  • type: defines the type of the alert, for example “threshold_cross”, “new_device”
  • entity: defines the type of the entity which this alert is inherent to, e.g. “host” identifies the alerts for the hosts, “influx_db” the alerts for InfluxDB
  • severity: defines the alert severity, “info”, “warning” or “error”
Metadata optional params:
  • periodicity: if set, it specify which is the expected alert recheck periodicity, e.g. if set to “5mins”, it means that the alert “trigger” method is expected to be called every 5 minutes. Supported values are “min”, “5mins”, “hour”, “day”
  • subtype: when multiple alerts with the same type existing, it is possible to specify a subtype. For example, threshold cross alerts for bytes have type=”threshold_cross” and subtype=”min_bytes”
  • formatter: a function that will be used to format the alert message. The function will receive two parameters (msg, alert_record). msg contains the message of the alert (usually a parsed JSON), whereas alert_record contains the fields of the alerts as stored into the database. (experimental)

Functions

function addAlertPoolAndNetworkInfo(entity_info, alert_json)

Adds pool information to the alert.

Parameters
  • entity_info: data returned by one of the entity_info building functions

function pushSmartRecordingFilter(entity_info, ifid)

Push filter matching the alert to Smart Recording if enabled See also Host::enqueueAlertToRecipients for alerts triggered from C++.

Parameters
  • entity_info: data returned by one of the entity_info building functions

function store(entity_info, type_info, when)

Return
true if the alert was successfully stored, false otherwise
Parameters
  • entity_info: data returned by one of the entity_info building functions
  • type_info: data returned by one of the type_info building functions
  • when: (optional) the time when the release event occurs

function trigger(entity_info, type_info, when, cur_alerts)

Trigger an alert of given type on the entity.

Return
true on if the alert was triggered, false otherwise
Note
The actual trigger is performed asynchronously
Note
false is also returned if an existing alert is found and refreshed
Parameters
  • entity_info: data returned by one of the entity_info building functions
  • type_info: data returned by one of the type_info building functions
  • when: (optional) the time when the release event occurs
  • cur_alerts: (optional) a table containing triggered alerts for the current entity

function release(entity_info, type_info, when, cur_alerts)

Release an alert of given type on the entity.

Note
The actual release is performed asynchronously
Return
true on success, false otherwise
Parameters
  • entity_info: data returned by one of the entity_info building functions
  • type_info: data returned by one of the type_info building functions
  • when: (optional) the time when the release event occurs
  • cur_alerts: (optional) a table containing triggered alerts for the current entity