mqttexporter

README

mqtt-exporter

Export MQTT messages to Prometheus

Info This exporter allows you to simplify your IoT monitoring stack if you don't want to store messages on the long run. While InfluxDB or other timeseries database are well suited for IoT messages, I built this exporter because I don't need those databases, I just need a temporary storage (at least a few months). Also Prometheus is a piece of software that is already deployed in my stack along with Grafana, so I wanted to keep it simple and stupid. I do not recommend any one to use this project unless your motivations are the same.

This project is still a work in progress.

Usage

With Go:

go install github.com/gaelreyrol/mqtt-exporter

You can change the following options from the command line:

• the listening address server with -listen-addr, defaults to :8181.
• the telemetry path with -telemetry-path, defaults to /metrics.
• the config file path with -config-path, defaults to /etc/mqtt-exporter.toml.

Here is an example of the output generated by the exporter:

# HELP mqtt_topic_field
# TYPE mqtt_topic_field gauge
mqtt_topic_field{name="outside_temperature",topic="zigbee2mqtt/my_thermostat"} 12.6
mqtt_topic_field{name="inside_temperature",topic="zigbee2mqtt/my_thermostat"} 19
# HELP mqtt_topic_messages_total
# TYPE mqtt_topic_messages_total counter
mqtt_topic_messages_total{topic="zigbee2mqtt/my_thermostat"} 14

Configuration

The configuration file follows the TOML format.

Here is a configuration example:

broker = "localhost:1883"

[[topics]]
name = "zigbee2mqtt/my_thermostat"
fields = [
    "outside_temperature",
    "inside_temperature",
]

broker

The MQTT broker TCP address, for example localhost:1883.

It does no yet support encryption nor authentication.

topics

Topics represents each topic messages to export to Prometheus.

The name field represents the topic name available in your broker. The fields field represents each key that should be exported to Prometheus from a message received in the topic.

For example if the following payload is received with two fields defined outside_temperature and inside_temperature:

{
    "outside_temperature": 12.6,
    "inside_temperature": 19,
    "garage_temperature": 14
}

The garage_temperature field will not be exported to Prometheus.

Warning Only JSON is supported with zero level of depth, every value must be at the root of the JSON object.

Warning Each value's field extracted from the payload must be float compatible. Strings or child object path values are not supported.

Development

Requirements

• A MQTT broker such as Mosquitto
• Go ^1.20

Or install Nix and run nix develop.

ToDo

• Unit tests basic features
• Real world tests with NixOS test VM
• Split listening and exporting via topic channels
• Forget messages between intervals

Documentation

Index

• func ExportTopicMessages(app *App, context *TopicContext)
• func NewClient(config Config) *mqtt.Client
• func NewTopicFieldsGaugeVec(topic Topic) *prometheus.GaugeVec
• func NewTopicMessagesTotalCounter(topic Topic) prometheus.Counter
• func SubscribeTopic(app *App, topic *Topic)
• type App
  • func NewApp(configPath string, listenAddress string, metricsPath string) (*App, error)
  • func (app *App) Shutdown(ctx context.Context) error
  • func (app *App) Start() error
• type Config
  • func NewConfig() *Config
  • func (c *Config) FromFile(filePath string) error
• type Topic
  • func (t *Topic) IsFieldFiltered(key string) bool
• type TopicContext
  • func InitializeTopicContext(topic Topic, registry *prometheus.Registry) *TopicContext

Functions

func ExportTopicMessages

func ExportTopicMessages(app *App, context *TopicContext)

func NewClient

func NewClient(config Config) *mqtt.Client

func NewTopicFieldsGaugeVec

func NewTopicFieldsGaugeVec(topic Topic) *prometheus.GaugeVec

func NewTopicMessagesTotalCounter

func NewTopicMessagesTotalCounter(topic Topic) prometheus.Counter

func SubscribeTopic

func SubscribeTopic(app *App, topic *Topic)

Types

type App

type App struct {
	Config   *Config
	Registry *prometheus.Registry
	Server   *http.Server
	Client   *mqtt.Client
	// contains filtered or unexported fields
}

func NewApp

func NewApp(configPath string, listenAddress string, metricsPath string) (*App, error)

func (*App) Shutdown

func (app *App) Shutdown(ctx context.Context) error

func (*App) Start

func (app *App) Start() error

type Config

type Config struct {
	Broker string
	Topics []Topic
}

func NewConfig

func NewConfig() *Config

func (*Config) FromFile

func (c *Config) FromFile(filePath string) error

type Topic

type Topic struct {
	Name   string
	Fields []string
}

func (*Topic) IsFieldFiltered

func (t *Topic) IsFieldFiltered(key string) bool

type TopicContext

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

func InitializeTopicContext

func InitializeTopicContext(topic Topic, registry *prometheus.Registry) *TopicContext