IMD SolutionComputing LibraryShop main store

How-to

How to store MQTT messages in InfluxDB with Telegraf

Edge computing and IIoT Published 5 min read

Short answer

No — InfluxDB has no MQTT client and cannot subscribe to topics. Run Telegraf beside it: the mqtt_consumer input subscribes to your topics and an InfluxDB output writes the parsed points. Publish line protocol, or set the parser to the format your device actually sends, and pick the output plugin that matches the server's write API.

On this page
  1. The hop Telegraf fills
  2. Configure the MQTT consumer input
  3. Format the payload so it parses
  4. Pick the output plugin that matches the server
  5. Prove each hop with one message
  6. Worked example: one message per minute for ten minutes
  7. Questions asked

Yes — this works without Node-RED, and the whole configuration is two plugin tables: an [[inputs.mqtt_consumer]] input that subscribes to your topics, and either [[outputs.influxdb]] or [[outputs.influxdb_v2]] as the output, chosen by the write API your InfluxDB server serves. InfluxDB is a time-series database with no MQTT client, so it cannot subscribe to topics itself; you put Telegraf between the broker and the database. Telegraf's MQTT consumer input connects to the broker, subscribes to the topics your IoT device publishes, and parses each payload in a format you configure — line protocol being the lowest-friction choice — while the InfluxDB output plugin writes the resulting points. The steps below configure both plugin blocks, format the payload, and prove the path with one counted message.

The hop Telegraf fills #

The device publishes each message to a topic, and the broker forwards that publication to every client subscribed to a matching topic filter — the routing that how MQTT clients publish and subscribe through the broker explains. InfluxDB is never one of those clients. Telegraf is the subscriber you add: its mqtt_consumer input is a service plugin that consumes messages from MQTT brokers for the configured topics in one of the supported data formats.

The broker also keeps no historic data you can query, which is why the historian role lands on InfluxDB. And a subscriber receives only what is published while it is connected: anything sent while Telegraf is down is not waiting when it returns. Covering that gap is the publisher's job, with MQTT store and forward backfill after a connection outage.

Configure the MQTT consumer input #

  1. Add the input block. Each Telegraf plugin is one table in the configuration file, written in double square brackets; the consumer's table is [[inputs.mqtt_consumer]].
  2. Point it at the broker. Use the address, port and credentials of a listener the broker actually runs, with the transport security that listener requires. Several addresses inside one block are treated as a single MQTT cluster; a second, independent broker needs a second block of the plugin.
  3. List the topic filters to subscribe to. They must match the topics the device publishes character for character, and the broker's access rules must let this client subscribe.
  4. Set the payload parser. The consumer parses every message with one of Telegraf's input data formats, so the setting must match the bytes the device publishes — whatever the topic is called.

Format the payload so it parses #

Line protocol is the lowest-friction choice, because the consumer hands it to InfluxDB unchanged. One line carries a measurement, optional tags, one or more fields, and optionally a timestamp; leave the timestamp out and the point is stamped when it is written. An illustrative payload for one machine sensor:

machine,cell=press01 temp=21.4

Read that as measurement machine, tag cell=press01, and field temp at 21.4 — example names and values standing in for yours. Keep device identity and other dimensions in tags and measured values in fields, and keep each field's type stable: a field that arrives as a number in one message and as text in the next makes the writes fail.

If the device already publishes JSON, do not relabel it as line protocol. Set the parser to JSON and map the payload's measurement, tag and field values the way your installed Telegraf version specifies. A payload that does not match the configured parser is the classic reason a consumer connects, subscribes and still writes nothing.

Pick the output plugin that matches the server #

The two InfluxDB outputs are not interchangeable, and the names carry the decision: [[outputs.influxdb]] speaks the v1 write API and [[outputs.influxdb_v2]] speaks the v2 API — the plugin name denotes the API version. InfluxDB 3 accepts writes on the v1 API, so match the plugin to the write API your deployed server serves. On a 2.x server such as InfluxDB 2.6, configure [[outputs.influxdb_v2]] with the server URL, organization, bucket and a token holding write permission on that bucket — the same endpoint and token checks walked through for connecting Node-RED to InfluxDB 2.6 with the v2 API.

Keep the token out of shared configuration files and use the secret handling your deployment already has. The skeleton with both tables in place:

[[inputs.mqtt_consumer]]
  # broker address and credentials, topic filters, payload parser

[[outputs.influxdb_v2]]
  # server URL, organization, bucket, write token

Each comment marks a setting you replace with your deployed values; the table headers are the plugin names.

Prove each hop with one message #

Validate the edited file with Telegraf's own configuration test before restarting the service, then push one known message through and check the hops in order:

  1. The publication reached the broker — visible in the broker log or with an independent subscriber on the same topic. If nothing publishes at all, you are fixing the same class of fault as a device that cannot publish MQTT to a broker on a PC.
  2. Telegraf connected and subscribed — its log states both. A silent log with no subscription usually means a topic misspelling or an access rule denying the subscribe.
  3. The message parsed — no parser errors, and the parsed point shows the measurement, tags and fields you expect. Receiving proves delivery, not parseability.
  4. The write succeeded — Telegraf reports its writes, and errors at this point are output-side: URL, destination, credentials, or a field type the server refuses.
  5. The point is queryable — query the destination for that measurement, tags, fields and timestamp before calling the path done.

Worked example: one message per minute for ten minutes #

Inputs, with where each comes from:

  • Publish interval: one message every 60 s — an example input, since the question named no rate; substitute your device's actual period.
  • Check window: 10 min, which is 600 s — chosen for this verification.
  • Points per message: 1 — one line-protocol payload with one field parses to one point.

Rule in words: the points you should find equal the check window divided by the publish interval, times the points per message. Arithmetic: 600 s ÷ 60 s per message = 10 messages; 10 messages × 1 point per message = 10 points expected. Query the destination with the window as the time range. Ten points returned and the path is proven end to end; eight returned and two messages were lost between broker and database. Any count below the expected ten is a lost-message fault — find that hop before touching a parser or output setting, then commission the flow.

Questions asked

Does the broker queue messages for Telegraf while it is stopped?

No. A subscriber only receives what is published while it is connected, so a restarted Telegraf starts from the present moment and the outage window stays empty. A publisher can mark a message retained, but that hands the subscriber only the last value per topic at connect, not a history. Real gap coverage means the device buffers and republishes the missed interval.

Can one consumer block read two different MQTT brokers?

Not as two brokers. Several broker addresses inside one mqtt_consumer block are treated as a single MQTT cluster. For two independent brokers, configure two blocks of the plugin, each with its own broker address, topics and parser — and, where the data lands in different databases, its own output table as well.

The server is InfluxDB 3 — which output plugin do I configure?

Configure the influxdb output: it speaks the v1 write API, and InfluxDB 3 accepts writes on that API. The influxdb_v2 output speaks the v2 API, which is what a 2.x server such as InfluxDB 2.6 serves. Match the plugin to the write API the deployed server actually accepts and the decision is made.

Telegraf subscribes but writes no points — where do I look first?

Read the Telegraf log in order: connect and subscribe lines first, then parser errors, then output errors. The first failure in that sequence is the one to fix. A frequent one is a parser mismatch — a device publishing JSON to a consumer set for line protocol connects happily and parses nothing.

How do I backfill the points missed during an outage?

Have the publisher republish the missed messages carrying their original timestamps. A point is keyed by measurement, tag set and timestamp, so repeating a backfill overwrites the same points instead of duplicating them. Afterwards, re-run the count check over the gap: expected points are the window divided by the publish interval.

Keep reading

  • Troubleshooting

    Telegraf MQTT consumer connects but writes no data to InfluxDB

    An empty 0 / 10000 output buffer with both the MQTT and InfluxDB connections up means no metrics are reaching Telegraf's parser. Prove live delivery with a second subscriber on a different client ID before touching parser or buffer settings: the two startup connections are independent events, and with qos = 0 and a non-persistent session, traffic published while Telegraf is offline is unrecoverable.

    Edge computing and IIoT

  • Explainer

    MQTT to Kafka edge data pipeline without losing messages

    Keep MQTT on the sensor side of the plant, put the Kafka-class durable log on the site or cloud side of the uplink, and give the boundary one disk-backed store-and-forward buffer sized to the longest outage you will ride through. At 500 messages per second and an 8-hour outage, that queue holds 14.4 million messages and about 9.6 GB — set the ceiling above it and alarm on overflow.

    Edge computing and IIoT

  • Selection guide

    Sizing an edge PC for oversampled PLC data to InfluxDB

    Yes — the database side carries it. 50 samples every 2 ms is 25,000 values per second, reaching InfluxDB as 2.5 writes per second at the documented 10,000-line batch, about 0.38 MB each. What decides the project is the controller's 2 ms buffer handshake and line serialization — no vendor rates that path in bytes per second, so each stage is proven on the box with a synthetic signal before a sensor is wired.

    Edge computing and IIoT