radtools.services.linux
Class NagiosStatsRequest

java.lang.Object
  radtools.services.linux.NagiosStatsRequest

public class NagiosStatsRequest
extends Object

This class is used to gather statistics from a running instance of Nagios. It reads the information from the Nagios status file, negating the need to reconfigure or even restart the Nagios installation. Though there is a lot of information available, the most useful data comes in the form of plugin output. If you're only interested in this data, pay attention to the methods getUsefulDataNames() and getUsefulDataValue(String).

When creating a new instance of a StatsRequest, you pass in the name of the Nagios status file (commonly found in either /usr/local/nagios/var/log/ or /var/log/nagios/, and commonly named either status.dat or status.log). You also pass in the refreshRate, or the number of milliseconds to wait between refreshing the stored status values. If you pass in a number <= 0, the statistics will only be refreshed by a call to refreshStats().

In order to add another useful status value to the list, you have to make the following additions:

- in getUsefulDataNames(), add the desired statistic name to the array - in getUsefulDataValue(String), add the created statistic name as a new condition, with the necessary code to extract the important piece of information as a double - in pluginRadToNagios(String), add a new condition to transform the created statistic name to the one that is used in the Nagios status file under service_description

This code assumes that Nagios v2.6 is being used. No guarantees are made about compatibility with other versions. All plugins are assumed to be running with host_name=localhost.

Version:

$Revision: 1.2 $

Author:

Nathan Burkhart

Nested Class Summary

private static class

NagiosStatsRequest.State Used to keep track of which portion of the status file is being read during a call to refreshStats().

Field Summary

private String	END_BLOCK_1 Represents the end of a block in the status file.
private String	END_BLOCK_2 Represents an alternative version of the the end of a block in the status file.
private String	HOST Represents the statistic that holds the value of the particular host's name in the status file.
private String	hostName Stores the current host's name when inside of a Host or Service block in a call to refreshStats().
private long	lastRefreshed The last time that the statistic values were refreshed, as given by System.currentTimeMillis().
private char[]	line_buffer The buffer used to store characters when reading lines from the Nagios status file.
private String	NAME_SEPARATOR The set of characters used to separate host, service, and statistic names when displaying the names of available statistics in the status file.
private String	SERV Represents the statistic that holds the value of the particular service's name in the status file.
private String	servName Stores the current service's name when inside of a Service block in a call to refreshStats().
private String	START_HOST Represents the beginning of a Host block in the status file.
private String	START_INFO Represents the beginning of an Info block in the status file.
private String	START_PROG Represents the beginning of a Program block in the status file.
private String	START_SERV Represents the beginning of a Service block in the status file.
private Hashtable<String,String>	statsBase Stores all statistics not related to a particular host or service; namely, statistics inside the Info or Program object blocks.
private Hashtable<String,Hashtable<String,String>>	statsHost Stores statistics that are related to a particular host as given by host_name (so within a Host block).
private Hashtable<String,Hashtable<String,Hashtable<String,String>>>	statsServ Stores statistics that are related to a particular service as given by service_description (so within a Service block) that is related to a particular host as given by host_name.

Constructor Summary

NagiosStatsRequest()

Method Summary

String	getFullPluginOutput(String service) Get the plugin output from the specified service.
Collection<String>	getListHost() Return a Collection containing the name of all hosts present in the Nagios status file.
Collection<String>	getListServ() Return a Collection containing the name of all services present in the Nagios status file.
String	getSpecificStat(String host, String service, String stat) Get the value of a specific statistic from the stored Nagios statistics.
Collection<String>	getStatListBase() Return a Collection containing the name of every basic statistic available.
Collection<String>	getStatListFull() Return a Collection containing the name of all available statistics in the Nagios status file.
Collection<String>	getStatListHost() Return a Collection containing the name of every host-specific statistic available.
Collection<String>	getStatListServ() Return a Collection containing the name of every service-specific statistic available.
private void	getStatVal(NagiosStatsRequest.State state, int length) After reading a line from the Nagios status file and storing its contents in line_buffer, this method is called to extract the value of the statistic on that line and store it in the appropriate place (in one of statsBase, statsHost, or statsServ).
String[]	getUsefulDataNames() Get an array containing the names of available useful data values.
double	getUsefulDataValue(String name) Returns the useful information from the specified piece of data, in the form of a double.
private String	pluginRadToNagios(String name) Convert the given alias for a useful piece of data to the name used in the Nagios status file.
private void	putStatBase(String stat, String value) Stores the value for the given basic statistic in the proper location (statsBase).
private void	putStatHost(String host, String stat, String value) Stores the value for the given host-specific statistic in the proper location (statsHost).
private void	putStatServ(String host, String service, String stat, String value) Stores the value for the given service-specific statistic in the proper location (statsServ).
boolean	refreshStats(InputStream input) TODO: Javadoc Refreshes the values of the stored statistics by reading in the current values from the Nagios status file.
long	wasLastRefreshed() Get the last time that the statistics were successfully refreshed, meaning a call was made to refreshStats() that returned true.

Methods inherited from class java.lang.Object

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

Field Detail

statsBase

private Hashtable<String,String> statsBase

Stores all statistics not related to a particular host or service; namely, statistics inside the Info or Program object blocks. This Hashtable maps a statistic name to the stored value of that statistic.

statsHost

private Hashtable<String,Hashtable<String,String>> statsHost

Stores statistics that are related to a particular host as given by host_name (so within a Host block). This Hashtable maps a host name to another Hashtable, which maps a statistic name to the stored value of that statistic (in relation to the particular host).

statsServ

private Hashtable<String,Hashtable<String,Hashtable<String,String>>> statsServ

Stores statistics that are related to a particular service as given by service_description (so within a Service block) that is related to a particular host as given by host_name. This Hashtable maps a host name to another Hashtable, which maps a service name to another Hashtable, which maps a statistic name to the stored valye of that statistic (in relation to the particular host and service).

START_INFO

private final String START_INFO

Represents the beginning of an Info block in the status file.

See Also:

Constant Field Values

START_PROG

private final String START_PROG

Represents the beginning of a Program block in the status file.

See Also:

Constant Field Values

START_HOST

private final String START_HOST

Represents the beginning of a Host block in the status file.

See Also:

Constant Field Values

START_SERV

private final String START_SERV

Represents the beginning of a Service block in the status file.

See Also:

Constant Field Values

END_BLOCK_1

private final String END_BLOCK_1

Represents the end of a block in the status file.

See Also:

Constant Field Values

END_BLOCK_2

private final String END_BLOCK_2

Represents an alternative version of the the end of a block in the status file.

See Also:

Constant Field Values

HOST

private final String HOST

Represents the statistic that holds the value of the particular host's name in the status file. This shows up in both Host and Service blocks.

See Also:

Constant Field Values

SERV

private final String SERV

Represents the statistic that holds the value of the particular service's name in the status file. This shows up in only Service blocks.

See Also:

Constant Field Values

NAME_SEPARATOR

private final String NAME_SEPARATOR

The set of characters used to separate host, service, and statistic names when displaying the names of available statistics in the status file.

See Also:

Constant Field Values

line_buffer

private char[] line_buffer

The buffer used to store characters when reading lines from the Nagios status file. It assumes that no line will have more than 1000 characters.

lastRefreshed

private long lastRefreshed

The last time that the statistic values were refreshed, as given by System.currentTimeMillis(). If this value is -1, then the statistics were never refreshed.

hostName

private String hostName

Stores the current host's name when inside of a Host or Service block in a call to refreshStats().

servName

private String servName

Stores the current service's name when inside of a Service block in a call to refreshStats().

Constructor Detail

NagiosStatsRequest

public NagiosStatsRequest()

Method Detail

getFullPluginOutput

public String getFullPluginOutput(String service)

Get the plugin output from the specified service. It is assumed that the name passed in is one of the ones given in getUsefulDataNames(). This method returns the entirety of the String stored as plugin_output in the Nagios status file. Note that a call to getFullPluginOutput(SERVICE), assuming that the plugin has run at least once so the value stored in has_been_checked is 1, returns the same thing as a call to getSpecificStat("localhost", this.pluginRadToNagios(SERVICE), "plugin_output").

Parameters:

service - The name of the requested Service; assumes that this is one of the names returned by getUsefulDataNames().

Returns:

The line stored as plugin_output inside of the relevant Service block, or null if the plugin hasn't yet been run or if that Service doesn't exist. Assumes that the Service is one of the ones specifed in getUsefulDataNames, which also assumes it is running on localhost.

getListHost

public Collection<String> getListHost()

Return a Collection containing the name of all hosts present in the Nagios status file. This means that there must exist a Host block for each host retunred, where the name returned is the one stored in host_name.

Returns:

A Collection of all present host names as Strings.

getListServ

public Collection<String> getListServ()

Return a Collection containing the name of all services present in the Nagios status file. This means that there must exist a Service block for each service returned, where the name returned is composed of the host name (stored in host_name) and service name (stored in service_description). The two parts of the name are separated by NAME_SEPARATOR.

Returns:

A Collection of all present service names as Strings of the format HOSTNAME->SERVICENAME. Note that the -> comes from the String NAME_SEPARATOR, defined elsewhere in this Class.

getSpecificStat

public String getSpecificStat(String host,
                              String service,
                              String stat)

Get the value of a specific statistic from the stored Nagios statistics. The value comes in the form of a String, which is pulled directly from the Nagios status file with no formatting or other modification. The relevant host and service (if applicable) are passed in; if they are unnecessary, they should be left null. For instance, if you want the value of a statistic in the Info or Program block in the status file, pass in null for host and service and that name of that statistic for stat. If you want a particular statistic from a Host block, give the relevant host's name and leave service null.

Parameters:

host - The name of the particular host, or null if not applicable.

service - The name of the particular service, or null if not applicable.

stat - The name of the particular desired statistic.

Returns:

The value of the requested statistic pulled straight from the status file, or null if the statistic doesn't exist.

getStatListBase

public Collection<String> getStatListBase()

Return a Collection containing the name of every basic statistic available. This includes all statistics included in the Info and Program blocks in the Nagios status file. To retrieve the value of one of the returned statistics STAT, call getSpecificStat(null, null, STAT).

Returns:

A Collection of all basic statistics in the Nagios status file.

getStatListFull

public Collection<String> getStatListFull()

Return a Collection containing the name of all available statistics in the Nagios status file. This includes the statistics returned by getStatListBase(), getStatListHost(), and getStatListServ().

Returns:

A Collection of all available statistics in the Nagios status file.

getStatListHost

public Collection<String> getStatListHost()

Return a Collection containing the name of every host-specific statistic available. This includes all statistics included in a Host block in the Nagios status file. The names returned are of the format HOST->STAT, where HOST is the value in host_name and STAT is the name of the statistic. Note that the -> comes from the String NAME_SEPARATOR, defined elsewhere in this Class. To retrieve the value of one of the returned statistics HOST->STAT, call getSpecificStat(HOST, null, STAT).

Returns:

A Collection of all host-specific statistics in the Nagios status file.

getStatListServ

public Collection<String> getStatListServ()

Return a Collection containing the name of every service-specific statistic available. This includes all statistics included in a Service block in the Nagios status file. The names returned are of the format HOST->SERVICE->STAT, where HOST is the value in host_name, SERVICE is the value in service_description, and STAT is the name of the statistic. Note that the -> comes from the String NAME_SEPARATOR, defined elsewhere in this Class. To retrieve the value of one of the returned statistics HOST->SERVICE->STAT, call getSpecificStat(HOST, SERVICE, STAT).

Returns:

A Collection of all service-specific statistics in the Nagios status file.

getStatVal

private void getStatVal(NagiosStatsRequest.State state,
                        int length)

After reading a line from the Nagios status file and storing its contents in line_buffer, this method is called to extract the value of the statistic on that line and store it in the appropriate place (in one of statsBase, statsHost, or statsServ). The passed in State represents at which point of the status file this line was read (inside of an Info block, Program block, Host block, or Service block, or outside of a particular block). The length represents the point in line_buffer at which the line ends (always starts at the beginning of the buffer). Note that the values in hostName and servName persist across calls to this method; they are reset when the end of a particular block is reached.

Parameters:

state - The State of the current line in the Nagios status file, indicating whether or not it is inside of a particular block and, if so, which type of block it is (Info, Program, Host, or Service).

length - The index at which the last character in the line is stored in line_buffer.

getUsefulDataNames

public String[] getUsefulDataNames()

Get an array containing the names of available useful data values. Any of these names can be passed into getFullPluginOutput(String) to retrieve the relevant piece of data, in the form of a double. The statistic names returned by this method are generally the only ones that you need to interact with, unless you need to pull the exact contents of the status file (in that case, look into getSpecificStat(String, String, String) and the getList* and getStatList* methods).

If you want to add a new statistic from the Nagios status file to the list of useful data points, you have to add an alias to the array contained in this method. It is assumed that the information you want comes out of the statistic plugin_output of a particular Service from the status file, and that the service is related to localhost (meaning that the value of host_name in that Service block is localhost).

Returns:

An array of Strings representing names of useful pieces of data.

getUsefulDataValue

public double getUsefulDataValue(String name)

Returns the useful information from the specified piece of data, in the form of a double. Assumes that the passed in name is one of the Strings returned by getUsefulDataNames().

If you want to add a new statistic from the Nagios status file to the list of useful data points, you have to add a condition to check for its alias in this method. It is assumed that the information you want comes out of the statistic plugin_output of a particular Service from the status file, and that the service is related to localhost (meaning that the value of host_name in that Service block is localhost). Also assumes that the statistic's alias has already been set in getUsefulDataNames(). Inside of the chain of if statements, under the condition that check for the relevant alias, you have to add logic to extract and return the needed piece of data in the form of a double.

Parameters:

name - The alias of the data value desired, as given by getUsefulDataNames().

Returns:

A double representing the useful data relating to this statistic, or -1 if it does not exist or has not yet been gathered by the related plugin.

pluginRadToNagios

private String pluginRadToNagios(String name)

Convert the given alias for a useful piece of data to the name used in the Nagios status file. Assumes that this is the name given by service_description inside of a Service block, and that the value for host_name within that block is localhost.

If you want to add a new statistic from the Nagios status file to the list of useful data points, you have to add a condition to check for its alias in this method. The alias you use in the if condition must be the same as the one returned by getUsefulDataNames(). It is assumed that the information you desire is in plugin_output inside of the relevant Service block.

Parameters:

name - The alias used for the particular service.

Returns:

The name used in the Nagios status file, or the empty String if the passed in alias does not exist.

putStatBase

private void putStatBase(String stat,
                         String value)

Stores the value for the given basic statistic in the proper location (statsBase). Assumes that the given statistic is found in either the Info or Program block in the Nagios status file. This value can be retrieved with a call to getSpecificStat(null, null, stat).

Parameters:

stat - The name of the specific statistic.

value - The value of the given statistic, as read from the Nagios status file.

putStatHost

private void putStatHost(String host,
                         String stat,
                         String value)

Stores the value for the given host-specific statistic in the proper location (statsHost). Assumes that the given statistic is found in a Host block in the Nagios status file, with the host_name being passed in as host. On a call to getStatListHost(), the name of this statistic will be returned as host->stat. This value can be retrieved with a call to getSpecificStat(host, null, stat).

Parameters:

host - The name of the specific host, as given in the status file by host_name.

stat - The name of the specific statistic.

value - The value of the given statistic, as read from the Nagios status file.

putStatServ

private void putStatServ(String host,
                         String service,
                         String stat,
                         String value)

Stores the value for the given service-specific statistic in the proper location (statsServ). Assumes that the given statistic is found in a Service block in the Nagios status file, with the host_name and service_description being passed in as host and service (respectively). On a call to getStatListHost(), the name of this statistic will be returned as host->service->stat. This value can be retrieved with a call to getSpecificStat(host, service, stat).

Parameters:

host - The name of the specific host, as given in the status file by host_name.

service - The name of the specific service, as given in the status file by service_description.

stat - The name of the specific statistic.

value - The value of the given statistic, as read from the Nagios status file.

refreshStats

public boolean refreshStats(InputStream input)

TODO: Javadoc Refreshes the values of the stored statistics by reading in the current values from the Nagios status file. If this StatsRequest was initialized with a positive refreshPeriod, this method will automatically be called periodically. Otherwise, this must be explicitly called whenever you want fresh information. The method will return true if all statistic vales were correctly updated. If it returns false, no guarantees are made about which (if any) of the statistics were correctly updated. If it returns true, lastRefreshed will be updated to contain the time at which it returned, given by System.currentTimeMillis().

Returns:

True if all updates were successful, false otherwise.

wasLastRefreshed

public long wasLastRefreshed()

Get the last time that the statistics were successfully refreshed, meaning a call was made to refreshStats() that returned true. The time is as given by System.currentTimeMillis().

Returns:

The last time that refreshStats() was called and returned successfully.