Configuring an MQTT (JSON) collector

the mqtt collector in factry historian allows you to subscribe to mqtt broker topics and historize incoming data once configured, the data becomes available for trending, reporting, and further analysis prerequisites permissions in factry historian to manage collectors see docid\ k2nnyecuxqqsiuclmpfkh an installed mqtt collector if you have not done so already, first docid\ iv4 sd56tdxcqkrkcj4kv a running mqtt broker that your collector can connect to if you are running into issues or setting this up for the first time, follow our guide to docid 9wwofhat2n58ssdmpv2rv optional but strongly recommended tls certificates for secure broker communication a configured docid\ sq5uvlchyg7umi930nyml to write the collected data to configure the collector after installing the collector, you should see that the collector is in an initial state initial state and is actively running this means that the collector has established a connection to factry historian and is awaiting further configuration to configure the collector, select it from the collectors overview in factry historian and click the edit button configure the following fields mqtturl this is the connection url of the mqtt broker the collector should connect to the url must point to a reachable broker instance for example tcp\ //broker example com 1883 # without tls ssl //broker example com 8883 # with tls (recommended for production) clientcertificate determines whether the collector uses a client certificate to authenticate with the broker false (default) no client certificate is used true the collector will attempt to use a configured certificate and private key to authenticate use this option only if your broker requires client side certificates username and password if your mqtt broker requires user authentication , enter a valid username and password here leave empty if your broker allows anonymous connections (only suitable for test environments) in production, authentication is strongly recommended topics a comma separated list of topics the collector should subscribe to wildcards are supported \+ matches exactly one level # matches multiple levels and must be the last character in the topic for example factory/+/temperature factory/# this field is required qos the quality of service (qos) level with which the collector subscribes to topics 0 at most once messages may be lost, no retries 1 at least once (default) messages are retried until acknowledged may result in duplicates 2 exactly once highest reliability, no duplicates more overhead for most industrial data, qos 1 offers the best balance between reliability and performance persistentsession controls whether the mqtt session is persistent true (default) the broker stores session information and caches messages while the collector is offline, delivering them once it reconnects false no session state is stored messages published while the collector is offline will be lost keep persistent sessions enabled in production to avoid losing data during temporary outages time & timestamps the default layout of the timestamp for measurements if empty, rfc3339 will be used if timestamps are in unix format, use one of unix | unixmillis | unixmicros | unixnanos more info https //pkg go dev/time#layout examples rfc3339 2025 09 18t09 45 00z unix 1695020700 unixmillis 1695020700000 unixmicros 1695020700000000 unixnanos 1695020700000000000 you can override the collector’s default per measurement by setting timestamplayout together with timestamppath on that measurement in rfc3339, a timestamp must include either z (utc) or an explicit offset (e g , +02 00) to avoid ambiguity adding measurements follow the guide on docid\ zhuyjz8ftlrp t3tsbul1 best practices use tls to secure connections in production prefer qos 1 for most industrial data, unless message duplication is unacceptable keep topics structured and predictable avoid deep hierarchies with wildcards everywhere validate jsonpath expressions before deploying, using tools like jsonpath com sync clocks on broker, collector, and clients with ntp to avoid timestamp issues limits a single collector can handle thousands of topics and high frequency messages limitations usually arise at the broker level (throughput, connections) or in the json parsing overhead if performance becomes an issue, consider splitting topics across multiple collectors troubleshooting mqtt collector typical issues collector shows "disconnected" → check broker address, credentials, and tls certificates messages received but no measurements → verify jsonpath expressions in measurement configuration timestamps not parsed → ensure correct timestamplayout is set