mqttop

README

MQTTop

MQTTop is a bridge to provide top-like system metrics over MQTT. This was mainly designed for use with Home Assistant and supports MQTT Discovery, and has currently been tested on Linux and with an NVIDIA GPU.

Inspired by btop and linux2mqtt

Quick Start

There are two provided Docker images, one with GPU support and one without. To monitor the host metrics, mount the root directory and set the environment variable $MQTTOP_ROOTFS_PATH to the mount point in the container, and to monitor the host network metrics, set network_mode to host. In order for GPU support to work, you must have the NVIDIA Container Toolkit installed.

docker-compose.yml - Without GPU Support

services:
  mqttop:
    image: ghcr.io/lone-faerie/mqttop:latest
    environment:
      - MQTTOP_ROOTFS_PATH=/host
    volumes:
      - "./config.yml:/config/config.yml"
      - "/:/host:ro"
    network_mode: host

docker-compose.yml - With GPU Support

services:
  mqttop:
    image: ghcr.io/lone-faerie/mqttop:gpu
    environment:
      - MQTTOP_ROOTFS_PATH=/host
    volumes:
      - "./config.yml:/config/config.yml"
      - "/:/host:ro"
    network_mode: host
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Configuration

Configuration files are stored in yaml format. Configs can be broken up into multiple files and may be passed as either a list of files or directories. The path to config files is either the path(s) passed as arguments, the value of $MQTTOP_CONFIG_PATH, $XDG_CONFIG_HOME/mqttop.yaml, or $HOME/.config/mqttop.yaml. The default path for config files in the Docker container is /config/config.yml.

Durations are parsed using Go's time.ParseDuration and any strings may be set to an environment variable $<variable> or Docker secret !secret <secret>.

Field	Type	Default	Description
interval	duration	2s	Default update interval for metrics
mqtt	MQTTConfig		MQTT configuration
discovery	DiscoveryConfig		Discovery configuration
log	LogConfig		Log configuration
cpu	CPUConfig		CPU metric configuration
memory	MemoryConfig		Memory metric configuration
disks	DisksConfig		Disks metric configuration
net	NetConfig		Network metric configuration
battery	BatteryConfig		Battery metric configuration
dirs	list DirConfig		List of directory metric configurations
gpu	GPUConfig		GPU metric configuration

MQTT Configuration

Field	Type	Default	Description
broker	string	"$MQTTOP_BROKER_ADDRESS"	Address of the MQTT broker
client_id	string		Client ID used when connecting to the broker
username	string	"$MQTTOP_BROKER_USERNAME"	Username used to connect to the broker
password	string	"$MQTTOP_BROKER_PASSWORD"	Password used to connect to the broker
keep_alive	duration	30s	Amount of time to wait before sending a PING to the broker
cert_file	string		Path to the cert file for SSL, disabled if blank
key_file	string		Path to the key file for SSL, disabled if blank
reconnect_interval	duration	10m	Maximum time to wait before attempting to reconnect
connect_timeout	duration	30s	Amount of time to wait when connecting before timeout
ping_timeout	duration	10s	Amount of time to wait after sending a PING before deciding to timeout
write_timeout	duration	0	Amount of time to wait after publishing before deciding to timeout, 0 means never timeout
birth_lwt_enabled	bool	true	Enable/disable birth and LWT message
birth_lwt_topic	string	"mqttop/bridge/status"	Topic to publish birth and LWT message to
log_level	level	DISABLED	Log level to provide to the MQTT client

See https://pkg.go.dev/github.com/eclipse/paho.mqtt.golang#ClientOptions

Discovery Configuration

Field	Type	Default	Description
enabled	bool	true	Enabled/disable MQTT discovery
prefix	string	"homeassistant"	Prefix of discovery topic
device_name	string		Name of device used for discovery, if blank or "hostname" will use device hostname, if "username" will use MQTT username
node_id	string		Optional node ID to use for discovery
availability	string		Topic to publish availability to, if blank will use MQTT birth_lwt_topic
retained	bool	true	Retain discovery payload at the broker
qos	int	QoS of discovery payload
wait_topic	string		Topic to wait for payload on before publishing discovery, if blank will not wait
wait_payload	string		Payload to wait for from wait_topic before publishing discovery, if blank will wait for any payload

See https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery

Log Configuration

Field	Type	Default	Description
level	level	INFO	Log level to use
output	string		Where to output logs, one of stderr, stdout, or path to a file, if blank will default to stderr
format	string		Format of log messages, either blank or json

CPU Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/cpu"	Topic to publish updates to
name	string		Custom name to use for the CPU
name_template	string		Template to use for the CPU name, will override name
selection_mode	string	auto	Mode used to select overall CPU temperature and frequency, one of auto, first, average, max, min, random

Memory Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/memory"	Topic to publish updates to
size_unit	string		Size unit to use for memory size, if blank, will be automatically determined
include_swap	bool	true	Include swap in the metrics

Disks Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/disks"	Topic to publish updates to
use_fstab	bool	true	Use /etc/fstab to find disks
rescan	bool or duration		Interval to rescan for disks, if true will use update interval, else the given interval
show_io	bool	true	Include disk IO in metrics
disk	list DiskConfig		List of individual disk configurations

Disk Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
exclude	bool	false	Exclude the disk from metrics
name	string		Custom name to use for the disk
name_template	string		Template to use for the disk name, will override name
mount_point	string		Path to mount point of the disk
size_unit	string		Size unit to use for disk size, if blank, will be automatically determined
show_io	bool	true	Include disk IO in metrics

Network Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/net"	Topic to publish updates to
only_physical	bool	false	Only include physical network interfaces
only_running	bool	false	Only include running network interfaces
include_bridge	bool	false	Include bridge interfaces
rescan	bool or duration		Interval to rescan for interfaces, if true will use update interval, else the given interval
rate_unit	string		Rate unit to use for network throughput, if blank, will be automatically determined
include	list NetIfaceConfig, list string		List of network interface configurations to explicitly include, if string will be name of interface
exclude	list string		List of network interfaces to explicitly exclude

Network Interface Configuration

Field	Type	Default	Description
name	string		Name to use for representing the interface
name_template	string		Template to use for the interface name, will override name
interface	string		Name of the interface on the system
rate_unit	string		Rate unit to use for network throughput, if blank, will use network config rate_unit

Battery Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/battery"	Topic to publish updates to
time_format	string		Format used to represent time remaining

Directory Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/dir/"	Topic to publish updates to
name	string		Custom name to use for the directory
name_template	string		Template to use for the directory name, will override name
path	string		Path to the directory
size_unit	string		Size unit to use for directory size, if blank, will be automatically determined
watch	bool	false	Watch the directory for changes instead of polling every update interval
depth	int	-1	Maximum depth to recursively watch the directory, if < 0, will watch the entire depth

GPU Configuration

Field	Type	Default	Description
enabled	bool	true	Enable/disable the metric
interval	duration		Update interval of the metric, if 0 will be top-level interval
topic	string	"mqttop/metric/gpu"	Topic to publish updates to
name	string		Custom name to use for the directory
name_template	string		Template to use for the directory name, will override name
platform	string		Platform of GPU to use, currently only supports nvidia
index	int	0	Index of GPU to use
size_unit	string		Size unit to use for memory size, if blank, will be automatically determined
include_procs	bool	false	Include GPU usage of processes

Documentation

Overview

Package mqttop implements a bridge to provide system metrics to the MQTT broker.

Configuration can be loaded from multiple YAML files, including from directories. If no config file is specified, the default path(s) will be determined by the first defined value of $MQTTOP_CONFIG_PATH, $XDG_CONFIG_HOME/mqttop.yaml, or $HOME/.config/mqttop.yaml. In the case of $MQTTOP_CONFIG_PATH, the value may be a comma-separated list of paths. If none of these files exist, the default configuration will be used, which looks for the following environment variables:

• broker: $MQTTOP_BROKER_ADDRESS
• username: $MQTTOP_BROKER_USERNAME
• password: $MQTTOP_BROKER_PASSWORD

Full documentation is available at: https://pkg.go.dev/github.com/lone-faerie/mqttop

Index

• type Bridge
  • func New(cfg *config.Config) *Bridge
  • func NewWithClient(cfg *config.Config, c mqtt.Client) *Bridge
  • func (b *Bridge) Connect(ctx context.Context) error
  • func (b *Bridge) Disconnect()
  • func (b *Bridge) Discover(ctx context.Context, path string) (err error)
  • func (b *Bridge) Done() <-chan struct{}
  • func (b *Bridge) IsConnected() bool
  • func (b *Bridge) IsConnectionOpen() bool
  • func (b *Bridge) Ready() <-chan error
  • func (b *Bridge) Start(ctx context.Context)

Types

type Bridge

type Bridge struct {
	// contains filtered or unexported fields
}

Bridge is the mqtt client that bridges metrics to the mqtt broker.

func New

func New(cfg *config.Config) *Bridge

New returns a new Bridge with the provided config and a [mqtt.Client] derived from the config. The bridge must have Bridge.Connect and Bridge.Ready called on it before it may be used. This follows the convention of [mqtt.NewClient] as well as waiting for metrics to be ready.

func NewWithClient

func NewWithClient(cfg *config.Config, c mqtt.Client) *Bridge

NewWithClient returns a new Bridge with the provided config and [mqtt.Client]. The bridge must have Bridge.Connect and Bridge.Ready called on it before it may be used. This follows the convention of [mqtt.NewClient] as well as waiting for metrics to be ready.

func (*Bridge) Connect

func (b *Bridge) Connect(ctx context.Context) error

Connect will create a connection to the message broker with the provided context, by default it will attempt to connect at v3.1.1 and auto retry at v3.1 if that fails

func (*Bridge) Disconnect

func (b *Bridge) Disconnect()

Disconnect will end the connection with the server.

func (*Bridge) Discover

func (b *Bridge) Discover(ctx context.Context, path string) (err error)

Discover publishes the discovery payload(s) for Home Assistant MQTT discovery after optionally waiting for a payload on the given wait topic. If path is a non-empty string, the previous discovery is loaded from the file at path for removing old components.

func (*Bridge) Done

func (b *Bridge) Done() <-chan struct{}

Done returns a channel that can be used to wait until the bridge has disconnected.

func (*Bridge) IsConnected

func (b *Bridge) IsConnected() bool

IsConnected returns a bool signifying whether the bridge is connected or not.

func (*Bridge) IsConnectionOpen

func (b *Bridge) IsConnectionOpen() bool

IsConnectionOpen return a bool signifying whether the bridge has an active connection to mqtt broker, i.e not in disconnected or reconnect mode

func (*Bridge) Ready

func (b *Bridge) Ready() <-chan error

Ready returns a channel that can be used to wait until all metrics have been started. If an error is encountered while starting metrics, it will be sent on this channel.

func (*Bridge) Start

func (b *Bridge) Start(ctx context.Context)

Start sets up each metric and begins listening for updates. Any updates that return nil errors will be published to the relevant metric's topic.