Plugin:MQTT
| MQTT plugin | |
|---|---|
| Type: | read, write |
| Callbacks: | config, init, write |
| Status: | supported |
| First version: | 5.6 |
| Copyright: | 2014-2015 Florian octo Forster 2014 Marc Falzon |
| License: | MIT license |
| Manpage: | collectd.conf(5) |
| List of Plugins | |
The MQTT plugin transmits or receives values collected by collectd via the MQTT protocol. MQTT is a "light weight" publish-subscribe messaging protocol for use on top of the TCP/IP protocol. Data is sent to or received from a MQTT Server, also known as a message broker. The values are encoded and parsed in the plain text protocol. It is possible to use three different levels of Quality of Service (QoS), which offer different levels of assurance that the message will be delivered.
Contents
Synopsis
<Plugin "mqtt">
# Send values to an MQTT server
<Publish "some_name">
Host "localhost"
# Port "1883"
# User "mqttuser"
# Password "password"
# ClientId "collectd-hostname"
# QoS 0
# Prefix "collectd"
# Retain true
# StoreRates false
</Publish>
# Receive values from an MQTT server
<Subscribe "some_name">
Host "localhost"
# Port "1883"
# User "mqttuser"
# Password "password"
# ClientId "collectd-hostname"
# QoS 0
# CleanSession false
# Topic "subscribetopic"
</Subscribe>
</Plugin>
The plugin's configuration is in Publish and/or Subscribe blocks, configuring the sending and receiving direction respectively. The plugin will register a write callback named "mqtt/name" where name is the string argument given to the Publish block. Both types of blocks share many but not all of the following options. If an option is valid in only one of the blocks, it will be mentioned explicitly.
Options
- Host Hostname
- Hostname of the MQTT broker to connect to.
- Port Service
- Port number or service name of the MQTT broker to connect to.
- User UserName
- Username used when authenticating to the MQTT broker.
- Password Password
- Password used when authenticating to the MQTT broker.
- ClientId ClientId
- MQTT client ID to use. Defaults to the hostname used by collectd.
- QoS [0-2]
- Sets the Quality of Service, with the values 0, 1 and 2 meaning:
- 0 At most once
- 1 At least once
- 2 Exactly once
- In Publish blocks, this option determines the QoS flag set on outgoing messages and defaults to 0. In Subscribe blocks,
- determines the maximum QoS setting the client is going to accept and defaults to 2. If the QoS flag on a message is larger
- than the maximum accepted QoS of a subscriber, the message's QoS will be downgraded.
- Prefix Prefix (Publish only)
- This plugin will use one topic per value list which will looks like a path. Prefix is used as the first path element and defaults to collectd.
- An example topic name would be:
- collectd/cpu-0/cpu-user
- Retain false|true (Publish only)
- Controls whether the MQTT broker will retain (keep a copy of) the last message sent to each topic and deliver it to new subscribers. Defaults to false.
- StoreRates true|false (Publish only)
- Controls whether "DERIVE" and "COUNTER" metrics are converted to a rate before sending. Defaults to true.
- CleanSession true|false (Subscribe only)
- Controls whether the MQTT "cleans" the session up after the subscriber disconnects or if it maintains the subscriber's
- subscriptions and all messages that arrive while the subscriber is disconnected. Defaults to true.
- Topic TopicName (Subscribe only)
- Configures the topic(s) to subscribe to. You can use the single level "+" and multi level "#" wildcards. Defaults to
- collectd/#, i.e. all topics beneath the collectd branch.
Dependencies
See also
