chore: update mqtt documentation (influxdata#10394)

powersj · Jan 21, 2022 · 14dc5a1 · 14dc5a1
1 parent 34c958f
commit 14dc5a1
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 49 deletions.
diff --git a/plugins/outputs/mqtt/README.md b/plugins/outputs/mqtt/README.md
@@ -2,25 +2,54 @@
 
 This plugin writes to a [MQTT Broker](http://http://mqtt.org/) acting as a mqtt Producer.
 
+## Mosquitto v2.0.12+ and `identifier rejected`
+
+In v2.0.12+ of the mosquitto MQTT server, there is a
+[bug](https://github.com/eclipse/mosquitto/issues/2117) which requires the
+`keep_alive` value to be set non-zero in your telegraf configuration. If not
+set, the server will return with `identifier rejected`.
+
+As a reference `eclipse/paho.mqtt.golang` sets the `keep_alive` to 30.
+
+## Configuration
+
 ```toml
 [[outputs.mqtt]]
-  ## URLs of mqtt brokers
+  ## MQTT Brokers
+  ## The list of brokers should only include the hostname or IP address and the
+  ## port to the broker. This should follow the format '{host}:{port}'. For
+  ## example, "localhost:1883" or "127.0.0.1:8883".
   servers = ["localhost:1883"]
 
-  ## topic for producer messages
+  ## MQTT Topic for Producer Messages
+  ## MQTT outputs send metrics to this topic format:
+  ## <topic_prefix>/<hostname>/<pluginname>/ (e.g. prefix/web01.example.com/mem)
   topic_prefix = "telegraf"
 
   ## QoS policy for messages
+  ## The mqtt QoS policy for sending messages.
+  ## See https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q029090_.htm
   ##   0 = at most once
   ##   1 = at least once
   ##   2 = exactly once
-  qos = 2
+  # qos = 2
+
+  ## Keep Alive
+  ## Defines the maximum length of time that the broker and client may not
+  ## communicate. Defaults to 0 which turns the feature off.
+  ##
+  ## For version v2.0.12 and later mosquitto there is a bug
+  ## (see https://github.com/eclipse/mosquitto/issues/2117), which requires
+  ## this to be non-zero. As a reference eclipse/paho.mqtt.golang defaults to 30.
+  # keep_alive = 0
 
   ## username and password to connect MQTT server.
   # username = "telegraf"
   # password = "metricsmetricsmetricsmetrics"
 
-  ## client ID, if not set a random ID is generated
+  ## client ID
+  ## The unique client id to connect MQTT server. If this parameter is not set
+  ## then a random ID is generated.
   # client_id = ""
 
   ## Timeout for write operations. default: 5s
@@ -30,43 +59,20 @@ This plugin writes to a [MQTT Broker](http://http://mqtt.org/) acting as a mqtt
   # tls_ca = "/etc/telegraf/ca.pem"
   # tls_cert = "/etc/telegraf/cert.pem"
   # tls_key = "/etc/telegraf/key.pem"
+
   ## Use TLS but skip chain & host verification
   # insecure_skip_verify = false
 
-  ## When true, metrics will be sent in one MQTT message per flush.  Otherwise,
+  ## When true, metrics will be sent in one MQTT message per flush. Otherwise,
   ## metrics are written one metric per MQTT message.
   # batch = false
 
-  ## When true, messages will have RETAIN flag set.
+  ## When true, metric will have RETAIN flag set, making broker cache entries until someone
+  ## actually reads it
   # retain = false
 
-  ## Defines the maximum length of time that the broker and client may not communicate.
-  ## Defaults to 0 which turns the feature off. For version v2.0.12 mosquitto there is a
-  ## [bug](https://github.com/eclipse/mosquitto/issues/2117) which requires keep_alive to be set.
-  ## As a reference eclipse/paho.mqtt.golang v1.3.0 defaults to 30.
-  # keep_alive = 0
-
-  ## Data format to output.
-  # data_format = "influx"
+  ## Each data format has its own unique set of configuration options, read
+  ## more about them here:
+  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
+  data_format = "influx"
 ```
-
-## Required parameters
-
-* `servers`: List of strings, this is for speaking to a cluster of `mqtt` brokers. On each flush interval, Telegraf will randomly choose one of the urls to write to. Each URL should just include host and port e.g. -> `["{host}:{port}","{host2}:{port2}"]`
-* `topic_prefix`: The `mqtt` topic prefix to publish to. MQTT outputs send metrics to this topic format `<topic_prefix>/<hostname>/<pluginname>/` ( ex: `prefix/web01.example.com/mem`)
-* `qos`: The `mqtt` QoS policy for sending messages. See [these docs](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q029090_.htm) for details.
-
-## Optional parameters
-
-* `username`: The username to connect MQTT server.
-* `password`: The password to connect MQTT server.
-* `client_id`: The unique client id to connect MQTT server. If this parameter is not set then a random ID is generated.
-* `timeout`: Timeout for write operations. default: 5s
-* `tls_ca`: TLS CA
-* `tls_cert`: TLS CERT
-* `tls_key`: TLS key
-* `insecure_skip_verify`: Use TLS but skip chain & host verification (default: false)
-* `batch`: When true, metrics will be sent in one MQTT message per flush. Otherwise, metrics are written one metric per MQTT message.
-* `retain`: Set `retain` flag when publishing
-* `data_format`: [About Telegraf data formats](https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md)
-* `keep_alive`: Defines the maximum length of time that the broker and client may not communicate with each other. Defaults to 0 which deactivates this feature.
diff --git a/plugins/outputs/mqtt/mqtt.go b/plugins/outputs/mqtt/mqtt.go
@@ -21,24 +21,41 @@ const (
 )
 
 var sampleConfig = `
-  servers = ["localhost:1883"] # required.
-
-  ## MQTT outputs send metrics to this topic format
-  ##    "<topic_prefix>/<hostname>/<pluginname>/"
-  ##   ex: prefix/web01.example.com/mem
+  ## MQTT Brokers
+  ## The list of brokers should only include the hostname or IP address and the
+  ## port to the broker. This should follow the format '{host}:{port}'. For
+  ## example, "localhost:1883" or "127.0.0.1:8883".
+  servers = ["localhost:1883"]
+
+  ## MQTT Topic for Producer Messages
+  ## MQTT outputs send metrics to this topic format:
+  ## <topic_prefix>/<hostname>/<pluginname>/ (e.g. prefix/web01.example.com/mem)
   topic_prefix = "telegraf"
 
   ## QoS policy for messages
+  ## The mqtt QoS policy for sending messages.
+  ## See https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q029090_.htm
   ##   0 = at most once
   ##   1 = at least once
   ##   2 = exactly once
   # qos = 2
 
+  ## Keep Alive
+  ## Defines the maximum length of time that the broker and client may not
+  ## communicate. Defaults to 0 which turns the feature off.
+  ##
+  ## For version v2.0.12 and later mosquitto there is a bug
+  ## (see https://github.com/eclipse/mosquitto/issues/2117), which requires
+  ## this to be non-zero. As a reference eclipse/paho.mqtt.golang defaults to 30.
+  # keep_alive = 0
+
   ## username and password to connect MQTT server.
   # username = "telegraf"
   # password = "metricsmetricsmetricsmetrics"
 
-  ## client ID, if not set a random ID is generated
+  ## client ID
+  ## The unique client id to connect MQTT server. If this parameter is not set
+  ## then a random ID is generated.
   # client_id = ""
 
   ## Timeout for write operations. default: 5s
@@ -48,24 +65,18 @@ var sampleConfig = `
   # tls_ca = "/etc/telegraf/ca.pem"
   # tls_cert = "/etc/telegraf/cert.pem"
   # tls_key = "/etc/telegraf/key.pem"
+
   ## Use TLS but skip chain & host verification
   # insecure_skip_verify = false
 
-  ## When true, metrics will be sent in one MQTT message per flush.  Otherwise,
+  ## When true, metrics will be sent in one MQTT message per flush. Otherwise,
   ## metrics are written one metric per MQTT message.
   # batch = false
 
   ## When true, metric will have RETAIN flag set, making broker cache entries until someone
   ## actually reads it
   # retain = false
 
-  ## Defines the maximum length of time that the broker and client may not communicate. 
-  ## Defaults to 0 which turns the feature off. For version v2.0.12 of eclipse/mosquitto there is a 
-  ## [bug](https://github.com/eclipse/mosquitto/issues/2117) which requires keep_alive to be set.
-  ## As a reference eclipse/paho.mqtt.golang v1.3.0 defaults to 30.
-  # keep_alive = 0
-
-  ## Data format to output.
   ## Each data format has its own unique set of configuration options, read
   ## more about them here:
   ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md