nagiosplugin

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 14, 2016 License: BSD-3-Clause Imports: 6 Imported by: 7

README

Build status

nagiosplugin

Package for writing Nagios/Icinga/et cetera plugins in Go (golang).

Documentation

See http://godoc.org/github.com/olorin/nagiosplugin.

Usage example

The general usage pattern looks like this:

func main() {
	// Initialize the check - this will return an UNKNOWN result
	// until more results are added.
	check := nagiosplugin.NewCheck()
	// If we exit early or panic() we'll still output a result.
	defer check.Finish()

	// obtain data here

	// Add an 'OK' result - if no 'worse' check results have been
	// added, this is the one that will be output.
	check.AddResult(nagiosplugin.OK, "everything looks shiny, cap'n")
	// Add some perfdata too (label, unit, value, min, max,
	// warn, crit). The math.Inf(1) will be parsed as 'no
	// maximum'.
	check.AddPerfDatum("badness", "kb", 3.14159, 0.0, math.Inf(1), 8000.0, 9000.0)

	// Parse a range from the command line and warn on a match.
	warnRange, err := nagiosplugin.ParseRange( "1:2" )
	if err != nil {
		check.AddResult(nagiosplugin.UNKNOWN, "error parsing warning range")
	}
	if warnRange.Check( 3.14159 ) {
		check.AddResult(nagiosplugin.WARNING, "Are we crashing again?")
	}
}

Language version

Requires go >= 1.0; tested with versions up to 1.5.

Documentation

Overview

The nagiosplugin package is a check development framework for Nagios and compatible monitoring systems.

Example
package main

import (
	"github.com/olorin/nagiosplugin"
	"math"
)

func main() {
	check := nagiosplugin.NewCheck()
	// Make sure the check always (as much as possible) exits with
	// the correct output and return code if we terminate unexpectedly.
	defer check.Finish()
	// (If the check panicked on the next line, it'd exit with a
	// default UNKNOWN result.)
	//
	// Our check is testing the internal consistency of the
	// universe.
	value := math.Pi
	// We add a dimensionless metric with a minimum of zero, an
	// unbounded maximum, a warning threshold of 4000.0 and a
	// critical threshold of 9000.0 (for graphing purposes).
	check.AddPerfDatum("badness", "", value, 0.0, math.Inf(1), 4000.0, 9000.0)
	// Add an OK check result as the universe appears sane.
	check.AddResult(nagiosplugin.OK, "Everything looks shiny from here, cap'n")
	// We potentially perform more checks and add more results here;
	// if there's more than one, the highest result will be the one
	// returned (in ascending order OK, WARNING, CRITICAL, UNKNOWN).

	// This will print:
	// OK: Everything looks shiny from here, cap'n | badness=3.141592653589793;4000;9000;0;
}
Output:

Index

Examples

Constants

View Source
const (
	Version = "1.1.0"
)

Variables

This section is empty.

Functions

func Exit

func Exit(status Status, message string)

Standalone Exit function for simple checks without multiple results or perfdata.

Example
package main

import (
	"github.com/olorin/nagiosplugin"
)

func main() {
	nagiosplugin.Exit(nagiosplugin.CRITICAL, "Badness over 9000!")
}
Output:

func NewDefaultStatusPolicy added in v1.2.0

func NewDefaultStatusPolicy() *statusPolicy

NewDefaultStatusPolicy returns a status policy that assigns relative severity in accordance with conventional Nagios plugin return codes. Statuses associated with higher return codes are more severe.

func NewStatusPolicy added in v1.2.0

func NewStatusPolicy(statuses []Status) (*statusPolicy, error)

NewStatusPolicy returns a status policy that assigns relative severity in accordance with a user-configurable prioritised slice. Check statuses must be listed in ascending severity order.

func RenderPerfdata

func RenderPerfdata(perfdata []PerfDatum) string

RenderPerfdata accepts a slice of PerfDatum objects and returns their concatenated string representations in a form suitable to append to the first line of check output.

Types

type Check

type Check struct {
	// contains filtered or unexported fields
}

Represents the state of a Nagios check.

func NewCheck

func NewCheck() *Check

NewCheck returns an empty Check object.

func NewCheckWithOptions added in v1.2.0

func NewCheckWithOptions(options CheckOptions) *Check

NewCheckWithOptions returns an empty Check object with caller-specified behavioural modifications. See CheckOptions.

func (*Check) AddPerfDatum

func (c *Check) AddPerfDatum(label, unit string, value float64, thresholds ...float64) error

AddPerfDatum adds a metric to the set output by the check. unit must be a valid Nagios unit of measurement (UOM): "us", "ms", "s", "%", "b", "kb", "mb", "gb", "tb", "c", or the empty string. UOMs are not case-sensitive.

Zero or more of the thresholds min, max, warn and crit may be supplied; these must be of the same UOM as the value.

A threshold may be positive or negative infinity, in which case it will be omitted in the check output. A value may not be either infinity.

Returns error on invalid parameters.

func (*Check) AddResult

func (c *Check) AddResult(status Status, message string)

AddResult adds a check result. This will not terminate the check. If status is the highest yet reported, this will update the check's final return status.

func (*Check) AddResultf

func (c *Check) AddResultf(status Status, format string, v ...interface{})

AddResultf functions as AddResult, but takes a printf-style format string and arguments.

func (*Check) Criticalf

func (c *Check) Criticalf(format string, v ...interface{})

Criticalf is a shorthand function which exits the check with status CRITICAL and the message provided.

func (*Check) Exitf

func (c *Check) Exitf(status Status, format string, v ...interface{})

Exitf takes a status plus a format string, and a list of parameters to pass to Sprintf. It then immediately outputs and exits.

func (*Check) Finish

func (c *Check) Finish()

Finish ends the check, prints its output (to stdout), and exits with the correct status.

func (Check) String

func (c Check) String() string

String representation of the check results, suitable for output and parsing by Nagios.

func (*Check) Unknownf

func (c *Check) Unknownf(format string, v ...interface{})

Unknownf is a shorthand function which exits the check with status UNKNOWN and the message provided.

type CheckOptions added in v1.2.0

type CheckOptions struct {

	// StatusPolicy defines the relative severity of different check
	// results by status value.
	//
	// A Nagios plugin must ultimately report a single status to its
	// parent process (OK, CRITICAL, etc.). nagiosplugin allows plugin
	// developers to batch multiple check results in a single plugin
	// invocation. The most severe result will be reflected in the
	// plugin's final exit status. By default, results are prioritised
	// by the numeric 'plugin return codes' defined by the Nagios Plugin
	// Development Guidelines. Results with CRITICAL status will take
	// precedence over WARNING, WARNING over OK, and UNKNOWN over all
	// other results. This ordering may be tailored with a custom
	// policy. See NewStatusPolicy().
	StatusPolicy *statusPolicy
}

CheckOptions contains knobs that modify default Check behaviour. See NewCheckWithOptions().

type PerfDatum

type PerfDatum struct {
	// contains filtered or unexported fields
}

PerfDatum represents one metric to be reported as part of a check result.

func NewPerfDatum

func NewPerfDatum(label string, unit string, value float64, thresholds ...float64) (*PerfDatum, error)

NewPerfDatum returns a PerfDatum object suitable to use in a check result. unit must a valid Nagios unit, i.e., one of "us", "ms", "s", "%", "b", "kb", "mb", "gb", "tb", "c", or the empty string.

Zero to four thresholds may be supplied: min, max, warn and crit. Thresholds may be positive infinity, negative infinity, or NaN, in which case they will be omitted in check output.

func (PerfDatum) String

func (p PerfDatum) String() string

String returns the string representation of a PerfDatum, suitable for check output.

type Range added in v1.1.0

type Range struct {
	Start         float64
	End           float64
	AlertOnInside bool
}

Range is a combination of a lower boundary, an upper boundary and a flag for inverted (@) range semantics. See 0 for more details.

func ParseRange added in v1.1.0

func ParseRange(rangeStr string) (*Range, error)

Returns a new range object and nil if the given range definition was valid, or nil and an error if it was invalid.

func (*Range) Check added in v1.1.0

func (r *Range) Check(value float64) bool

Returns true if an alert should be raised based on the range (if the value is outside the range for normal semantics, or if the value is inside the range for inverted semantics ('@-semantics')).

func (*Range) CheckInt added in v1.1.0

func (r *Range) CheckInt(val int) bool

CheckInt is a convenience method which does an unchecked type conversion from an int to a float64.

func (*Range) CheckUint64 added in v1.1.0

func (r *Range) CheckUint64(val uint64) bool

CheckUint64 is a convenience method which does an unchecked type conversion from an uint64 to a float64.

type Result

type Result struct {
	// contains filtered or unexported fields
}

Result encapsulates a machine-readable result code and a human-readable description of a problem. A check may have multiple Results. Only the most severe Result will be reported on the first line of plugin output and in the plugin's exit status.

type Status

type Status uint

Nagios plugin exit status.

const (
	OK Status = iota
	WARNING
	CRITICAL
	UNKNOWN
)

https://nagios-plugins.org/doc/guidelines.html#AEN78

func (Status) String

func (s Status) String() string

Returns string representation of a Status. Panics if given an invalid status (this will be recovered in check.Finish if it has been deferred).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL