org.opennms.netmgt.poller.monitors

Class BSFMonitor

java.lang.Object

org.opennms.netmgt.poller.support.AbstractServiceMonitor

org.opennms.netmgt.poller.monitors.BSFMonitor

All Implemented Interfaces:

ServiceMonitor

public class BSFMonitor
extends AbstractServiceMonitor

This ServiceMonitor is designed to enable the evaluation or execution of user-supplied scripts via the Bean Scripting Framework (BSF). Scripts should indicate a status whose string value is one of: "OK" (service is available), "UNK" (service status unknown), "UNR" (service is unresponsive), or "NOK" (service is unavailable). These strings map into the status values defined in @PollStatus and are indicated differently depending on the run-type of the script in question (see below for details). Use cases: a) Evaluate an expression from a file in the filesystem. The result of the evaluation carries the status indication in this mode. As a special case for backward compatibility, a status code outside the set described above will be taken to convey that the service is unavailable, and the status code itself will be set as the reason code. If the scripting engine in use supports bean manipulation during an evaluation, then any entries put into the "times" bean will be returned for optional thresholding and/or persisting. If no entries exist in this bean upon the evaluation's return, then a single value describing the time window (in milliseconds) from just before the evaluation began until just after it returned will be substituted. This mode is the default if no "run-type" parameter is specified in the service definition or if this parameter's value is "eval". b) Execute a self-contained script from a file in the filesystem. The script must put an entry into the "results" HashMap bean with key "status" and a value from the above list of service status indications. If the script puts one or more entries into the "times" bean, then these key-value pairs will be returned for optional thresholding and/or persisting. If no entry exists in this bean with a key of "response-time", the overall response time will be substituted as the time from just before the script's execution to just after its completion. This mode is used if the service's definition contains a "run-type" parameter with a value of "exec". The following beans are declared in the script's execution context: map: A @Map allowing direct access to the list of parameters configured for the service at hand ip_addr: A @String representing the IPv4 or IPv6 address of the interface on which the polled service resides node_id: An int containing the unique identifying number from the OpenNMS configuration database of the node on whose interface the monitored service resides node_label: A @String containing the textual node label of the node on whose interface the monitored service resides svc_name: A @String containing the textual name of the monitored service bsf_monitor: The singleton instance of the @BSFMonitor class, useful primarily for purposes of logging via its log(String sev, String fmt, Object... args) method. The severity must be one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL. The format is a printf-style format string, and the args fill in the tokens. results: A @HashMap that the script may use to pass its results back to the @BSFMonitor. A status indication should be set into the entry with key "status", and for status indications other than "OK" a reason code should be set into the entry with key "reason". times: A @LinkedHashMap that the script may use to pass one or more response times back to the @BSFMonitor.

Author:

Jason Aras, Jeff Gehlbach, OpenNMS

Constructor Summary

Constructors

Constructor and Description
BSFMonitor()

Method Summary

Modifier and Type	Method and Description
void	log(String level, String format, Object... args)
PollStatus	poll(MonitoredService svc, Map<String,Object> map) This method is the heart of the plug-in monitor.

Methods inherited from class org.opennms.netmgt.poller.support.AbstractServiceMonitor

getEffectiveLocation, getKeyedBoolean, getKeyedInstance, getKeyedInteger, getKeyedLong, getKeyedObject, getKeyedString, getRuntimeAttributes, getServiceProperties

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BSFMonitor

public BSFMonitor()

Method Detail

poll

public PollStatus poll(MonitoredService svc,
                       Map<String,Object> map)

This method is the heart of the plug-in monitor. Each time an interface requires a check to be performed as defined by the scheduler the poll method is invoked. The poll is passed the service to check.

By default when the status transition from up to down or vice versa the framework will generate an event. Additionally, if the polling interval changes due to an extended unavailability, the framework will generate an additional down event. The plug-in can suppress the generation of the default events by setting the suppress event bit in the returned integer.

NOTE: This method may be invoked on a Minion, in which case certain bean and facilities will not be available. If any state related information is required such as agent related configuration, it should retrieved by the ServiceMonitor.getRuntimeAttributes(MonitoredService, Map).

Parameters:

svc - Includes details about to the service being monitored.

map - Includes the service parameters defined in poller-configuration.xml and those returned by ServiceMonitor.getRuntimeAttributes(MonitoredService, Map).

Returns:

The availability of the interface and if a transition event should be suppressed.

See Also:

PollStatus.SERVICE_AVAILABLE, PollStatus.SERVICE_UNAVAILABLE, PollStatus.SERVICE_AVAILABLE, PollStatus.SERVICE_UNAVAILABLE

log

public void log(String level,
                String format,
                Object... args)