mqttlogger

Logs MQTT messages to STDOUT, file or a Discord channel.

Introduction

This repository is part of the homebattery project. Its primary goal is to enable push notifications in Discord when a message is published to an error relevant MQTT topic. Of course, usage as an MQTT data logger or debugging tool is also perfectly possible.

The working principle is simple: all MQTT messages received on the configured MQTT topics are written to the logs (with their timestamp and topic).

Things worth to notice:

• MQTT topic wildcards are supported.
• The log files written by this tool are rotated at midnight.
• The log levels DEBUG and CRITICAL are reserved for the output of the tool itself and can not be used for MQTT.

Discord setup steps

Please read the tutorial from discord.py.

Configuration

The configuration is done via yaml file. The example file can be found in config/sample.yaml

Key	Environment variable	Rules	Explanation
mqtt -> host	MQLO_MQTT_HOST	string, <host>:<port>	Host and port of the MQTT server to connect to.
mqtt -> ca	-	optional, string	Enables TLS encryption and sets the path to the TLS public certificate chain file.
mqtt -> tls_insecure	-	optional, bool	If set to true, TLS encryption is enabled, but the TLS certificates are not checked (not recommended).
mqtt -> user	MQLO_MQTT_USER	string	The user name for log in to the MQTT server.
mqtt -> password	MQLO_MQTT_PASS	string	The password for log in to the MQTT server.
stdout	-	optional	Enables logging to STDOUT.
stdout -> level	-	string; DEBUG, INFO, WARN, ERROR or CRITICAL	Minimum level a log message must have to be written to this output.
file	-	optional	Enables logging to file.
file -> level	-	string; DEBUG, INFO, WARN, ERROR or CRITICAL	Minimum level a log message must have to be written to this output.
file -> path	-	string	Path to the written log file.
file -> days	-	optional, int	If set, log files are deleted after the given number of days.
discord	-	optional	Enables logging to Discord.
discord -> level	-	string; DEBUG, INFO, WARN, ERROR or CRITICAL	Minimum level a log message must have to be written to this output.
discord -> token	MQLO_DISCORD_TOKEN	string	Discord bot token. Alternatively, specify token_path.
discord -> token_path	MQLO_DISCORD_TOKEN_PATH	string	Path to the Discord bot token file. Alternatively, specify token.
discord -> channel_id	MQLO_DISCORD_CHANNEL_ID	int	Id of the Discord channel to write to.
topics -> <MQTT topic>	-	-	Enables logging of the MQTT topic.
topics -> <MQTT topic> -> level	-	string; INFO, WARN or ERROR	Log level to the created message.
topics -> <MQTT topic> -> type	-	string; bool, uint8, int8, uint16, int16, uint32, int32, uint64, int64, float, double or utf8	Binary format of the payload received in this topic.

Usage without docker

Prerequisites

• Python 3 with pip + venv

This program should run on any OS, but I have no capacity to test this, so feedback is appreciated. My test machines run Ubuntu and Raspbian.

Install

git clone https://github.com/danielringch/mqttlogger.git
python3 -m venv <path to virtual environment>
source <path to virtual environment>/bin/activate
python3 -m pip install -r requirements.txt

Run

source <path to virtual environment>/bin/activate
python3 -B src/mqttlogger.py --config /path/to/your/config/file.yaml

Usage with docker

This software is also available as docker container:

docker pull danielringch/mqttlogger:latest

The container expects the configuration file at /config/mqttlogger.yaml

Example:

docker run --rm -it \
  -v /path/to/config/file:/config \
  -e MQLO_MQTT_HOST="12.34.56.78:8883" \
  -e MQLO_MQTT_USER="user" \
  -e MQLO_MQTT_PASS="password" \
  danielringch/mqttlogger

Get support

You have trouble getting started? Something does not work as expected? You have some suggestions or thoughts? Please let me know.

Feel free to open an issue here on github or contact me on reddit: 3lr1ng0.