more documentation and add in base64+gzip support

Makefile.PL

@@ -22,6 +22,8 @@ my %WriteMakefileArgs = (
 	PREREQ_PM => {
 		'Module::List' => '0.004',
 		'JSON'         => '2.97.001',
+		'MIME::Base64' => '3.16',
+		'Gzip::Faster' => '0.21',
 	},
 	dist       => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
 	clean      => { FILES    => 'HV-Monitor-*' },

README.md

@@ -1,12 +1,73 @@
 # HV::Monitor
 
+Provides a LibreNMS style JSON SNMP extend for monitoring HV
+info. Currently supported ones are as below.
+
+- FreeBSD: CBSD+bhyve
+- Linux: Libvirt+QEMU
+
+## Installation
+
+FreeBSD...
+
+```
+pkg install p5-App-cpanminus p5-JSON p5-MIME-Base64 p5-Gzip-Faster
+cpanm HV::Monitor
+```
+
+Debian...
+
+```
+apt-get install zlib1g-dev cpanminus libjson-perl
+cpanm HV::Monitor
+```
+
+## Usage
+
+The cron+snmpd setup is needed as even if you use sudo to make sure
+snmpd can run it, this usual time it takes this to run will result in
+in a time out.
+
+For cron...
+
+```
+*/5 * * * * /usr/local/bin/hv_monitor > /var/cache/hv_monitor.json -c 2> /dev/null
+```
+
+For snmpd...
+
+```
+extend hv-monitor /bin/cat /var/cache/hv_monitor.json
+```
+
+### FLAGS
+
+#### -b backend
+
+The backend to use.
+
+Defaults are as below.
+
+| OS      | Module  |
+|---------|---------|
+| FreeBSD | CBSD    |
+| Linux:  | Libvirt |
+
+#### -c
+
+Compress the output using gzip and base64 encoded so it can be
+transmitted via SNMP with out issue.
+
 ## JSON Return
 
 These are all relevant to `.data` in the JSON.
 
 - .VMs :: Hash of the found VMs. VM names are used as the keys. See
   the VM Info Hash Section for more information.
-- .totals :: Hash of various compiled totals stats.
+- .totals :: Hash of various compiled totals stats. This does not
+  include the disks or ifs hashes. The relevant stats are migrated
+  from the the relevant hash to the VM info hash to finally the totals
+  hash.
 
 ### VM Info Hash
 
@@ -22,7 +83,7 @@ These are all relevant to `.data` in the JSON.
 - console :: Console address and port.
 - snaps_size :: Total size of snapshots. Not available for libvirt.
 - snaps :: The number of snapshots for a VM.
-- ifs :: Interface array. The name matches `/nic[0-9]+/`.
+- ifs :: Interface hash. The name matches `/nic[0-9]+/`.
 - rbytes :: Total write bytes.
 - wbytes :: Total read bytes.
 - etimes :: Elapsed running time, in decimal integer seconds.
@@ -52,8 +113,19 @@ These are all relevant to `.data` in the JSON.
 - disk_in_use :: Number of bytes in use by by all disks.
 - disk_on_disk :: Number of bytes in use on all disks. For qcow, this
   will be larger than in_use as the file includes snapshots
+- coll :: Packet collisions.
+- ibytes :: Input bytes.
+- idrop :: Input packet drops.
+- ierrs :: Input errors.
+- ipkgs :: Input packets.
+- obytes :: Output bytes.
+- odrop :: Output packet drops.
+- oerrs :: Output errors.
+- opkts :: Output packets.
 
-The interface hash stats are as below.
+### Interface Hash
+
+The interface hash keys are as below.
 
 - if :: Interface the device is mapped to.
 - parent :: Bridge or the like the device if is sitting on.
@@ -84,7 +156,9 @@ these.
 | MAINTENANCE | 9   | Maintenance                         |
 | UNKNOWN     | 10  | Unknown                             |
 
-Disk hash is as below.
+### Disk Hash
+
+Disk hash keys is as below.
 
 - alloc :: Number of bytes allocated to a disk.
 - in_use :: Number of bytes in use by the disk.

bin/hv_monitor

@@ -1,11 +1,49 @@
 #!/usr/bin/env perl
 
+=head1 NAME
+
+hv_monitor - LibreNMS style JSON SNMP extend for hypervisor monitoring.
+
+=head1 SYNOPSIS
+
+hv_monitor [B<-c>] [B<-b> <backend>]
+
+=head1 DESCRIPTION
+
+For cron...
+
+    */5 * * * * /usr/local/bin/hv_monitor > /var/cache/hv_monitor.json -c 2> /dev/null
+
+For snmpd...
+
+    extend hv-monitor /bin/cat /var/cache/hv_monitor.json
+
+=head1 FLAGS
+
+=head2 -b <backend>
+
+The backend to use.
+
+Defaults are as below.
+
+    FreeBSD: CBSD
+    Linux: Libvirt
+
+=head2 -c
+
+Compress the output using gzip and base64 encoded so it
+can be transmitted via SNMP with out issue.
+
+=cut
+
 use JSON;
 use strict;
 use warnings;
 use Getopt::Long;
 use JSON;
 use HV::Monitor;
+use MIME::Base64;
+use Gzip::Faster;
 
 sub version {
 	print "hv_monitor v. 0.0.1\n";
@@ -17,6 +55,7 @@ sub help {
 	print '
 -b <backend>    The backend to use.
 
+-c              gzip the json and then base64 encode it
 
 
 Backends include by default...
@@ -34,8 +73,9 @@ elsif ( $^O eq 'linux' ) {
 }
 
 # get the commandline options
-my $help    = 0;
-my $version = 0;
+my $help     = 0;
+my $version  = 0;
+my $compress = 0;
 Getopt::Long::Configure('no_ignore_case');
 Getopt::Long::Configure('bundling');
 GetOptions(
@@ -44,6 +84,7 @@ GetOptions(
 	'help'    => \$help,
 	'h'       => \$help,
 	'b=s'     => \$backend,
+	'c'       => \$compress,
 );
 
 my $hm = HV::Monitor->new( { backend => $backend } );
@@ -54,4 +95,21 @@ if ($@) {
 	exit 1;
 }
 
-print encode_json($hm->run)."\n";
+my $data = encode_json( $hm->run );
+
+if ( !$compress ) {
+	print $data. "\n";
+	exit;
+}
+
+my $compressed = encode_base64( gzip($data) );
+$compressed =~ s/\n//g;
+$compressed = $compressed . "\n";
+
+# check which is smaller and prints it
+if ( length($compressed) > length($data) ) {
+	print $data;
+}
+else {
+	print $compressed;
+}