An MQTT message can arrive at the broker or historian long after the physical measurement occurred. If that arrival time becomes the historian timestamp, a trend may show an old pressure reading as a new process condition. During an outage replay, that can distort aggregates, alarms, and the apparent order of events.
The timestamp policy should answer one question clearly: When did this industrial observation represent the process? For most time-series analysis, that is the source event time. Ingestion time remains valuable, but it describes transport and processing chronology rather than the process itself.
MQTT does not supply a universal process-time field
Plain MQTT defines the transport of an application message. It does not prescribe a JSON field called timestamp, an industrial clock model, or the meaning of a time value inside a payload. The publisher and its application contract decide whether a payload contains a time, its format, and its quality.
Do not transfer OPC UA timestamp names to ordinary MQTT payloads. OPC UA has defined SourceTimestamp and ServerTimestamp concepts; a plain MQTT publication has only the fields its publisher supplies. A broker receipt time and a connector receipt time are useful operational observations, but they are not automatically evidence of when a machine produced a measurement.
Consider this illustrative payload:
{
"asset_id": "compressor-12",
"event_time": "2026-10-27T08:15:04.125Z",
"discharge_pressure_kpa": 742.6
}
event_time may be the right historical time if the gateway defines it as the observation time and its clock is trustworthy. A field named ts is not enough by itself. Its unit, timezone, source, and behavior during restart still need to be agreed and tested.
Keep source, broker, and ingestion time separate
Three different clocks can appear in one path:
| Time | What it describes | Typical use |
|---|---|---|
| Source event time | When the device or gateway observed the condition | Trends, calculations, sequence analysis, historical investigation |
| Broker receipt time | When the broker accepted the PUBLISH | Transport diagnostics and broker operations |
| Ingestion time | When the collector or database pipeline processed the message | Latency monitoring, backlog analysis, troubleshooting |
Choose source event time as the record time when the application needs a truthful process chronology and the source can supply a valid value. Preserve an ingestion or receipt time separately when the system needs to explain delay. This lets an engineer distinguish a late delivery from a late event.
There are valid exceptions. A simple device may not have a reliable clock, an upstream payload may carry only a sequence number, or a protocol gateway may sample data without an event timestamp. In that case, use a clearly documented collection or ingestion time rather than inventing a source time. The resulting record is still useful, but downstream users must know it represents observation by the collector, not necessarily the exact process instant.
Validate clock, timezone, precision, and epoch unit
Timestamp errors are often plausible enough to escape a connection test. Build validation into the source-data contract:
- Require an unambiguous timezone convention, preferably an ISO 8601 value with
Zor an explicit offset. - For integer epochs, state whether the value is seconds, milliseconds, microseconds, or nanoseconds; do not infer the unit from the digit count alone.
- Define acceptable future skew and stale-data limits for each source class.
- Monitor source-clock health and resynchronize gateways after replacement, reboot, or loss of time service.
- Decide how to handle null, malformed, or out-of-range time: reject, archive, flag, or use arrival time under an explicit policy.
For TDengine, the timestamp is the primary key for time-series data. Its database precision determines how integer timestamps are interpreted, and the default precision is milliseconds. The current TDengine data types and precision documentation should therefore be checked against the target database before mapping a numeric time field. Do not assume that a millisecond payload can be safely interpreted as microseconds or nanoseconds merely because a connector accepts it.
Design for late, replayed, and out-of-order records
Network interruption, local buffering, broker queues, and retry can delay a message. The later arrival does not make the measurement newer. Store source event time as the historical axis when it is valid, then configure queries, downstream windows, and alerts to tolerate late arrivals where the use case requires it.
Out-of-order arrival is normal in a distributed path. A live message can reach the historian while an older message is still waiting in a buffer. A query sorted by event time can show the process correctly; an operational view based on ingestion order can expose the backlog. Do not use one timestamp to answer both questions without declaring the compromise.
Duplicates also interact with time. A retransmitted message can have the same source time as the original. If a source provides a stable sequence number or event identifier, retain it for validation and define the duplicate policy. MQTT QoS or broker receipt does not validate either the source clock or the business meaning of the time field.
Test the timestamp policy with controlled late data
Run a test that deliberately separates source time from delivery time:
- Publish a small series with known event times and a source identifier.
- Delay one message, then deliver it after a newer measurement.
- Replay a previously sent message and include an intentionally malformed or wrong-unit timestamp.
- Query by event time and inspect the arrival or ingestion evidence separately.
- Confirm the expected handling for duplicates, null time, stale data, and future time.
The pass condition is not simply that every message produced a row. It is that the historian explains process sequence accurately, exposes transport delay when needed, and handles invalid time according to an agreed rule.
Make timestamp meaning part of the data contract
Document each measurement class with its time owner, format, precision, timezone, allowable clock drift, fallback behavior, and any additional arrival-time field. Review the contract when a PLC, edge gateway, firmware version, or broker route changes.
That discipline makes a time-series database more useful for investigations and analysis: stored values retain a defensible relationship to the process that produced them. Without it, a technically successful MQTT pipeline can still create misleading history.
