Author image Dean Hamstead
and 2 contributors

NAME

Monit::HTTP - An OOP interface to Monit.

VERSION

version 0.04

SYNOPSIS

 use Monit::HTTP;

 # Use defaults to authenticate
 my $monit = Monit::HTTP->new( use_auth => 1 );

 # Or specify what you need (defaults displayed)
 my $monit = Monit::HTTP->new(
            hostname => '127.0.0.1',
            port     => '2812',
            use_auth => 0,
            username => 'admin',
            password => 'monit',
            );

 # list processes
 my @processes = $hd->get_services();

DESCRIPTION

This module exposes an interface to talk with Monit via its HTTP interface. You can use it to get the status of all the monitored services on that particular host such as CPU and Memory usage, current PID, parent PID, current running status, current monitoring status and so on. The module can be used also for performing actions like:

COMMON USE CASES

  • Start/Stop/Restart services

    Send a PR with an example!

  • Monitor/Unmonitor services

        use Monit::HTTP ':constants';
        use Try::Tiny; # or your favourite
    
        my $hd = Monit::HTTP->new(
                use_auth => 1,
                );
    
        try {
            my @processes = $hd->get_services(TYPE_PROCESS);
            $hd->command_run($processes[0], ACTION_STOP);
            my $service_status_href = $hd->service_status($processes[0]);
        }
        catch {
            print "caught error: $_"
        };

EXPORTED CONSTANTS

When brought in with:

 use Monit::HTTP ':hashes';

This module will export these variables:

%MONIT_ACTIONS

Contains the following keys with corresponding codes:

 ACTION_MONITOR
 ACTION_RESTART
 ACTION_START
 ACTION_STOP
 ACTION_UNMONITOR
%MONIT_ACTIONS_REV

As per %MONIT_ACTIONS but with keys and values reversed.

%MONIT_STATUS

Contains possible service status's with corresponding codes.

Probably %MONIT_STATUS_REV is more useful to you.

%MONIT_STATUS_REV

As per %MONIT_STATUS but with keys and values reversed.

Look up human readable status from its code using the status code.

%MONIT_TYPES

Contains the following keys with corresponding codes.

 TYPE_DIRECTORY
 TYPE_FIFO
 TYPE_FILE
 TYPE_FILESYSTEM
 TYPE_HOST
 TYPE_PROCESS
 TYPE_SYSTEM

Use this hash when requesting certain service types

%MONIT_TYPES_REV

As per %MONIT_TYPES but with keys and values reversed.

Look up the status type from its code using this hash.

%MONIT_MONITOR

Contains the monitoring status's with corresponding codes.

Probably %MONIT_MONITOR_REV is of more use to you.

%MONIT_MONITOR_REV

As per %MONIT_MONITOR but with keys and values reversed.

Look up human readable monitoring status from its code using the status code.

When brought in with:

 use Monit::HTTP ':constants';

This module exports a set of constants:

 TYPE_FILESYSTEM
 TYPE_DIRECTORY
 TYPE_FILE
 TYPE_PROCESS
 TYPE_HOST
 TYPE_SYSTEM
 TYPE_FIFO

 ACTION_STOP
 ACTION_START
 ACTION_RESTART
 ACTION_MONITOR
 ACTION_UNMONITOR

Use them as arguments for methods.

Note: the above are all from constant, so they are sub's.

METHODS

$monit = Monit::HTTP->new(...)

Constructor method, which creates a new Monit::HTTP object.

This constructor can be called passing a list of various parameters:

    my $monit = Monit::HTTP->new(
                    hostname => 'localhost',
                    port     => 2812,
                    use_auth => 0,
                    username => 'admin',
                    password => 'monit'
        );

FYI The values above are the default values in case no argument is passed to the constructor.

If use_auth is equal to 1 (true) and username and password are not null the http request will be performed using those usernames and password (basic HTTP authentication). Be aware that if you provide username and password and you don't set use_auth to be 1 authentication won't work.

$monit->set_hostname($hostname)

Set the hostname of the Monit instance

$monit->set_port($port)

Set the TCP port of the Monit instance

$monit->set_username($username)

Set the username to be used in thee basic http authentication

$monit->set_password($password)

Set the password to be used in thee basic http authentication

$res = $monit->_fetch_info()

Called by "get_services".

Does not need to be called by user. This is a private (internal) method This private function connects via http (GET) to the monit server.

URL requested is http://<hostname>:<port>/_status?format=xml

An XML file is returned and parsed using XML::Fast.

The raw XML data is stored in the object using the "_set_xml" method. The raw XML data can be retrieved using "_get_xml".

An hash reference of the XML data (as the one returned by the parse_xml function of XML::Fast) is stored in the object.

$res = $monit->get_services()

Return an array of services configured on the remote monit daemon.

In case of any exception an error is thrown and undef is returned.

$res = $monit->_set_xml($xml)

Private method to set raw XML data. Called from "_fetch_info"

$res = $monit->_get_xml($xml)

Private method to get raw XML data. Called from "_fetch_info"

$hashref_tree = $monit->service_status($servicename)

Returns the status for a particular service in form of hash with all the info for that service. Return undef is the service does not exists. To know the structure of the hash ref use Data::Dumper :D

$monit->command_run($servicename, $command)

Perform an action against a service. $command can be a constant (ACTION_STOP, ACTION_START, ACTION_RESTART, ACTION_MONITOR, ACTION_UNMONITOR)

This method throws errors in case something goes wrong. Use eval { } statement to catch the error.

BUGS

Please report any bugs or feature requests to bug-monit-http-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Monit-HTTP-API. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Monit::HTTP

You can also look for information at:

ACKNOWLEDGEMENTS

AUTHORS

  • Angelo "pallotron" Failla <pallotron@freaknet.org>

  • Dean Hamstead <dean@bytefoundry.com.au>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Angelo Failla.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.