Skip to main content
Version: 0.1

Investigate an incident with replay

This guide replays the plant as it was around an incident. It is for an operator or engineer who wants to see what happened in the minutes before an alarm, in the same screens they use live. A replay is private to one browser: live data and everyone else's screens are not touched, and nothing can be written until you are back to live. See History and replay for the mechanism.

Prerequisites​

  • The viewer role or higher; a replay needs nothing more.
  • The incident within what the gateway still holds. The gateway keeps recorded values for a limited time: 7 days unless EventBackbone__ValueRetention says otherwise, see Configuration. Alarm history is kept for a year by default.
  • A screen that shows the part of the plant concerned, and ideally a trend widget on the tags involved.

Steps​

1. Pick the time​

Find when the incident happened. Alarms, History lists each alarm's lifecycle with its time, and GET /api/v1/alarms/history?from&to returns the same over the API (Alarms API). Note the time a few minutes before the first alarm went active.

2. Start the replay from the clock​

  1. In the top bar, the clock shows the gateway's time (the tag @gateway.time). Click it; the tooltip reads "Gateway time ..., Open to replay the past." A Replay panel opens.
  2. Switch the control at the top from Live to Replay.
  3. Under Start, enter the date and time, or press one of the Ago: presets to start a while back from now.
  4. Leave End (optional) empty to play on until the replay has caught up with now, or set it to stop at a time.
  5. Press Start replay.

The phase line reads Opening the recording, then Playing at the recorded pace. The clock in the top bar now shows the replayed time with a Replay pill, a band runs under the bar, and the tab title is marked, so the mode is visible from every page.

On a phone, where the clock is not shown, the same controls are on the Replay page.

What the gateway does: it finds the newest hourly checkpoint at or before your start time (looking back up to six hours), folds in the values recorded between the checkpoint and the start, sends that as the opening state, then plays the recorded values on at their recorded pace, with the clock once a second and each alarm event at its own recorded time.

3. Watch a screen​

Open the screen of the area. Every widget shows the value the tag had at the replayed moment and moves as the replay plays: states change color, numbers move, and symbols with alarm colors follow the replayed alarms. Go to another page and back; the mode is the whole browser's, so every page shows the past until you return to live.

4. Watch the alarm list​

Open Alarms. The list shows the alarms that were outstanding at the start, most severe first, and then each activation, acknowledgement and clearing as it was recorded. The name, severity, condition and setpoint are the ones the alarm had at the time. Acknowledging or shelving is refused during a replay; the dashboard shows a message when it is tried.

5. Watch a trend​

A trend widget on the screen, or the history pane of a tag in the tag browser, shows the recorded values around the replayed time and follows it as the replay plays. The data comes from the historian when the module runs, otherwise from what the event backbone retains, so a trend may reach further back than the replay can start (see How far back it works).

6. Pause, resume, jump​

In the replay panel (click the clock again):

  • Pause holds values, clock and alarms where they are; Resume plays on. A replay cannot be sped up or slowed down.
  • The progress bar and the line beneath it say where the replay is: "From ... to ...", or "until it has caught up with now".
  • Jump to another time and Go start again from a new time; the end, if set, is kept when it is still ahead.
  • Gaps of more than 5 seconds in the recording are shortened to 5 seconds, so a quiet night passes quickly.

When the replay reaches its end the phase reads Finished and the panel says "The recording ends here. The screens show the plant as it was at this time." It is still a replay until you go back to live.

7. Go back to live​

Press Back to live, or switch the control to Live. Every subscriber is handed its tag's live value at once, the alarm list is read afresh, and writing is possible again. Closing the browser tab ends the replay as well.

What is and is not replayed​

ReplayedNot replayed
Every tag the session may read, with its recorded values and qualitiesTags private to a user or a session (user- and session-scoped memory tags)
The gateway clock, @gateway.timeThe other @gateway tags, which keep their live value
Alarms: the outstanding set at the start, then each active, acknowledged, cleared, shelved and unshelved event at its recorded timeAn alarm's deadband and on-delay, which history does not hold (a replayed alarm shows 0); whether it was stale; the value between its transitions
Alarm name, severity, condition and setpoint as they were at the timeAlarm acknowledgements and writes: both are refused while replaying

How far back it works​

A replay is built from two things the event backbone keeps: the value stream, retained for EventBackbone__ValueRetention (7 days by default), and the hourly checkpoints of every tag's last value, kept for that retention plus two hours. Starting at a time with no checkpoint within the six hours before it still works: the gateway folds in the last hour of values instead, so a tag that stood still for longer may have no opening value.

The historian module keeps samples for its own retentionDays and answers trends, but a replay does not play from it. So a trend can show last month, while a replay can only start within the backbone's retention. Alarm history, from Alarms__EventRetention (a year by default), is read for whatever range the replay covers; further back, the replay shows no alarms. If the alarm history cannot be read the replay goes on with the values and says so in a warning line.

The gateway runs at most 8 replays at once, one per socket, and a replay that falls too far behind is disconnected like any slow client.

Where to go next​