Check Hooks

ntopng uses hooks to know when to execute a check. Hooks are string keys of the plugin hooks table and have a check function assigned. Hooks are associated to:

  • Predefined events for flows
  • Intervals of time for any other network element such as an host, or a network

Flow Check Hooks and Other Check Hooks are discussed below.

Flow Check Hooks

Available hooks for flow checks are the following:

  • protocolDetected: Called after the Layer-7 application protocol has been detected.
  • statusChanged: Called when the internal status of the flow has changed since the previous invocation.
  • periodicUpdate: Called every few minutes on long-lived flows.
  • flowEnd: Called when the flow is considered finished.
  • flowBegin: Called when the flow is seen for the first time.
  • all: A special hook which will cause the associated check to be called for all the available hooks.

Flow Check Hooks Parameters

ntopng calls flow checks with two parameters:

  • now: An integer indicating the current epoch
  • script_config: A table containing the check configuration submitted by the user from the Checks GUI. Table can be empty if the script doesn not require user-submitted configuration.

Flow Check Hook Example

A check which needs to be called every time a flow goes idle, will implement a check function and assign it to hook flowEnd.

hooks = {
  flowEnd  = function (now, script_config)
    --[[ Check function body --]]
  end
}

Other Check Hooks

Available hooks for non-flow checks are the following:

  • min: Called every minute.
  • 5mins: Called every 5 minutes.
  • hour: Called every hour.
  • day: Called every day (at midnight localtime).
  • all: A special hook name which will cause the associated check to be called for all the available hooks.

Other Check Hooks Parameters

ntopng calls every check hook function with a params Lua table as argument. The script hook function is expected to have this structure:

function my_check(params)
  -- ...
end

The params contains the following keys:

  • granularity: one of aperiodic, min, 5mins, hour, day.
  • alert_entity: A table carrying information on the current entity which can be used to generate alerts.
  • entity_info: A string identifying the current entity.
  • cur_alerts: Currently engaged alert for the entity.
  • check_config: The check configuration submitted by the user from the Checks GUI. Table can be empty if the script doesn not require user-submitted configuration.
  • check: The name of the check which is being called.
  • when: An integer indicating the current epoch.
  • ifid: The interface id of the current interface.
  • ts_enabled: True when the timeseries generation is enabled for the current timeseries.

It is ntopng which takes care of calling the hook check function with table params opportunely populated.

Other Check Hooks Example

A check which needs to be called every minute will implement a check function and assign it to hook min

hooks = {min  = function (params) --[[ Check function body --]] end }