CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: update mqtt documentation (#10394)

This commit is contained in:
Joshua Powers 2022-01-10 07:45:32 -07:00 committed by GitHub
parent 7f20e7103f
commit c2c15e8b3e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 65 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
plugins/outputs/mqtt/README.md
View File

@ -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.

37
plugins/outputs/mqtt/mqtt.go
View File

@ -21,24 +21,41 @@ const (
)
var sampleConfig = `
servers = ["localhost:1883"] # required.
## 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 outputs send metrics to this topic format
## "<topic_prefix>/<hostname>/<pluginname>/"
## ex: prefix/web01.example.com/mem
## 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,10 +65,11 @@ 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
@ -59,13 +77,6 @@ var sampleConfig = `
## 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