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¶

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’).

static __new__(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.

evaluate()¶

Evaluates this instance according to the context.

Raises RuntimeError:
Returns:	`Result` object
	if no context has been associated yet

performance()¶

Generates performance data according to the context.

Raises RuntimeError:
Returns:	`Performance` object
	if no context has been associated yet

replace(**attr)¶: Creates new instance with updated attributes.

description¶

Human-readable, detailed string representation.

Delegates to the Context to format the value.

Returns:	`describe()` output or `valueunit` if no context has been associated yet

valueunit¶

Compact string representation.

This is just the value and the unit. If the value is a real number, express the value with a limited number of digits to improve readability.

nagiosplugin.state¶

Classes to represent check outcomes.

This module defines ServiceState which is the abstract base class for check outcomes. class for check outcomes. 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¶

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.

__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¶

nagiosplugin.state.Warn¶

nagiosplugin.state.Critical¶

nagiosplugin.state.Unknown¶

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 to create 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¶

static __new__(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¶

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.

static __new__(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.

match(value)¶

Decides if value is inside/outside the threshold.

Returns:	`True` if value is inside the bounds for non-inverted Ranges.

Also available as in operator.

violation¶: Human-readable description why a value does not match.

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¶

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.

static __new__(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

context¶: Reference to the metric used to generate this result.

resource¶: Reference to the resource used to generate this result.

class nagiosplugin.result.ScalarResult¶

Special-case result for evaluation in a ScalarContext.

DEPRECATED: use Result instead.

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.

Raises KeyError:
Returns:	`Result` object
	if no matching result is found

__contains__(name)¶

Tests if a result with given name is present.

Returns:	boolean

add(*results)¶

Adds more results to the container.

Besides passing Result objects in the constructor, additional results may be added after creating the container.

Raises ValueError:
	if `result` is not a `Result` object

first_significant¶

Selects one of the results with most significant state.

Raises IndexError:
Returns:	`Result` object
	if no results are present

most_significant¶

Returns list of results with most significant state.

From all results present, a subset with the “worst” state is selected.

Returns:	list of `Result` objects or empty list if no results are present

most_significant_state¶

The “worst” state found in all results.

Raises ValueError:
Returns:	`ServiceState` object
	if no results are present

Table Of Contents

Previous topic

Next topic

This Page