psyinfra / prometheus-eaton-ups-exporter

A Prometheus exporter for (some) Eaton UPSs

Eaton UPS Prometheus Exporter

Description

A Prometheus exporter for Eaton UPSs. Data is collected from the REST API of the web UI of Eaton UPSs and is made available for Prometheus to scrape.

The exporter can monitor multiple UPSs.

Information Exported

• Input Voltage (V)
• Input Frequency (Hz)
• Output Voltage (V)
• Output Frequency (Hz)
• Output Current (A)
• Output Apparent Power (VA)
• Output Active Power (W)
• Output Power Factor
• Output Percent Load (%)
• Battery Voltage (V)
• Battery Capacity (%)
• Battery Remaining Time (s)
• Battery Health Status (given as the remaining lifetime in years [uncertain, contribute to #19])

Supported Devices:

• Eaton 5P 1550iR (user guide)
• Other models may also work if they use the same API

Usage:

UPSs to monitor and their credentials are defined in a config file. See config.json for an example.

./prometheus_eaton_ups_exporter.py [-h] [-w WEB.LISTEN_ADDRESS] -c CONFIG [-k] [-t] [-v] [--login-timeout {range 2 - 10}]


optional arguments:
  -h, --help            show this help message and exit
  -w WEB.LISTEN_ADDRESS, --web.listen-address WEB.LISTEN_ADDRESS
                        Interface and port to listen on, in the format of "ip_address:port".
                        If the IP is omitted, the exporter listens on all interfaces. (default: 0.0.0.0:9795)
  -c CONFIG, --config CONFIG
                        Configuration JSON file containing UPS addresses and login info (default: None)
  -k, --insecure        Allow the exporter to connect to UPSs with self-signed SSL certificates (default: False)
  -t, --threading       Whether to use multi-threading for scraping (faster) (default: False)
  -v, --verbose         Be more verbose (default: False)
  --login-timeout {range 2 - 10}
                        The login timeout for the UPSs in seconds (default: 3)

Defaults:

• Default host-address is 0.0.0.0
• Default port is 9795 (see also: Prometheus default port allocations)
• Login timeout is set to 3 seconds
• Other request timeouts are set to 2 seconds
• Static values are described in prometheus_eaton_ups_exporter/scraper_globals.py

Requirements:

• requests
• prometheus_client

Installation:

git clone https://github.com/psyinfra/prometheus-eaton-ups-exporter.git
cd prometheus-eaton-ups-exporter
pip install -r requirements.txt

Testing:

Install requirements with

pip install -r test-requirements.txt

Runt tests with

pytest tests

Test-Requirements:

• pytest
• pytest-vcr

prometheus-eaton-ups-exporter's Issues

combine --port and --host-address

The ip:port syntax is common, and allows this to be exposed as a single option.

In the Prometheus community, the flag is usually called --web.listen-address.

For example:

--web.listen-address=":9290"

regression: --web.listen-address no longer allows listening on all interfaces

The following syntax used to result in the exporter listening on all network interfaces:

--web.listen-address :9790"

In the new release, it results in listening on 127.0.0.1.

Missing files

Can you add a LICENSE and requirements.txt file? It's probably also best to put the entry point in the root folder (i.e., eaton_ups_exporter.py (because exporter/prometheus_api_exporter.py could be more descriptive).

User-Agent should not be spoofed

In scraper_globals.py, the headers for both LOGIN_ and AUTH_ are hardcoded. It is considered poor form to spoof the headers unnecessarily.

Unless they are sniffing for user agents (which would be worthy of a snarky comment in the source code), nothing in those headers looks atypical. Ideally, they can all be removed and the defaults used.

HELP strings should be more... helpful

Currently they're all the same:

Measure collected from the ups device

https://prometheus.io/docs/instrumenting/writing_exporters/#help-strings

percent should be "ratio"

Prometheus best practice is to use "ratio": rather than percent. https://prometheus.io/docs/practices/naming/#base-units

The field names should be updated to end in _ratio rather than _percent. And the values should be changed accordingly.

Multi threading

Exporter not working on UPS Firmware 2.0.5

I stumbled upon this today, I have 3 of the same UPS's with all the same network card.

2x of my UPS's are on Network Card Firmware 1.7.5 with one of them on 2.0.5 somehow, this error appears on my UPS with the 2.0.5 Firmware, suggesting Eaton changed something somewhat recently with the way input measures are called upon.
Unfortunately I'm not well versed enough to figure out what causes the issue, although it may be possible to upgrade your firmware to 2.0.5 and figure it out for yourself. There is also a 3.0 version firmware, seems they really did support this product decently!

For anyone reading this, do not upgrade your Firmware if you wish to keep using this amazing exporter, thanks for making it! (:

Originally posted by @Randommmm in #22 (comment)

Create setup.py with entry points

Remove `urllib3` dependency for `requests` functionality

Removing the unnecessary dependency should be addressed in a future PR.

Out of scope, but this dependency is used in one place, and simply to disable SSL verification.

requests supports this feature directly. https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

Originally posted by @aqw in #27 (comment)

select a default/suggested port

Prometheus maintains a list of ports that exporters use, to help avoid conflicts.
https://github.com/prometheus/prometheus/wiki/Default-port-allocations

I recommend choosing a free one and using that in the docs.

You can also choose to register it with upstream, if you wish.

Integrate tests

To quote @nhjjreuter :

I recommend getting rid of the input and getpass parts. Tests should be automated. 
Instead, use either an .env file (and then import os; os.environ.get('eaton_ups_username')), 
or a .config.json/yaml file that you likewise draw your data from. Then just put the file with the password data in .gitignore

rename repo to prometheus-eaton-ups-exporter

This will follow common norms in the Prometheus community, and will also make clear that only Eaton UPSs are targeted.

document values of battery health (if possible)

Right now it's a 5.0. I have no idea if that means healthy or actively on fire. ;-)

exporter returns error when a UPS is unreachable

I am monitoring three UPSs. When one became unavailable (the network between the exporter and one of the UPSs went down), the exporter waited for 7 seconds and then returns this following error:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
        <title>Error response</title>
    </head>
    <body>
        <h1>Error response</h1>
        <p>Error code: 500</p>
        <p>Message: error generating metric output.</p>
        <p>Error code explanation: 500 - Server got itself in trouble.</p>
    </body>
</html>

It would be preferable if the exporter had an overall timeout (5-10 seconds), and any UPS that has responded by then is included in the metric output. That way one unreachable UPS doesn't halt reporting for all others. This feature would likely require #3.

Problem

Hello,
When I run the script, I get this error:

Do you have any ideas to help me ? I have the Eaton Network Card-M2.

Have a nice day :)

add automated credential removal for casettes to tests

The test-casettes are not allowed to contain credentials.
By default the casettes are created with the information, which then has to be removed by hand, which is either not save or takes a lot of time to be sure that nothing gets accidently pushed.

This process needs be automated to ensure that no critical information is shared.

"health status" value reported by UPS is unclear (help wanted)

The health status is likely the remaining lifetime of the single UPS's based on:

https://www.eaton.com/content/dam/eaton/products/backup-power-ups-surge-it-power-distribution/backup-power-ups/eaton-ups-battery-tech-brief-bat14fxa.pdf

The relevant information found in this document that lead to an interpretation of the health status:

• (Section 7 on page 3)

  7. What is the average lifespan of UPS batteries?
  
  The standard lifespan for VRLA batteries is three to five years; for
  wet-cell batteries it’s up to 20 years. However, expected life can
  vary greatly due to environmental conditions, number and depth
  of discharge cycles, and adequate maintenance. Having a regular
  schedule of battery maintenance and monitoring will ensur
  

• (Grey highlighted text on page 3)

  Although batteries are sold with a variety of published life
  spans, the fact is, some demonstrate a useful life of as little
  as three to five years. Eaton’s exclusive ABM tech