plugin

package module
v0.0.0-...-346b018 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2017 License: GPL-3.0 Imports: 8 Imported by: 0

README

go-plugin

GoDoc Build Status Codecov Status

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.