Add apcupsd_ups_status and apcupsd_ups_info metrics #8

jangrewe · 2019-05-24T18:29:41Z

This adds multiple apcupsd_ups_status metrics, each containing the label status with all possible values the STATUS: line can contain. (Label values taken from https://www.systutorials.com/docs/linux/man/8-apcaccess/)

This also add the apcupsd_ups_info metric and moves all the redundant info labels from the other metrics to this one (as suggested by you in #6).

And lastly this PR adds an example Grafana dashboard and the respective screenhot.

Added bonus: a Dockerfile (image size: 8MB), with the image available at https://hub.docker.com/r/jangrewe/apcupsd-exporter

…ATUS:`.

jangrewe · 2019-05-27T23:36:04Z

@mdlayher Any chance you could have a look at this PR? I'm sorry that it got a bit out of hand, but i think it's worth it! 😄

mdlayher · 2019-05-29T14:46:07Z

Thank you for the PR and I appreciate the effort you've put in, but this PR has a lot of unrelated changes that make it difficult to review quickly.

My free time is rather limited this week. I'll try to get to this early next week.

mdlayher · 2019-06-03T20:05:03Z

.gitignore

@@ -0,0 +1,2 @@
+.idea


Please add these to your global gitignore instead.

mdlayher · 2019-06-03T20:05:44Z

README.md

+
+You can find the dashboard JSON in the `grafana` folder.
+
+![sample](https://raw.githubusercontent.com/jangrewe/apcupsd_exporter/master/grafana/screenshot.png)


This would need to reflect the path of the upstream repository.

mdlayher · 2019-06-03T20:06:05Z

go.sum

@@ -1,19 +1,55 @@
-github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973 h1:xJ4a3vCFaGF/jqvzLMYoU8P317H5OQ+Via4RmuPwCS0=


Seems like a lot of churn, did you go mod tidy too?

mdlayher · 2019-06-03T20:07:53Z

upscollector.go

@@ -41,105 +44,119 @@ var _ prometheus.Collector = &UPSCollector{}
 // NewUPSCollector creates a new UPSCollector.
 func NewUPSCollector(ss StatusSource) *UPSCollector {
 	var (
-		labels = []string{"hostname", "ups_name", "model"}
+		infoLabels = []string{"hostname", "ups_name", "model"}


Move these to package level so they can be deduplicated at this point.

mdlayher · 2019-06-03T20:08:33Z

upscollector.go

+
+		UPSInfo: prometheus.NewDesc(
+			prometheus.BuildFQName(namespace, "", "ups_info"),
+			"Hostname, UPS Model and Name.",


"Metadata about a UPS."

More flexible for the future.

mdlayher · 2019-06-03T20:10:57Z

upscollector.go

+			nil,
+		),
+
+		UPSStatus: prometheus.NewDesc(


I feel like it would make more sense to include the status label in UPSInfo rather than in its own metric.

candlerb · 2019-06-16T20:32:21Z

Just a note to say that I have tested from the @jangrewe repo, and it works for me:

apcupsd_apcupsd_nominal_power_watts 390
apcupsd_battery_charge_percent 100
apcupsd_battery_cumulative_time_on_seconds_total 0
apcupsd_battery_nominal_volts 12
apcupsd_battery_number_transfers_total 0
apcupsd_battery_time_left_seconds 4602
apcupsd_battery_time_on_seconds 0
apcupsd_battery_volts 13.4
apcupsd_line_nominal_volts 230
apcupsd_line_volts 240
apcupsd_ups_info{hostname="nuc2",model="Back-UPS XS 700U",ups_name="bx700"} 1
apcupsd_ups_load_percent 3
apcupsd_ups_status{status="BOOST"} 0
apcupsd_ups_status{status="CAL"} 0
apcupsd_ups_status{status="COMMLOST"} 0
apcupsd_ups_status{status="LOWBATT"} 0
apcupsd_ups_status{status="NOBATT"} 0
apcupsd_ups_status{status="ONBATT"} 0
apcupsd_ups_status{status="ONLINE"} 1
apcupsd_ups_status{status="OVERLOAD"} 0
apcupsd_ups_status{status="REPLACEBATT"} 0
apcupsd_ups_status{status="SHUTTING DOWN"} 0
apcupsd_ups_status{status="SLAVE"} 0
apcupsd_ups_status{status="SLAVEDOWN"} 0
apcupsd_ups_status{status="TRIM"} 0

I am ambivalent, however, about the loss of metadata from the individual metrics.

Including metadata in every metric is how the official snmp_exporter works. Example:

# HELP ifHCInOctets The total number of octets received on the interface, including framing characters - 1.3.6.1.2.1.31.1.1.1.
6
# TYPE ifHCInOctets counter
ifHCInOctets{ifAlias="",ifDescr="bridge",ifIndex="14",ifName="bridge"} 6.343343949e+09
ifHCInOctets{ifAlias="",ifDescr="ether1",ifIndex="16",ifName="ether1"} 2.4808641625e+10
ifHCInOctets{ifAlias="",ifDescr="ether2",ifIndex="2",ifName="ether2"} 0
ifHCInOctets{ifAlias="",ifDescr="ether3",ifIndex="3",ifName="ether3"} 6.083273145e+09
ifHCInOctets{ifAlias="",ifDescr="ether4",ifIndex="4",ifName="ether4"} 6.79593826e+08
ifHCInOctets{ifAlias="",ifDescr="ether5",ifIndex="5",ifName="ether5"} 2.91243382e+08
ifHCInOctets{ifAlias="",ifDescr="pppoe-out1",ifIndex="17",ifName="pppoe-out1"} 2.4255138238e+10
...
# HELP ifHCOutOctets The total number of octets transmitted out of the interface, including framing characters - 1.3.6.1.2.1.31.1.1.1.10
# TYPE ifHCOutOctets counter
ifHCOutOctets{ifAlias="",ifDescr="bridge",ifIndex="14",ifName="bridge"} 2.5131203193e+10
ifHCOutOctets{ifAlias="",ifDescr="ether1",ifIndex="16",ifName="ether1"} 5.096503509e+09
ifHCOutOctets{ifAlias="",ifDescr="ether2",ifIndex="2",ifName="ether2"} 0
ifHCOutOctets{ifAlias="",ifDescr="ether3",ifIndex="3",ifName="ether3"} 1.0343428154e+10
ifHCOutOctets{ifAlias="",ifDescr="ether4",ifIndex="4",ifName="ether4"} 1.4271999034e+10
ifHCOutOctets{ifAlias="",ifDescr="ether5",ifIndex="5",ifName="ether5"} 4.11163912e+09
ifHCOutOctets{ifAlias="",ifDescr="pppoe-out1",ifIndex="17",ifName="pppoe-out1"} 4.764235347e+09

This in turn makes it very easy to use in grafana dashboards, with all of the graph lines labelled with the available metadata, and easy to filter on any particular piece of metadata.

If they changed it to work the way proposed here, then it would look more like this:

ifIndex{ifAlias="",ifDescr="bridge",ifIndex="14",ifName="bridge"} 1
ifIndex{ifAlias="",ifDescr="ether1",ifIndex="16",ifName="ether1"} 1
ifIndex{ifAlias="",ifDescr="ether2",ifIndex="2",ifName="ether2"} 1
ifIndex{ifAlias="",ifDescr="ether3",ifIndex="3",ifName="ether3"} 1
ifIndex{ifAlias="",ifDescr="ether4",ifIndex="4",ifName="ether4"} 1
ifIndex{ifAlias="",ifDescr="ether5",ifIndex="5",ifName="ether5"} 1
ifIndex{ifAlias="",ifDescr="pppoe-out1",ifIndex="17",ifName="pppoe-out1"} 1
...
ifHCInOctets{ifIndex="14"} 6.343343949e+09
ifHCInOctets{ifIndex="16"} 2.4808641625e+10
ifHCInOctets{ifIndex="2"} 0
ifHCInOctets{ifIndex="3"} 6.083273145e+09
ifHCInOctets{ifIndex="4"} 6.79593826e+08
ifHCInOctets{ifIndex="5"} 2.91243382e+08
ifHCInOctets{ifIndex="17"} 2.4255138238e+10
...
ifHCOutOctets{ifIndex="14"} 2.5131203193e+10
ifHCOutOctets{ifIndex="16"} 5.096503509e+09
ifHCOutOctets{ifIndex="2"} 0
ifHCOutOctets{ifIndex="3"} 1.0343428154e+10
ifHCOutOctets{ifIndex="4"} 1.4271999034e+10
ifHCOutOctets{ifIndex="5"} 4.11163912e+09
ifHCOutOctets{ifIndex="17",ifName="pppoe-out1"} 4.764235347e+09

This has some advantages with regards to continuity of timeseries if metadata changes, but seems to be a lot harder to work with in grafana.

Let's consider the simpler case of apcupsd with this proposed patch applied. Suppose you have multiple UPSes, and are showing all the "time remaining" in a single graph with a separate line for each UPS. Once prometheus has added its own scraping labels, you would get metrics like this:

apcupsd_ups_info{job="apcupsd",instance="192.0.2.1",hostname="nuc1",model="Back-UPS XS 700U",ups_name="bx700-1"} 1
apcupsd_battery_time_left_seconds{job="apcupsd",instance="192.0.2.1",status="ONLINE"} 4062
...
apcupsd_ups_info{job="apcupsd",instance="192.0.2.2",hostname="nuc2",model="Back-UPS XS 700U",ups_name="bx700-2"} 1
apcupsd_battery_time_left_seconds{job="apcupsd",instance="192.0.2.2",status="ONLINE"} 3950

If you want your graphs labelled with the UPS name or hostname, you need to invoke some prometheus join magic. According to this article I think that adding the ups_name to the apcupsd_battery_time_left_seconds metric might look something like this:

apcupsd_battery_time_left_seconds * on (instance, job) group_left(ups_name) apcupsd_ups_info

I don't pretend to understand this, and it may be wrong. In any case it would have to be copy-pasted into every grafana query in the dashboard.

Similarly: suppose you want a drop-down menu to select between UPSes. If you don't mind just showing the 'instance' value this is straightforward:

Dashboard variable 'instance' = label_values(apcupsd_ups_info, instance)
Query: apcupsd_battery_time_left_seconds{instance="$instance"}

But if you want the dropdown to select on 'ups_name', it gets tricky.

Dashboard variable 'ups_name' = label_values(apcupsd_ups_info, ups_name)
Query: apcupsd_battery_time_left_seconds * on (instance, job) group_left(ups_name) apcupsd_ups_info{ups_name="$ups_name"} ???

candlerb · 2019-07-05T13:06:43Z

I am ambivalent, however, about the loss of metadata from the individual metrics.

Including metadata in every metric is how the official snmp_exporter works.

For reference, discussion about it at prometheus/snmp_exporter#180 and prometheus/snmp_exporter#339

mdlayher · 2020-05-18T20:15:05Z

I ended up fixing things up, thanks for your time.

crockk · 2021-07-22T21:36:45Z

Can this be revisited? It would be very useful to have status info in the metrics, or as a label in apcupsd_info. I made an issue pertaining to it:
#19

candlerb · 2021-07-23T07:17:22Z

FWIW, I changed to https://github.com/damomurf/apcupsd-exporter a while ago.

crockk · 2021-07-27T19:15:58Z

Fair enough, but I need both status metrics and the metrics that this exporter provides... Both exporters use the same command line tool so it seems a bit silly to be installing two exporters for the same tool 😅

jangrewe added 5 commits May 24, 2019 20:23

Add apcupsd_ups_status metric with status label for values of `ST…

d3584f7

…ATUS:`.

add Dockerfile

65504a0

Add example dashboard for Grafana

8b90b9c

add dashboard screenshot

7ba195d

Move UPS info labels to separate metric apcupsd_ups_info

aefc089

jangrewe mentioned this pull request May 24, 2019

apcupsd_exporter: move hostname, model, and ups_name labels to an info metric #6

Closed

update prometheus/client_golang to v0.9.3

99fbe0f

jangrewe changed the title ~~Add apcupsd_ups_status metric~~ Add apcupsd_ups_status and apcupsd_ups_info metrics May 24, 2019

oops

699febe

mdlayher requested changes Jun 3, 2019

View reviewed changes

mdlayher closed this May 18, 2020

crockk mentioned this pull request Jul 27, 2021

Metrics for UPS status #16

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add apcupsd_ups_status and apcupsd_ups_info metrics #8

Add apcupsd_ups_status and apcupsd_ups_info metrics #8

jangrewe commented May 24, 2019 •

edited

Loading

jangrewe commented May 27, 2019

mdlayher commented May 29, 2019

mdlayher Jun 3, 2019

mdlayher Jun 3, 2019

mdlayher Jun 3, 2019

mdlayher Jun 3, 2019

mdlayher Jun 3, 2019

mdlayher Jun 3, 2019

candlerb commented Jun 16, 2019

candlerb commented Jul 5, 2019

mdlayher commented May 18, 2020

crockk commented Jul 22, 2021 •

edited

Loading

candlerb commented Jul 23, 2021

crockk commented Jul 27, 2021


		You can find the dashboard JSON in the `grafana` folder.

		![sample](https://raw.githubusercontent.com/jangrewe/apcupsd_exporter/master/grafana/screenshot.png)

		@@ -1,19 +1,55 @@
		github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973 h1:xJ4a3vCFaGF/jqvzLMYoU8P317H5OQ+Via4RmuPwCS0=

Add apcupsd_ups_status and apcupsd_ups_info metrics #8

Add apcupsd_ups_status and apcupsd_ups_info metrics #8

Conversation

jangrewe commented May 24, 2019 • edited Loading

jangrewe commented May 27, 2019

mdlayher commented May 29, 2019

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

mdlayher Jun 3, 2019

Choose a reason for hiding this comment

candlerb commented Jun 16, 2019

candlerb commented Jul 5, 2019

mdlayher commented May 18, 2020

crockk commented Jul 22, 2021 • edited Loading

candlerb commented Jul 23, 2021

crockk commented Jul 27, 2021

jangrewe commented May 24, 2019 •

edited

Loading

crockk commented Jul 22, 2021 •

edited

Loading