Plugin:MQTT

From collectd Wiki
Jump to: navigation, search
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.


Publish Example

This is an example of publishing from collectd and then subscribing using the mosquitto command line tools.

Add the following configuration to collectd.conf:

<Plugin "mqtt">
   <Publish "name1">
     Host "localhost"
     Prefix "collectd"
     Retain true
   </Publish>
</Plugin>

Start a MQTT server (such as mosquitto) on the same machine.

Then subscribe using mosquitto_sub and you should start seeing pairs of topic names and MQTT payloads, separated by a space:

 $ mosquitto_sub -t 'collectd/#' -v
 collectd/bob/memory/memory-wired 1448840558.555:1714962432
 collectd/bob/memory/memory-active 1448840558.555:9526575104
 collectd/bob/memory/memory-inactive 1448840558.555:4316172288
 collectd/bob/memory/memory-free 1448840558.555:871038976
 collectd/bob/memory/memory-wired 1448840568.206:1888133120
 collectd/bob/memory/memory-inactive 1448840568.206:4315336704
 collectd/bob/memory/memory-free 1448840568.206:853004288
 collectd/bob/memory/memory-active 1448840568.206:9373102080

The payload is a serialised Value list of one or more values separated by colons, depending on the Type. The first number is always the UNIX timestamp for the value(s).

See Plain Text Protocol for more detailed information.


Subscribe Example

This is an example of publishing from mosquitto_pub command line tool and then subscribing using to it using collectd.

Add the following configuration to collectd.conf:

<Plugin "mqtt">
   <Subscribe "name2">
     Host "localhost"
     Topic "incoming/#"
     CleanSession true
   </Publish>
</Plugin>

Start a MQTT server (such as mosquitto) on the same machine.

Then publish using mosquitto_pub and collectd should receive and ingest the values.

 $ mosquitto_pub -t 'incoming/localhost/mqtt/temperature-kitchen' -m 'N:21.5'

The payload is a serialised Value list of one or more values separated by colons, depending on the Type. Values are always prefixed with a Unix timestamp but you can use 'N' instead of a timestamp, which is interpreted as 'now'. You can submit an undefined GAUGE value by using 'U'. See Plain Text Protocol for more information.

The topic name (after the prefix) follows the following format:

 <host>/<plugin>-<plugin_instance>/<type>-<type_instance>
  • <host> can be the name of the device the data is from
  • <plugin> can be anything, but should probably be the name of the source
  • <plugin_instance> the instance name of the source (optional)
  • <type> the name of the data type - must be listed in types.db(5)
  • <type_instance> a qualifier for the type - free text (optional)

See Naming schema for more details about the path structure.


Dependencies

See also


Personal tools
Namespaces

Variants
Actions
Navigation
Tools