sensulib

README

sensulib

Base library for writing go checks.

Goals

There are three goals for this project:

1. write a go library to help writing go check plugins.
2. provide a magefile library to help publishing assets for Sensu-go.

Usage

Root command error handling

Check handlers use panic instead of os.Exit for breaking execution, for better testability. However, the main command has to recover from panic to properly exit with the provided exit code:

package main

import "github.com/julian7/sensulib"

func main() {
    defer sensulib.Recover()

    if err := rootCmd().Execute(); err != nil {
        sensulib.HandleError(err)
    }
}

Build a sensu check command

This snippet creates a command with a configuration struct, therefore all the parameters will be readily available during run. checkCmd() returns a *cobra.Command, which then can be called or added to another command.

package main

import (
    "github.com/julian7/sensulib"
    "github.com/spf13/cobra"
)

type checkConfig struct {
    param1 string
    param2 float64
}

func (conf *checkConfig) Run(cmd *cobra.Command, []args string) error {
    // interesting things
    return nil
}

func checkCmd() *cobra.Command {
    config := &checkConfig{}
    cmd := sensulib.Command(
        config,
        "use",
        "short desc",
        "long desc",
    )
    flags := cmd.Flags()
    flags.StringVarP(&config.param1, "param1", "p", "", "first parameter")
    flags.Float64VarP(&config.param2, "param2, "P", 0.0, "second parameter")

    return cmd
}

Errors

There are two error classes in sensulib: a single one, and an aggregate one. Both can be used to return from commands.

Single errors:

• sensulib.Ok(error): no real error, it should report success.
• sensulib.Warn(error): report Warning-level (1) error.
• sensulib.Crit(error): report Critical-level (2) error.
• sensulib.Unknown(error): report Unknown-level (3) error.

Aggregate errors:

• sensulib.NewErrors(): create a new aggregate.
• sensulib.Errors.Add(err): add a new single error.
• sensulib.Errors.Return(err): return with aggregated errors, or a default one, if specified.

Humanize

Some numbers need to be converted to be human-readable. Some functions:

• sensulib.SizeToHuman(uint64): converts bytes into IEC-formatted, rounded string.
• sensulib.PercentToHuman(percent float64, precision int): converts percentage into a nice, rounded string.

Legal

This project is licensed under Blue Oak Model License v1.0.0. It is not registered either at OSI or GNU, therefore GitHub is widely looking at the other direction. However, this is the license I'm most happy with: you can read and understand it with no legal degree, and there are no hidden or cryptic meanings in it.

The project is also governed with Contributor Covenant's Code of Conduct in mind. I'm not copying it here, as a pledge for taking the verbatim version by the word, and we are not going to modify it in any way.

Any issues?

Open a ticket, perhaps a pull request. We support GitHub Flow. You might want to fork this project first.

Documentation

Index

• Constants
• func CatchExit(t Errorable, name string, want int)
• func Exit(code int)
• func HandleError(err error)
• func NewCommand(runnable Runnable, use, short, long string) *cobra.Command
• func PercentToHuman(percent float64, precision int) string
• func Recover()
• func SizeToHuman(size uint64) string
• type Error
  • func Crit(args ...interface{}) *Error
  • func NewError(crit int, args ...interface{}) *Error
  • func Ok(args ...interface{}) *Error
  • func Unknown(args ...interface{}) *Error
  • func Warn(args ...interface{}) *Error
  • func (serr *Error) Error() string
  • func (serr *Error) Exit()
• type ErrorExiter
• type Errorable
• type Errors
  • func NewErrors() *Errors
  • func (errs *Errors) Add(err *Error)
  • func (errs *Errors) Error() string
  • func (errs *Errors) Exit()
  • func (errs *Errors) Return(err error) error
• type Runnable

Constants

const (
	OK = iota
	WARN
	CRIT
	UNKNOWN
)

Functions

func CatchExit

func CatchExit(t Errorable, name string, want int)

func Exit

func Exit(code int)

Exit behaves like os.Exit, but instead of exiting right away, it panic()s instead. This allows test code to capture exit calls, while the program can act as intended, by deferring Recover() at the beginning.

func HandleError

func HandleError(err error)

func NewCommand

func NewCommand(runnable Runnable, use, short, long string) *cobra.Command

NewCommand returns a now *cobra.Command suitable for self-contained configuration

func PercentToHuman

func PercentToHuman(percent float64, precision int) string

PercentToHuman returns a string value of percentage, with at most a given precision

func Recover

func Recover()

Recover allows to convert panic back to os.Exit call

func SizeToHuman

func SizeToHuman(size uint64) string

SizeToHuman converts byte size to IEC size string

Types

type Error

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

Error is a sensu-aware error message, which knows about its criticality

func Crit

func Crit(args ...interface{}) *Error

Crit creates a Critical-level error

func NewError

func NewError(crit int, args ...interface{}) *Error

NewError creates a new Error

func Ok

func Ok(args ...interface{}) *Error

Ok creates a OK-level error

func Unknown

func Unknown(args ...interface{}) *Error

Unknown creates a Unknown-level error

func Warn

func Warn(args ...interface{}) *Error

Warn creates a Warning-level error

func (*Error) Error

func (serr *Error) Error() string

Error returns a string representing the error and its criticality

func (*Error) Exit

func (serr *Error) Exit()

Exit terminates run by returning the error

type ErrorExiter

type ErrorExiter interface {
	error
	Exit()
}

type Errorable

type Errorable interface {
	Errorf(string, ...interface{})
}

type Errors

type Errors []*Error

Errors is a slice of Error

func NewErrors

func NewErrors() *Errors

NewErrors is a new, empty Errors slice

func (*Errors) Add

func (errs *Errors) Add(err *Error)

Add appends error to the slice, if it's not nil

func (*Errors) Error

func (errs *Errors) Error() string

Error returns all the errors, with all criticalities

func (*Errors) Exit

func (errs *Errors) Exit()

Exit terminates run by returning error

func (*Errors) Return

func (errs *Errors) Return(err error) error

Return provides return value for aggregates

type Runnable

type Runnable interface {
	Run(*cobra.Command, []string) error
}

Runnable is an interface command.New can take to generate a new cobra command