README
¶
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 ¶
- Constants
- func Exit(status Status, message string)
- func NewDefaultStatusPolicy() *statusPolicy
- func NewStatusPolicy(statuses []Status) (*statusPolicy, error)
- func RenderPerfdata(perfdata []PerfDatum) string
- type Check
- func (c *Check) AddPerfDatum(label, unit string, value float64, thresholds ...float64) error
- func (c *Check) AddResult(status Status, message string)
- func (c *Check) AddResultf(status Status, format string, v ...interface{})
- func (c *Check) Criticalf(format string, v ...interface{})
- func (c *Check) Exitf(status Status, format string, v ...interface{})
- func (c *Check) Finish()
- func (c Check) String() string
- func (c *Check) Unknownf(format string, v ...interface{})
- type CheckOptions
- type PerfDatum
- type Range
- type Result
- type Status
Examples ¶
Constants ¶
const (
Version = "1.1.0"
)
Variables ¶
This section is empty.
Functions ¶
func Exit ¶
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
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 ¶
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 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 ¶
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 ¶
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 ¶
AddResultf functions as AddResult, but takes a printf-style format string and arguments.
func (*Check) Criticalf ¶
Criticalf is a shorthand function which exits the check with status CRITICAL and the message provided.
func (*Check) Exitf ¶
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.
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.
type Range ¶ added in v1.1.0
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
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
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
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
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.
Source Files