/ 
OSLV-Monitor-1.0.2
River stage zero No dependents
/ README.md

OSLV-Monitor

OS level virtualization monitoring extend for LibreNMS

Install

FreeBSD

pkg install p5-JSON p5-Mime-Base64 p5-Clone p5-File-Slurp p5-IO-Interface
perl Makefile.pl
make
make test
make install

or...

pkg install p5-JSON p5-Mime-Base64 p5-Clone p5-File-Slurp p5-IO-Interface p5-App-cpanminus
cpanm OSLV::Monitor

Debian

apt-get install libjson-perl libclone-perl libmime-base64-perl libfile-slurp-perl libio-interface-perl
perl Makefile.pl
make
make test
make install

or...

apt-get install libjson-perl libclone-perl libmime-base64-perl libfile-slurp-perl libio-interface-perl cpanminus
cpanm OSLV::Monitor

Setup

For cron...

*/5 * * * * /usr/local/bin/oslv_monitor -q

For snmpd...

extend oslv_monitor /bin/cat /var/cache/oslv_monitor/snmp

See oslvm_monitor -h for more information.

Config File

The default location for the optional config file is /usr/local/etc/oslv_monitor.json.

The following keys are used in the JSON config file.

- include :: A array of regular expressions to include.
    Default :: ["^.*$"]

- exlcude :: A array of regular expressions to exlclude.
    Default :: undef

- backend :: Override the the backend and automatically choose it.

- time_divider :: Override the time_divider value. The default value varies
    per backend and if it is needed.

Time divider notes.

- cgroups :: While the default for usec to sec conversion should be 1000000,
          some settings report the value in nanoseconds, requiring 1000000000.
    Default :: 1000000

- FreeBSD :: not used

By Defaults the backends are as below.

Default would be like this.

{
    "include": ["^.*$"]
}

Stats

| Path | Description | |---------------------|------------------------------------------------------------------| | .data.backend | The backend used. | | .data.oslvms | A hash of OSLVMs found containing the stats for each one. | | .data.oslvms..ip | A array of IP information OSLVM. Detailed below. | | .data.oslvms..path | A array of paths for the OSLVM. | | .data.totals | A hash of the totals of the values for the OSLVMs. | | .data.has.* | A hash of variables with a 0/1 boolean for what data is present. |

The IP information is as below. Each item in the array with the hashes below.

| Variable | Description | |----------|-----------------------------------------------------------| | ip | The IP address. | | if | The interface for the IP. | | gw | The gateway IP that will be used for it. | | gw_if | The interface that will be used for reaching the gateway. |

The has hash is used for telling LibreNMS if a specific set of graphs should be displayed or not.

| Variable | Description | |-----------------|--------------------------------------------------| | linux_mem_stats | Has stuff from memory.stat for Linux cgroups v2. | | rwdops | Has read/write/discard op vars. | | rwdbytes | Has read/write/discard bytes vars. | | rwdblocks | Has read/write/discard blocks vars. | | signals-taken | Has signals taken info for procs. | | stack-size | Has stack size info for procs. | | cows | Has COW fault vars. | | swaps | Has meaningful info on swap in/out. | | sock | Has socket buffer size info. |

FreeBSD Stats

The stats names match those produced by "ps --libxo json".

Linux cgroup v2 Stats

The cgroup to name mapping is done like below.

systemd -> s_$name
user -> u_$name
docker -> d_$name
podman -> p_$name
anything else -> $name

Anything else is formed like below.

$cgroup =~ s/^0\:\:\///;
$cgroup =~ s/\/.*//;

The following ps to stats mapping are as below.

"procs" is a total number of procs in that cgroup.

The rest of the values are pulled from the following files with the names kept as is.

The following mappings are done though.

pgfault -> minor-faults
pgmajfault -> major-faults
usage_usec -> cpu-time
system_usec -> system-time
user_usec -> user-time
throttled_usec -> throttled-time
burst_usec -> burst-time
core_sched.force_idle_usec -> core_sched.force_idle-time