NAME
Monitoring::Sneck::Checks::base - what Monitoring::Sneck::Checks checks are built on
VERSION
Version 0.0.1
SYNOPSIS
package Monitoring::Sneck::Checks::example;
use strict;
use warnings;
use parent 'Monitoring::Sneck::Checks::base';
sub option_spec { return ( 'file|f=s', 'warning|w=s', 'critical|c=s' ) }
sub defaults { return { warning => '10', critical => '20' } }
sub required { return ('file') }
sub ranges { return ( 'warning', 'critical' ) }
sub check {
my ($self) = @_;
my @lines = split( /\n/, ... );
my $code = $self->threshold_status( scalar(@lines), $self->opt('warning'), $self->opt('critical') );
$self->perfdata( label => 'lines', value => scalar(@lines), warning => $self->opt('warning') );
return $self->finish( $code, scalar(@lines) . ' lines in ' . $self->opt('file') );
}
1;WRITING A CHECK
A check is a subclass named Monitoring::Sneck::Checks::$name. It is made by "new", which parses its args, and then "check" is called, which returns the code. Those it may provide are below. Only check is needed.
- check :: Does the check. Returns OK, WARNING, CRITICAL, or UNKNOWN, usually through "finish". Dying is UNKNOWN.
- option_spec :: The options it takes, as a list of Getopt::Long specs. The first name of each is what "opt" knows it by. -t and --timeout are added.
- defaults :: A hash ref of defaults for its options.
- required :: A list of the options that must be given.
- ranges :: A list of the options that are ranges, see "RANGES", checked by new.
- validate :: Given the hash ref of options, returns a list of what is wrong with them, for what option_spec and ranges can not catch.
- label :: What starts its output, such as HTTP. The upper cased name by default.
Output is written through "out" and "err", not print, which keeps the order of the two. Anything printed is caught as well, so it never ends up in sneck's own output. A check must not exit, as it runs inside sneck.
Modules only some checks use should be loaded with require in the check, as every check runs in the same process.
COMMON OPTIONS
- -t, --timeout :: Seconds to wait on the network. Each lookup or connection gets this, not the check as a whole. Default :: a second under what it is run with, and at least one
RANGES
Thresholds are nagios style ranges. A value outside of the range alerts, or inside of it if it starts with @.
- 10 :: Under 0 or over 10.
- 10: :: Under 10.
- ~:10 :: Over 10, ~ being negative infinity.
- 10:20 :: Under 10 or over 20.
- @10:20 :: 10 to 20.
METHODS
new
Makes the check and parses its args. Dies on bad args, which is UNKNOWN.
- args :: Array ref of args, or a string of them. Default :: []
- timeout :: Seconds it is run with. Default :: 30
my $check = Monitoring::Sneck::Checks::http->new( args => [ '-H', 'www.example.org' ], timeout => 30 );parse_args
Parses args as said by option_spec, defaults, required, and ranges. Used by new. Dies listing every problem.
- args :: Array ref of args, or a string of them, which Getopt::Long splits like a shell would. A string with unbalanced quotes dies.
Returns a hash ref of option names to values.
my $options = $check->parse_args( [ '-H', 'www.example.org', '-w', '2' ] );
my $options = $check->parse_args(q{-H www.example.org -s 'Welcome home'});quotes_balanced
Returns 1 if every ' and " in the text is closed, else 0. A backslash escapes the next character, in or out of quotes, the same as Getopt::Long splitting a string goes by.
$check->quotes_balanced(q{-s 'Welcome home'}); # 1
$check->quotes_balanced(q{-s 'Welcome}); # 0
$check->quotes_balanced(q{-s "it's"}); # 1option_spec
Returns the Getopt::Long specs of the check's options. None for base.
defaults
Returns a hash ref of defaults for the check's options. None for base.
required
Returns the options that must be given. None for base.
ranges
Returns the options that are ranges. None for base.
validate
Returns a list of what is wrong with the options, given as a hash ref. Nothing for base.
check
Does the check. Dies for base, as each check has its own.
label
Returns what starts the check's output, the upper cased name, such as HTTP for Monitoring::Sneck::Checks::http.
opt
Returns the value of a option, or undef if it was not given and has no default.
my $host = $check->opt('hostname');timeout
Returns the seconds to wait on the network, see "COMMON OPTIONS".
out
Adds to the output.
$check->out( "a line\n" );err
Adds to the errors.
$check->err( "could not read it\n" );finish
Writes the status line and returns the code, so a check can end with return $self->finish(...).
- code :: OK, WARNING, CRITICAL, or UNKNOWN.
- message :: What it found.
- details :: Lines to add after the status line, the nagios long output.
The line is the label, status, and message, with any perfdata after a |.
return $self->finish( $self->OK, '200 OK in 0.120 seconds' );
# HTTP OK - 200 OK in 0.120 seconds | time=0.120s;1;2;0status_name
Returns the name of a code, such as CRITICAL for 2.
worst
Returns the worst of the codes given, CRITICAL, then WARNING, then UNKNOWN, then OK. OK if none are given.
my $code = $check->worst( $check->OK, $check->UNKNOWN, $check->WARNING );
# WARNINGparse_range
Parses a range, see "RANGES". Dies if it is not valid.
Returns a hash ref of start, undef for negative infinity, end, undef for infinity, and inside, 1 if it starts with @.
my $range = $check->parse_range('@10:20');
# { start => 10, end => 20, inside => 1 }in_alert
Returns 1 if a value alerts for a range, else 0.
$check->in_alert( 15, '10' ); # 1
$check->in_alert( 15, '10:' ); # 0threshold_status
Returns CRITICAL if a value alerts for the critical range, WARNING if for the warning one, else OK. A undef range is skipped.
my $code = $check->threshold_status( $seconds, $check->opt('warning'), $check->opt('critical') );perfdata
Adds perfdata, which finish puts after the status line.
- label :: The name, quoted if it needs it.
- value :: The value.
- uom :: The unit, such as s, B, or %.
- warning, critical, min, max :: As in the nagios plugin guidelines.
Returns the perfdata as text.
$check->perfdata( label => 'time', value => '0.120', uom => 's', warning => 1, critical => 2, min => 0 );
# time=0.120s;1;2;0is_host
Returns 1 if the text is a IP or hostname, else 0.
$check->is_host('www.example.org'); # 1
$check->is_host('not a host'); # 0user_agent
Returns a LWP::UserAgent using the timeout, not following redirects, and checking certificates.
- insecure :: 1 to not check certificates.
- ca_file :: The CA file to check them against.
- max_redirect :: Redirects to follow. Default :: 0
my $user_agent = $check->user_agent( insecure => $check->opt('insecure') );resolver
Returns a Net::DNS::Resolver using the timeout.
- servers :: Array ref of the servers to ask. The system's if not given.
- tcp :: 1 to ask over TCP.
- no_recurse :: 1 to not ask for recursion, for asking authoritative servers.
my $resolver = $check->resolver( servers => ['192.0.2.53'] );cert_details
Returns details on a certificate, a Net::SSLeay X509, as a hash ref.
- subject :: The common name, or the whole subject if it has none.
- issuer :: The same, for the issuer.
- not_before, not_after :: When it is good from and to, as time since epoch.
- days_left :: Whole days until not_after, negative once past it.
- names :: Array ref of its subject alternative names, such as DNS:www.example.org.
my $details = $check->cert_details( $socket->peer_certificate );cert_status
Works out the status of a certificate from when it is good to.
- details :: From "cert_details".
- warning :: Days left at or under which it is WARNING.
- critical :: Days left at or under which it is CRITICAL.
Returns the code and a message. Expired or not good yet is CRITICAL.
my ( $code, $message ) = $check->cert_status( $details, 30, 14 );
# ( 1, '"www.example.org" expires in 20 days, 2026-11-21 12:00:00 UTC' )utc_time
Returns a time since epoch as text, such as 2026-11-21 12:00:00 UTC.
read_socket
Reads from a socket until done says so, it closes, or the timeout passes.
- socket :: The socket, plain or TLS.
- done :: A code ref given what has been read so far, returning true once it is enough.
Returns what was read.
my $greeting = $check->read_socket( $socket, sub { $_[0] =~ /^\d{3} [^\n]*\n/m } );pem_certs
Reads the certificates in a PEM file. Dies if it can not be read.
Returns a array ref of a Net::SSLeay X509 for each, in order, undef for any that can not be parsed. Empty if there are none. Free them with "CERT_free" in IO::Socket::SSL::Utils.
my $certs = $check->pem_certs('/usr/local/etc/ssl/www-chain.pem');run_command
Runs a command, without a shell, and waits for it, with stdin from /dev/null. Dies if it can not be run.
- command :: The program and its args, as a list.
Returns its exit code and its stdout and stderr together. A command killed by a signal has a exit of 128 plus the signal.
If the check times out while the command runs, the command, and anything it started, is sent TERM, then KILL if it is still there half a second later, so a hung command does not hold the check up past its timeout. For that it is run in a process group of its own.
my ( $exit, $output ) = $check->run_command( '/usr/sbin/pkg', 'audit' );split_expect
Splits a expect, a name, a comparison, and a value, as sysctl and config_value take. The comparison is =, !=, <, <=, >, or >=.
Returns the name, comparison, and value, or a empty list if it is not valid.
my ( $name, $comparison, $value ) = $check->split_expect('kern.securelevel>=1');
# ( 'kern.securelevel', '>=', '1' )expect_met
Checks a value against a expect.
- value :: The value it has.
- comparison :: =, !=, <, <=, >, or >=.
- wanted :: The value wanted. For = and !=, values split by |, any of which is enough for =, and none of which may match for !=. Runs of space in them are squashed. A empty one, as all of "name=" or the last of "name=a|", is met by a empty value. The others compare as numbers, and a value that is not a number does not meet them.
- no_case :: 1 to compare = and != without case.
Returns 1 if it is met, else 0.
$check->expect_met( '1', '=', '1|2' ); # 1
$check->expect_met( '5', '<', '3' ); # 0
$check->expect_met( '', '=', '' ); # 1expect_wanted
Returns what a expect wants as text, for messages, a empty value shown as "".
$check->expect_wanted( '>=', '1' ); # 'at least 1'
$check->expect_wanted( '=', 'a|b' ); # 'a or b'
$check->expect_wanted( '=', '' ); # '""'shown
Returns a value as it is to be shown in messages, which is as it is, other than a empty one being "".
$check->shown('022'); # '022'
$check->shown(''); # '""'read_state
Reads state kept between runs, as JSON.
- file :: The state file.
Returns a hash ref of it, a empty one if there is none yet, or undef if it can not be read or is not a JSON object.
my $state = $check->read_state( $Monitoring::Sneck::Checks::base::STATE_DIR . '/interface-em0.json' );write_state
Writes the state, through a temporary file renamed into place, making the directory if needed.
- file :: The state file.
- state :: Hash ref of the state.
Returns undef, or what went wrong.
os
Returns the OS, as in $^O, such as linux or freebsd.
sysctl
Returns the value of a sysctl, through BSD::Sysctl, which is only loaded when this is used, so only needed on the BSDs. Dies if it is not there.
my $cpus = $check->sysctl('hw.ncpu');proc_file
Returns the content of a file under Linux's /proc, such as meminfo. Dies if it can not be read.
my $meminfo = $check->proc_file('meminfo');