plugin

README

go-plugin

Description

Package plugin provides a Go library which helps writing monitoring plugins.

Synopsis

package main

import (
  "github.com/ajgb/go-plugin"
)

var opts struct {
  Hostname string `short:"H" long:"hostname" description:"Host" default:"localhost"`
  Port     int    `short:"p" long:"port" description:"Port" default:"123"`
}

func main() {
  check := plugin.New("check_service", "v1.0.0")
  if err := check.ParseArgs(&opts); err != nil {
    check.ExitCritical("Error parsing arguments: %s", err)
  }
  defer check.Final()

  check.AddMessage("Service %s:%d", opts.Hostname, opts.Port)

  serviceMetrics, err := .... // retrieve metrics
  if err != nil {
    check.ExitCritical("Connection to %s:%d failed: %s", opts.Hostname, opts.Port, err)
  }

  for metric, value := range serviceMetrics {
    check.AddMetric(metric, value)
  }
}

API Documentation

Please read full usage documentation at https://godoc.org/github.com/ajgb/go-plugin

License

Copyright (C) 2017 Alex J. G. Burzyński

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Documentation

Overview

Package plugin provides a Go library which helps writing monitoring plugins.

Features:

• Setting and appending check messages
• Aggregation of results
• Thresholds and ranges for metrics with breaches reported
• Exit shortcut helper methods
• Provides extensive command line options parser

Example usage:

package main

// import plugin library
import (
  "github.com/ajgb/go-plugin"
)

// define command line options
var opts struct {
  Hostname string `short:"H" long:"hostname" description:"Host" required:"true"`
  Port     int    `short:"p" long:"port" description:"Port" required:"true"`
}

func main() {
  // initialize check
  check := plugin.New("check_service", "v1.0.0")

  // parse command line arguments
  if err := check.ParseArgs(&opts); err != nil {
    check.ExitCritical("Error parsing arguments: %s", err)
  }

  // return result on exit
  defer check.Final()

  // add service data to output
  check.AddMessage("Service %s:%d", opts.Hostname, opts.Port)

  // gather metrics - provided by some function
  serviceMetrics, err := .... // retrieve metrics
  if err != nil {
    check.ExitCritical("Connection failed: %s", err)
  }

  // add metrics to output
  for metric, value := range serviceMetrics {
    check.AddMetric(metric, value)
  }
}

Index

• type Plugin
  • func New(name, version string) *Plugin
  • func (p *Plugin) AddMessage(format string, args ...interface{})
  • func (p *Plugin) AddMetric(name string, value interface{}, args ...string) error
  • func (p *Plugin) AddResult(code Status, format string, args ...interface{})
  • func (p *Plugin) ExitCritical(format string, args ...interface{})
  • func (p *Plugin) ExitOK(format string, args ...interface{})
  • func (p *Plugin) ExitUnknown(format string, args ...interface{})
  • func (p *Plugin) ExitWarning(format string, args ...interface{})
  • func (p *Plugin) Final()
  • func (p *Plugin) ParseArgs(opts interface{}) error
  • func (p *Plugin) SetMessage(format string, args ...interface{})
  • func (p *Plugin) Status() Status
  • func (p *Plugin) UpdateStatus(status Status)
• type Status
  • func (st Status) ExitCode() int
  • func (st Status) String() string

Types

type Plugin

type Plugin struct {

	// Plugin name
	Name string
	// Plugin version
	Version string
	// Preamble displayed in help output before flags usage
	Preamble string
	// Plugin description displayed in help after flags usage
	Description string
	// If true all metrics will be added to check message
	AllMetricsInOutput bool
	// Messages separator, default: ", "
	MessageSeparator string
	// contains filtered or unexported fields
}

Plugin represents the check - its name, version and help messages. It also stores the check status, messages and metrics data.

func New

func New(name, version string) *Plugin

New creates a new plugin instance.

check := plugin.New("check_service", "v1.0.0")

func (*Plugin) AddMessage

func (p *Plugin) AddMessage(format string, args ...interface{})

AddMessage appends message to check output.

check.AddMessage("Server %s", opts.Hostname)

func (*Plugin) AddMetric

func (p *Plugin) AddMetric(name string, value interface{}, args ...string) error

AddMetric adds new metric to check's performance data, with name and value parameters required. The optional string arguments include (in order): uom (unit of measurement), warning threshold, critical threshold - for details see Monitoring Plugins Development Guidelines. Note: Metrics names have to be unique.

// basic usage - add metric with value
check.AddMetric("load5", 0.98)

// metric with UOM
check.AddMetric("tmp", 15789, "MB")

// metric with warning threshold (without uom)
check.AddMetric("rtmax", 28.723, "", 75)

// metric with warning & critical thresholds (with uom)
check.AddMetric("rta", 24.558, "ms", 50, 100)

func (*Plugin) AddResult

func (p *Plugin) AddResult(code Status, format string, args ...interface{})

AddResult aggregates results and appends message to check output - the worst result is final.

// would not change the final result
check.AddResult(plugin.OK, "Server %s", opts.Hostname)

// increases to WARNING level
if opts.SkipSSLChecks {
    check.AddResult(plugin.WARNING, "Skiping SSL Certificate checks")
}

func (*Plugin) ExitCritical

func (p *Plugin) ExitCritical(format string, args ...interface{})

ExitCritical exits with specified message and CRITICAL exit status. Note: existing messages and metrics are discarded.

func (*Plugin) ExitOK

func (p *Plugin) ExitOK(format string, args ...interface{})

ExitOK exits with specified message and OK exit status. Note: existing messages and metrics are discarded.

check.ExitOK("Test mode | metric1=1.1; metric2=2.2")

func (*Plugin) ExitUnknown

func (p *Plugin) ExitUnknown(format string, args ...interface{})

ExitUnknown exits with specified message and UNKNOWN exit status. Note: existing messages and metrics are discarded.

func (*Plugin) ExitWarning

func (p *Plugin) ExitWarning(format string, args ...interface{})

ExitWarning exits with specified message and WARNING exit status. Note: existing messages and metrics are discarded.

func (*Plugin) Final

func (p *Plugin) Final()

Final calculates the final check output and exit status.

check := plugin.New("check_service, "v1.0.0")
// make sure Final() is called
defer check.Final()

func (*Plugin) ParseArgs

func (p *Plugin) ParseArgs(opts interface{}) error

ParseArgs parses the command line options using flags parsing library providing handling of short/long names, flags and lists, and default and required options. For details please see https://godoc.org/github.com/jessevdk/go-flags. Note: -h/--help is automatically added

if err := check.ParseArgs(&opts); err != nil {
	check.ExitCritical("Error parsing arguments: %s", err)
}

func (*Plugin) SetMessage

func (p *Plugin) SetMessage(format string, args ...interface{})

SetMessage replaces accumulated messages with new one provided.

check.SetMessage("%s", opts.Hostname)

func (*Plugin) Status

func (p *Plugin) Status() Status

Status returns current status.

fmt.Printf("Status after first five metrics: %s\n", check.Status)

func (*Plugin) UpdateStatus

func (p *Plugin) UpdateStatus(status Status)

UpdateStatus updates final exit status if the provided value is higher (worse) then the current Status.

// keep people awake
if rand.Intn(100) % 3 == 0 {
    check.UpdateStatus(plugin.CRITICAL)
}

type Status

type Status int

const (
	OK Status = iota
	WARNING
	CRITICAL
	UNKNOWN
)

Supported exit statuses

func (Status) ExitCode

func (st Status) ExitCode() int

ExitCode returns current status as integer

func (Status) String

func (st Status) String() string

String returns current status as string