NUT - Network UPS Tools Plug-in

[mcindea]

Feature Request

Hello guys,

I'm just curious if you have any plans in creating a plugin for NUT ? Similar to what you did for #2877

Proposal:

I volunteer to create it myself, but I'm new to Go, so I would need your support reviewing the code and most possibly also share the procedures you have for this kind of situations? i.e. Best practices or some docs about writing plugins.
Thanks!

Current behavior:

Currently only a plugin for APCUPCd exists.

Desired behavior:

Would be nice if a plugin for NUT exists, which offers a broader compatibility with UPS hardware.

Use case:

Currently I use Telegraf for my UnRaid setup, which monitors everything, and built a custom Docker container script which gathers data and sends it to InfluxDB. Another solution is to use an Exec, but that also requires having NUT installed in the Alpine container where Telegraf is. Therefore I would like a plugin, which doesn't have any external dependencies.

[danielnelson]

This would be nice to have. I looked very briefly at the NUT documentation, do you think the plugin would operate similar to the upsc command?

[mcindea]

Yes, as a matter of fact the python script I built uses the same uspc command.

[danielnelson]

Would be nice to get an idea of how some actual data looks, could you show the output of your script?

I believe this is the documentation for connecting to upsd: https://networkupstools.org/docs/developer-guide.chunked/ar01s09.html

[mcindea]

Sure, but it's it's not fully relevant since currently I just adapted a python script that was built for APCUPCd, so currently the fields match what APC would output:

[{'fields': {'STATUS': u'OL', 'WATTS': 90.0, 'TIMELEFT': 3570.0, 'BCHARGE': 100.0, 'LOADPCT': 10.0, 'BATTV': 24.0, 'OUTPUTV': 260.0, 'NOMPOWER': 900.0}, 'tags': {'ups_alias': 'ups', 'host': 'Tower', 'serial': u'CRMJP2000104'}, 'measurement': 'ups_status'}]

Just for reference, BCHARGE is actually battery.charge on UPS Cyberpower and similar BATTV is battery.voltage.
Since I can't test other UPS equipments, I would want to make it dynamic, just output the fields it gets. Of course, after proper filtering so we make sure nothing malicious gets stored in the DB.

Thinking about it I think it's better if I just show you the upsc output:

root@Tower:~# upsc ups@localhost
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 20
battery.mfr.date: CPS
battery.runtime: 3720
battery.runtime.low: 300
battery.type: PbAcid
battery.voltage: 24.0
battery.voltage.nominal: 24
device.mfr: CPS
device.model: CP1500EPFCLCD
device.serial: CRMJP2000104
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.synchronous: no
driver.version: 2.7.4.1
driver.version.data: CyberPower HID 0.5
driver.version.internal: 0.53
driver.version.usb: libusb-1.0.22 (API: 0x1000106)
input.transfer.high: 260
input.transfer.low: 170
input.voltage: 225.0
input.voltage.nominal: 230
output.voltage: 260.0
ups.beeper.status: enabled
ups.delay.shutdown: 20
ups.delay.start: 30
ups.load: 10
ups.mfr: CPS
ups.model: CP1500EPFCLCD
ups.productid: 0501
ups.realpower.nominal: 900
ups.serial: CRMJP2000104
ups.status: OL
ups.test.result: No test initiated
ups.timer.shutdown: -60
ups.timer.start: -60
ups.vendorid: 0764
root@Tower:~# 

[danielnelson]

I wonder how standardized these stats are, is there a list of possible stats? Likely we would want a plugin to connect to upsd and list all stats and then for each stat we would check a list of known stats to determine if the stat should be saved as a tag/field.

If a stat is unknown we could either ignore the stat or add it based on the observed type:

• 2.0 -> float
• 2 -> int
• default: string

If we find the use of a decimal point is not consistent, we may want to always store as float. I would think that the memcached plugin is the closest in style to what we would want here.

[mcindea]

That's a very good idea. I'll have to dig into this a bit more. I found upsrw, which does something like that, but only for config variables that can be changed by the user and not actual log data.

[battery.charge.low]
Remaining battery level when UPS switches to LB (percent)
Type: STRING
Maximum length: 10
Value: 10

[battery.runtime.low]
Remaining battery runtime when UPS switches to LB (seconds)
Type: STRING
Maximum length: 10
Value: 300

[input.transfer.high]
High voltage transfer point (V)
Type: STRING
Maximum length: 10
Value: 260

[input.transfer.low]
Low voltage transfer point (V)
Type: STRING
Maximum length: 10
Value: 170

[ups.delay.shutdown]
Interval to wait after shutdown with delay command (seconds)
Type: STRING
Maximum length: 10
Value: 20

[ups.delay.start]
Interval to wait before (re)starting the load (seconds)
Type: STRING
Maximum length: 10
Value: 30

root@Tower:~#

Also found something we could use to replace upsc which polls every 30 seconds by default, but unfortunately it doesn't say anything about types. The format appears to be universal, so I don't think it's tied to the vendor type. Especially if you look at the last 2 columns, ups.temperature and input.frequency. They're NA because I don't have those sensors.

root@Tower:~# upslog  -s ups@localhost -l - -f "%TIME @Y@m@d @H@M@S% %VAR battery.charge% %VAR battery.runtime% %VAR ups.realpower.nominal% %VAR battery.voltage% %VAR output.voltage% %VAR input.voltage% %VAR ups.load%  [%VAR ups.status%] %VAR ups.temperature% %VAR input.frequency%"
Network UPS Tools upslog 2.7.4.1
logging status of ups@localhost to - (30s intervals)
20190829 073621 100 3480 900 24.0 260.0 225.0 11  [OL] NA NA
20190829 073651 100 3330 900 24.0 260.0 224.0 11  [OL] NA NA

EDIT: I looked into it and they have quite complex documentation about this:
https://networkupstools.org/docs/developer-guide.chunked/apas01.html

To be honest there are more than I expected and I'm curious how much of them my UPS actually supports so I can actually test them.

Thanks for the tip about memcached, I''ll look into that.

[sjwang90]

Hi @kiwimato, just checking if you have any update in looking into referencing thememcached plugin for the NUT plugin you're working on. Just looking into prioritizing plugins for future feature releases. Please respond if you have any questions!

[mcindea]

Hello @sjwang90, unfortunately I didn't enough time to start work on it and my server where I had this setup crashed in the meantime, so I won't be able to work on it until I will fix it.
I did however write a python script which I planned to use as PoC before I planned to work on this. If you guys have more time than me or might find it useful you can find it here - it's fully tested and it works.
Please keep me updated. I find it really awesome that you are guys are interested in it!

[Styx13]

Hello @kiwimato , do you still plan to create this nut plugin for telegraf ?

I too am using nut for my UPS management and monitoring, and I would love to be able to send the metrics to influxdb/grafana using telegraf.

[mcindea]

Hey @Styx13, to be honest I didn't have time to yet and for my use case i created a workaround: https://github.com/kiwimato/nut-influxdb-exporter

I still plan to work on it at some point, but don't have an ETA at this point.

[lmondoux]

Just wanted to say it would be great if there was a NUT telegraf input!

[donmueang]

Is there any known update on this? Would like to have Telegram scraping data from the NUT instance running on another server. Not planning to switch over to apcupcd.