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’).
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 byCheck)
-
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 byCheck)
-
evaluate()¶ Evaluates this instance according to the context.
Returns: ResultobjectRaises: RuntimeError – if no context has been associated yet
-
performance()¶ Generates performance data according to the context.
Returns: PerformanceobjectRaises: RuntimeError – if no context has been associated yet
-
replace(**attr)¶ Creates new instance with updated attributes.
-
description¶ Human-readable, detailed string representation.
Delegates to the
Contextto format the value.Returns: describe()output orvalueunitif 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. 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:
textis the short text representation which is printed for example at the beginning of the summary line.codeis 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.
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¶ 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¶ Represents a threshold range.
The general format is “[@][start:][end]”. “start:” may be omitted if start==0. “~:” means that start is negative infinity. If
endis 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.
-
match(value)¶ Decides if
valueis inside/outside the threshold.Returns: Trueif value is inside the bounds for non-inverted Ranges.Also available as
inoperator.
-
violation¶ Human-readable description why a value does not match.
-
static
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
Contextobject and represents the outcome of an evaluation. It contains aServiceStateas 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
Metricfrom 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
Metricfrom 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 ofhint. 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
Summaryimplementations 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: ResultobjectRaises: KeyError – 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
Resultobjects in the constructor, additional results may be added after creating the container.Raises: ValueError – if resultis not aResultobject
-
first_significant¶ Selects one of the results with most significant state.
Returns: ResultobjectRaises: IndexError – 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 Resultobjects or empty list if no results are present
-
most_significant_state¶ The “worst” state found in all results.
Returns: ServiceStateobjectRaises: ValueError – if no results are present
-