Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 39 ยท Integrations

MQTT and IoT Ingest into InfluxDB

Bring IoT sensor data from MQTT into InfluxDB. Map topics to tags, parse payloads, handle device time and offline devices, with runnable stand-ins.

Sensors, meters, vehicles and factory machines are the classic source of time-series data, and most of them speak MQTT, a lightweight publish/subscribe protocol designed for small devices and unreliable networks. A device publishes a message to a topic such as site1/room2/temperature; any subscriber to that topic receives it through a broker (Mosquitto, EMQX, HiveMQ and others).

InfluxDB does not speak MQTT itself. The usual bridge is Telegraf's mqtt_consumer input, which subscribes to topics and turns each message into a metric. This lesson shows the configuration (read-only; no broker or server runs here) and, more importantly, the data-mapping decisions, which you can practise with runnable JavaScript and SQL.

The architecture

flowchart LR
  D1["Sensor A"] --> B["MQTT broker"]
  D2["Sensor B"] --> B
  D3["Gateway"] --> B
  B --> T["Telegraf<br/>mqtt_consumer"]
  T --> I[("InfluxDB")]
  I --> G["Dashboards and alerts"]

Devices publish to a broker, Telegraf subscribes and writes to InfluxDB.

Why a broker in the middle? Devices connect out to it (no inbound firewall holes), many consumers can read the same data, and the broker buffers messages for subscribers that reconnect (depending on QoS and session settings).

Topics and payloads

MQTT topics are hierarchical strings. Choose a convention and keep to it:

TEXT
factory/{line}/{machine}/{measurement}
factory/line1/press-4/temperature   -> payload: 71.3
factory/line1/press-4/vibration     -> payload: 0.82

Payloads vary: plain numbers, JSON objects such as {"temp": 21.4, "hum": 48}, or binary formats. JSON is the easiest to handle.

A read-only Telegraf config that maps topic parts to tags and parses JSON:

TOML
[[inputs.mqtt_consumer]]
  servers = ["tcp://broker.example.com:1883"]
  topics = ["factory/+/+/+"]
  qos = 1
  persistent_session = true
  client_id = "telegraf-factory"
  data_format = "value"
  data_type = "float"

  [[inputs.mqtt_consumer.topic_parsing]]
    topic = "factory/+/+/+"
    measurement = "/#/#/#/3"
    tags = "_/line/machine/_"

The + is a single-level wildcard and # matches all remaining levels. The topic_parsing block pulls pieces out of the topic: the fourth level becomes the measurement, and levels two and three become the tags line and machine. Check the plugin documentation for the exact topic_parsing syntax in your Telegraf version.

For JSON payloads, set data_format = "json_v2" and describe the fields to extract.

QoS matters for reliability: QoS 0 is "at most once" (may lose messages), QoS 1 is "at least once" (may duplicate), QoS 2 is "exactly once" (slowest). Because InfluxDB overwrites points with the same series and timestamp, at-least-once delivery is usually safe, as long as the timestamp is stable.

Stand-in: topic to line protocol

The JavaScript below does what topic_parsing does: split the topic, extract tags, parse the payload and build a line-protocol string. Study how a malformed message is rejected rather than written.

JS Stand-in: turn MQTT messages into line protocol

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Bad messages are counted and skipped, not allowed to crash the pipeline. In production, count them and alert if the share rises.

Device time versus arrival time

Which timestamp goes on the point?

  • Arrival time (when Telegraf received it) is easy and always present, but wrong for devices that buffer and send later.
  • Device time (a timestamp inside the payload) is right for the event, but devices with no real-time clock drift or restart at 1970.

A safe policy: use the device timestamp when it is present and within a plausible window of the arrival time, otherwise fall back to arrival time and add a tag or field flagging the fallback.

Offline devices and gaps

Devices go offline. Decide what a gap means:

  • For a heartbeat or deadman, silence is itself a signal. Use a deadman check (checks and notifications).
  • For charts, do not draw a line across a six-hour gap: show the gap, or fill only short gaps.
  • Devices that buffer while offline will send a burst of old points when they reconnect. Make sure the destination bucket's retention still covers their timestamps.

Stand-in: last known state and silence per device

This SQL finds, for each device, its latest reading and how long it has been silent.

SQL Stand-in: last reading and silence per device

Press Run (or Ctrl + Enter) to see the result here.

The "now" value (1130) is fixed so the output is repeatable; in a real query you would use the current time.

Security and scale

  • Authenticate devices to the broker (username and password or client certificates) and use TLS.
  • Give each device its own credentials and topic permissions, so a compromised sensor cannot publish as another.
  • Use shared subscriptions or several Telegraf instances to spread load from one very busy topic tree.
  • Keep device identity in a stable tag (device_id), not a changing IP or session ID, or you will explode cardinality.
  • Write the raw data to a short-retention bucket and keep aggregated results longer (downsampling).

Common mistakes

  • A topic tree that mixes data types in one measurement.
  • Subscribing to # and ingesting every message on the broker.
  • Trusting device clocks blindly.
  • Not escaping spaces in topic-derived tag values.
  • QoS 0 for data that matters.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What bridges MQTT messages to InfluxDB in a typical setup?

    Telegraf subscribes to MQTT topics and writes the metrics to InfluxDB.
  2. 2. In an MQTT topic filter, what does + match?

    • is the single-level wildcard, # matches everything below.
  3. 3. Why is at-least-once (QoS 1) usually acceptable for InfluxDB?

    A repeated write with the same identity replaces the point instead of duplicating it.
  4. 4. What is a sound policy for timestamps from devices?

    This keeps correct event times without being fooled by bad clocks.

Summary

  • Devices publish to an MQTT broker; Telegraf subscribes and writes to InfluxDB.
  • Topic levels become tags and the measurement; payloads become fields.
  • Choose QoS, timestamps and a stable device tag deliberately.
  • Skip and count malformed messages; alert on silence.
  • Secure the broker with TLS and per-device credentials.

Next: Prometheus and Metrics Bridges