Add a python plugin for monitoring power supplies on Linux. (#3799)

* Add a python plugin for monitoring power supplies on Linux.

This adds a python-based module for tracking statistics relating to
Linux kernel power_supply class devices.  This allows tracking battery
statistics on Linux systems, as well as (in theory) other energy storage
devices that utilize the kernel's power_supply class.

The primary purpose of this module is twofold:

- To provide a way for battery powered IoT devices to easily alert about a
low battery.
- To provide a way for all battery powered devices to alert on some easy
to monitor battery health conditions.

It provides up to four charts, one which provides the remaining capacity
as a percentage, and three others which report info about charge (in
amp-hours), energy (in watt-hours), and voltage, each providing info
about the current values, and possibly minimal and maximal values that
can be used for computing battery life.

Exact support provided by each individual device varies.  Almost all
provide the percentage capacity, but beyond that they may or may not
support any or all of the attributes needed for the other three charts
(ACPI compliant systems for example support most of the charge related
ones, and two of the voltage related values, but none of the energy
related ones).

Data collection is done by scanning entries in /sys/class/power_supply.
One job must be created for each power supply to be monitored, and there
is no autodetection (though the config includes an example that should
work to monitor the main battery on most laptops).

* Fix the build.

* Fix one bug and various style issues.

* Add a check to make sure it only runs on Linux.

* Fixed formatting issues reported by flake8.

* Updated to only collect capacity by default.

* Add an alarm to alert on low battery.

* Update function names to not be sunder style.

* Split chart generation to a separate function.

* Remove get_sysfs_value_or_zero.

1 files changed, 68 insertions, 0 deletions

diff --git a/python.d/README.md b/python.d/README.md
index 10c15295b1..3ce63cf30c 100644
--- a/python.d/README.md
+++ b/python.d/README.md
@@ -1039,6 +1039,74 @@ The module will not work If no configuration is given.
 
 ---
 
+# linux\_power\_supply
+
+This module monitors variosu metrics reported by power supply drivers
+on Linux.  This allows tracking and alerting on things like remaining
+battery capacity.
+
+Depending on the uderlying driver, it may provide the following charts
+and metrics:
+
+1. Capacity: The power supply capacity expressed as a percentage.
+  * capacity\_now
+
+2. Charge: The charge for the power supply, expressed as microamphours.
+  * charge\_full\_design
+  * charge\_full
+  * charge\_now
+  * charge\_empty
+  * charge\_empty\_design
+
+3. Energy: The energy for the power supply, expressed as microwatthours.
+  * energy\_full\_design
+  * energy\_full
+  * energy\_now
+  * energy\_empty
+  * energy\_empty\_design
+
+2. Voltage: The voltage for the power supply, expressed as microvolts.
+  * voltage\_max\_design
+  * voltage\_max
+  * voltage\_now
+  * voltage\_min
+  * voltage\_min\_design
+
+### configuration
+
+Sample:
+
+```yaml
+battery:
+  supply: 'BAT0'
+  charts: 'capacity charge energy voltage'
+```
+
+The `supply` key specifies the name of the power supply device to monitor.
+You can use `ls /sys/class/power_supply` to get a list of such devices
+on your system.
+
+The `charts` key is a space separated list of which charts to try
+to display.  It defaults to trying to display everything.
+
+### notes
+
+* Most drivers provide at least the first chart.  Battery powered ACPI
+compliant systems (like most laptops) provide all but the third, but do
+not provide all of the metrics for each chart.
+
+* Current, energy, and voltages are reported with a _very_ high precision
+by the power\_supply framework.  Usually, this is far higher than the
+actual hardware supports reporting, so expect to see changes in these
+charts jump instead of scaling smoothly.
+
+* If `max` or `full` attribute is defined by the driver, but not a
+corresponding `min or `empty` attribute, then netdata will still provide
+the corresponding `min` or `empty`, which will then always read as zero.
+This way, alerts which match on these will still work.
+
+---
+
 # litespeed
 
 Module monitor litespeed web server performance metrics.