Intermediate data API

The following classes allow to handle intermediate data that are used during the plugin’s execution in a structured way. Most of them are used by the nagiosplugin library itself to create objects which are passed into code written by plugin authors. Other classes (like Metric) are used by plugin authors to generate intermediate data during acquisition or evaluation steps.

Note

All classes that plugin authors typically need are imported directly into the nagiosplugin name space. For example, use

import nagiosplugin
# ...
result = nagiosplugin.Result(nagiosplugin.Ok)

to get a Result instance.

nagiosplugin.metric

Structured representation for data points.

This module contains the Metric class whose instances are passed as value objects between most of nagiosplugin’s core classes. Typically, Resource objects emit a list of metrics as result of their probe() methods.

class nagiosplugin.metric.Metric(name, value, uom=None, min=None, max=None, context=None, contextobj=None, resource=None)

Single measured value.

The value should be expressed in terms of base units, so Metric(‘swap’, 10240, ‘B’) is better than Metric(‘swap’, 10, ‘kiB’).

Creates new Metric instance.

Parameters:

  • name – short internal identifier for the value – appears also in the performance data

  • value – data point, usually has a boolen or numeric type, but other types are also possible

  • uom – unit of measure, preferrably as ISO abbreviation like “s”

  • min – minimum value or None if there is no known minimum

  • max – maximum value or None if there is no known maximum

  • context – name of the associated context (defaults to the metric’s name if left out)

  • contextobj – reference to the associated context object (set automatically by Check)

  • resource – reference to the originating Resource (set automatically by Check)

static __new__(cls, name, value, uom=None, min=None, max=None, context=None, contextobj=None, resource=None)

Creates new Metric instance.

Parameters:

  • name – short internal identifier for the value – appears also in the performance data

  • value – data point, usually has a boolen or numeric type, but other types are also possible

  • uom – unit of measure, preferrably as ISO abbreviation like “s”

  • min – minimum value or None if there is no known minimum

  • max – maximum value or None if there is no known maximum

  • context – name of the associated context (defaults to the metric’s name if left out)

  • contextobj – reference to the associated context object (set automatically by Check)

  • resource – reference to the originating Resource (set automatically by Check)

__str__()

Same as valueunit.

nagiosplugin.state

Classes to represent check outcomes.

This module defines ServiceState which is the abstract base class for check outcomes. The four states defined by the Nagios plugin API are represented as singleton subclasses.

Note that the warning state is defined by the Warn class. The class has not been named Warning to avoid being confused with the built-in Python exception of the same name.

class nagiosplugin.state.ServiceState(code, text)

Abstract base class for all states.

Each state has two constant attributes: text is the short text representation which is printed for example at the beginning of the summary line. code is the corresponding exit code.

Create new instance of ServiceState(code, text)

__str__()

Plugin-API compliant text representation.

__int__()

Plugin API compliant exit code.

Note

ServiceState is not imported into the nagiosplugin top-level name space since there is usually no need to access it directly.

nagiosplugin.state.worst(states)

Reduce list of states to the most significant state.

State subclasses

The state subclasses are singletons. Plugin authors should use the class name (without parentheses) to access the instance. For example:

state = nagiosplugin.Critical
nagiosplugin.state.Ok

alias of (0, ‘ok’)

nagiosplugin.state.Warn

alias of (1, ‘warning’)

nagiosplugin.state.Critical

alias of (2, ‘critical’)

nagiosplugin.state.Unknown

alias of (3, ‘unknown’)

Because these are implemented as classes, the Warn class cannot be named Warning, or it would occlude the Python built-in exception class.

nagiosplugin.performance

Performance data (perfdata) representation.

Performance data are created during metric evaluation in a context and are written into the perfdata section of the plugin’s output. Performance allows the creation of value objects that are passed between other nagiosplugin objects.

For sake of consistency, performance data should represent their values in their respective base unit, so Performance('size', 10000, 'B') is better than Performance('size', 10, 'kB').

class nagiosplugin.performance.Performance(label, value, uom='', warn='', crit='', min='', max='')

Create new performance data object.

Parameters:

  • label – short identifier, results in graph titles for example (20 chars or less recommended)

  • value – measured value (usually an int, float, or bool)

  • uom – unit of measure – use base units whereever possible

  • warn – warning range

  • crit – critical range

  • min – known value minimum (None for no minimum)

  • max – known value maximum (None for no maximum)

static __new__(cls, label, value, uom='', warn='', crit='', min='', max='')

Create new performance data object.

Parameters:

  • label – short identifier, results in graph titles for example (20 chars or less recommended)

  • value – measured value (usually an int, float, or bool)

  • uom – unit of measure – use base units whereever possible

  • warn – warning range

  • crit – critical range

  • min – known value minimum (None for no minimum)

  • max – known value maximum (None for no maximum)

__str__()

String representation conforming to the plugin API.

Labels containing spaces or special characters will be quoted.

nagiosplugin.range

class nagiosplugin.range.Range(spec='')

Represents a threshold range.

The general format is “[@][start:][end]”. “start:” may be omitted if start==0. “~:” means that start is negative infinity. If end is omitted, infinity is assumed. To invert the match condition, prefix the range expression with “@”.

See http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT for details.

Creates a Range object according to spec.

Parameters:

spec – may be either a string, an int, or another Range object.

static __new__(cls, spec='')

Creates a Range object according to spec.

Parameters:

spec – may be either a string, an int, or another Range object.

__str__()

Human-readable range specification.

__repr__()

Parseable range specification.

nagiosplugin.result

Outcomes from evaluating metrics in contexts.

The Result class is the base class for all evaluation results. The Results class (plural form) provides a result container with access functions and iterators.

Plugin authors may create their own Result subclass to accomodate for special needs. Context constructors accept custom Result subclasses in the result_cls parameter.

class nagiosplugin.result.Result(state, hint=None, metric=None)

Evaluation outcome consisting of state and explanation.

A Result object is typically emitted by a Context object and represents the outcome of an evaluation. It contains a ServiceState as well as an explanation. Plugin authors may subclass Result to implement specific features.

Creates a Result object.

Parameters:

  • state – state object

  • hint – reason why this result arose

  • metric – reference to the Metric from which this result was derived

static __new__(cls, state, hint=None, metric=None)

Creates a Result object.

Parameters:

  • state – state object

  • hint – reason why this result arose

  • metric – reference to the Metric from which this result was derived

__str__()

Textual result explanation.

The result explanation is taken from metric.description (if a metric has been passed to the constructur), followed optionally by the value of hint. This method’s output should consist only of a text for the reason but not for the result’s state. The latter is rendered independently.

Returns:

result explanation or empty string

class nagiosplugin.result.ScalarResult(state, hint, metric)

Special-case result for evaluation in a ScalarContext.

DEPRECATED: use Result instead.

Creates a Result object.

Parameters:

  • state – state object

  • hint – reason why this result arose

  • metric – reference to the Metric from which this result was derived

class nagiosplugin.result.Results(*results)

Container for result sets.

Basically, this class manages a set of results and provides convenient access methods by index, name, or result state. It is meant to make queries in Summary implementations compact and readable.

The constructor accepts an arbitrary number of result objects and adds them to the container.

__iter__()

Iterates over all results.

The iterator is sorted in order of decreasing state significance (unknown > critical > warning > ok).

Returns:

result object iterator

__len__()

Number of results in this container.

__getitem__(item)

Access result by index or name.

If item is an integer, the itemth element in the container is returned. If item is a string, it is used to look up a result with the given name.

Returns:

Result object

Raises:

KeyError – if no matching result is found

__contains__(name)

Tests if a result with given name is present.

Returns:

boolean