Live streams

Collector: OPC UA history

Backfill a time range or fill gaps from an OPC UA server’s own history.

OPC UA history and backfill

Many OPC UA servers keep their own history of the values they serve (OPC UA Historical Access). The collector can read it to fill a time range it did not collect: a period before it was installed, or a gap while it could not reach the server. Values read from history always reach Kymoscope marked as history, so viewers never take them for live data. They are only as detailed as the server’s history, which often stores one value every 1 to 5 seconds or only changes beyond a deadband.

Backfill a time range

kymoscope-collector backfill reads the range from --from (included) to --to (excluded) for every tag in the source’s tags.csv and sends it into the source’s stream. Times are ISO 8601; a time without a zone is the host’s local time. It returns once everything is sent. What could not be sent stays in the state folder and goes with the next backfill. When the stream takes nothing for two minutes (Kymoscope unreachable, or the sender waiting for a project member’s approval) it stops with an error: run it again once the stream is online.

Shell

# Send one day of the OPC UA server's own history into the source's stream, marked as history
kymoscope-collector backfill --config collector.yaml --source "Customer A DCS" --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z

Fill gaps automatically

With backfill_gaps: true, when the connection to the server is lost and comes back, the collector reads the server’s history for each tag from the last value it received to its first live value after the reconnect, in the background while live values keep flowing. The same happens for the time the collector itself was stopped: it remembers the last value sent for each tag in its state folder. Nothing older than backfill_max_h hours is read automatically; use kymoscope-collector backfill for the rest. A gap whose backfill fails (for example, the connection drops again) is retried on the next connection, also after a restart.

collector.yaml

sources:
  - name: Customer A DCS
    type: opcua
    url: opc.tcp://dcs-gw:4840
    tags: tags.csv
    backfill_gaps: true    # after a lost connection or a restart, read the gap from the server's history
    backfill_max_h: 24     # never more than the last 24 hours of a gap
    history_rate: 2        # at most 2 history requests per second

Key	Meaning and default
`history_rate`	Maximum history requests per second, for backfill and gap backfill. Default 2. Raise it only when the server owner agrees.
`backfill_gaps`	Default false. true reads the gap from the server’s history after a lost connection or a restart of the collector.
`backfill_max_h`	The longest gap read automatically, in hours. Default 24.

What the server needs

Historical Access (OPC UA Part 11) with raw reads (HistoryRead, ReadRawModifiedDetails). Many DCS gateways, Kepware with its Local Historian, Ignition and most historians’ OPC UA servers offer it; plain PLC servers usually do not.
History kept for each tag you want back: the node is Historizing and its AccessLevel includes HistoryRead. Ask the site to enable history for the tags in tags.csv and to give the collector’s read-only user the right to read history.

A tag the server keeps no history for, or a server without Historical Access, does not stop the backfill: the collector logs it once per tag and reads the others. The health stream counts them in <source>.history_unavailable, next to history_values (values read from history) and gaps_backfilled.

Load on the control system

History reads cost the server more than live subscriptions, so the collector keeps them gentle: at most history_rate requests per second, no more tags per request than the server’s MaxNodesPerHistoryReadData limit (and never more than 500), at most 10,000 values per tag per request, and the server’s continuation points to page through long ranges. Memory stays bounded however long the range is.