Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update mqtt documentation #10394

Merged
merged 1 commit into from
Jan 10, 2022
Merged

chore: update mqtt documentation #10394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
chore: update mqtt documentation 
There is some confusion reguarding the server's string as well as the
need to use the keep_alive param with later versions of mosquitto. This
tries to make the README read a bit more clear and not need two
different sections, which detail the various parameters.

Finally, it gets the README and the configuration in sync with each
other.

Fixes: #10180
  • Loading branch information
@powersj
powersj committed Jan 6, 2022
commit 7b4ac5866697c70c233b1f634d3c672eea601bcc
76 changes: 41 additions & 35 deletions plugins/outputs/mqtt/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
39 changes: 25 additions & 14 deletions plugins/outputs/mqtt/mqtt.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down