Modbus exporter

Prometheus exporter which retrieves stats from a modbus tcp system and exports them via HTTP for Prometheus consumption.

Scrape sequence

Reproduce diagram

Go to: https://bramp.github.io/js-sequence-diagrams/ ``` Note right of Prometheus: prometheus.yml \n --- \n target: Modbus-TCP-10.0.0.5 \n sub_target: Modbus-Unit-10 \n module: VendorXY Prometheus->Exporter: http://xxx.de/modbus?target=10.0.0.5&sub_target=10&module=vendorxy Note right of Exporter: modbus.yml \n --- \n module: VendorXY \n - temperature_a: 400001 \n - temperature_b: 400002 Exporter->Modbus_TCP_10.0.0.5: tcp://10.0.0.5?unit=10®ister=400001 Modbus_TCP_10.0.0.5->Modbus_RTU_10: rtu://_?register=400001 Modbus_RTU_10-->Modbus_TCP_10.0.0.5: value=20 Modbus_TCP_10.0.0.5-->Exporter: value=20 Exporter->Modbus_TCP_10.0.0.5: tcp://10.0.0.5?unit=10®ister=400002 Modbus_TCP_10.0.0.5->Modbus_RTU_10: rtu://_?register=400002 Modbus_RTU_10-->Modbus_TCP_10.0.0.5: value=19 Modbus_TCP_10.0.0.5-->Exporter: value=19 Exporter-->Prometheus:temperature_a{module="VendorXY",sub_target="10"} 20 \ntemperature_b{module="VendorXY",sub_target="10"} 19 ```

Building

Prerequisite packages:

make
go (called golang at some package managers)

Run:

make build

Getting Started

The modbus exporter can be tested standalone, but should be added as a target in your Prometheus config.

Prometheus needs the following labels parsed by the modbus exporter: target (including port), module and sub_module as parameters, this can be done with relabelling as shown in the example prometheus.yml.

Once Prometheus is properly configured, run the exporter via:

./modbus_exporter [flags]

Supported flags:

usage: modbus_exporter [<flags>]

Flags:
  -h, --[no-]help                Show context-sensitive help (also try
                                 --help-long and --help-man).
      --config.file=modbus.yml ...  
                                 Sets the configuration file.
      --[no-]web.systemd-socket  Use systemd socket activation listeners instead
                                 of port listeners (Linux only).
      --web.listen-address=:9602 ...  
                                 Addresses on which to expose metrics and web
                                 interface. Repeatable for multiple addresses.
      --web.config.file=""       [EXPERIMENTAL] Path to configuration file that
                                 can enable TLS or authentication.
      --log.level=info           Only log messages with the given severity or
                                 above. One of: [debug, info, warn, error]
      --log.format=logfmt        Output format of log messages. One of: [logfmt,
                                 json]
      --[no-]version             Show application version.

Visit http://localhost:9602/modbus?target=1.2.3.4:502&module=fake&sub_target=1 where 1.2.3.4:502 is the IP and port number of the modbus IP device to get metrics from, while module and sub_target parameters specify which module and subtarget to use from the config file. If your device doesn't use sub-targets you can usually just set it to 1.

Visit http://localhost:9602/metrics to get the metrics of the exporter itself.

Configuration File

Check out modbus.yml for more details on the configuration file format.

The --config.file parameter can be used multiple times to load more than one file. It also supports glob filename matching, e.g. modbus_*.yml.

Systemd service

You can create a systemd service if you want to run modbus exporter as a background service. Start by creating a modbus_exporter system account (example on Debian)

useradd -r modbus_exporter

Place the modbus_exporter binary at /usr/local/bin/modbus_exporter

The following example systemd unit file can be saved to /etc/systemd/system/modbus_exporter.service:

[Unit]
Description=Modbus TCP Prometheus exporter
Requires=network.target
After=network-online.target
Wants=network-online.target

[Service]
User=modbus_exporter
Group=nogroup
ExecStart=/usr/local/bin/modbus_exporter --config.file='/etc/modbus_exporter.yml'
Restart=on-failure
RestartSec=1

[Install]
WantedBy=multi-user.target

Then locate your Modbus exporter config file in /etc/modbus_exporter.yml, and run the following commands to make systemd aware of config changes and startup the modbus_exporter

systemctl daemon-reload
systemctl start modbus_exporter

In order to start the service at system boot, run the following

systemctl enable modbus_exporter

TODO

Rework logging.
Revisit bit parsing.
Print name, version, ... on exporter startup.

Misc info

ModBus RTU

Support for serial ModBus (RTU) was dropped in git commit d06573828793094fd2bdf3e7c5d072e7a4fd381b. Please send a PR if you need it again. For now, we suggest using a ModBus PLC/bridge/master to bridge from RTU into TCP.

Software provenance

This is forked from https://github.com/lupoDharkael/modbus_exporter which was not maintained any more and did not follow Prometheus best practices. Initially, development happened in https://github.com/mxinden/modbus_exporter which has now been retired in favour of https://github.com/RichiH/modbus_exporter .

RichiH / modbus_exporter

readme