Skip to content

Live supervision (Pro)

This guide is about a sliding timeline of runs arriving live. It builds on the resources and timeline views: read that guide first for resources, rows and the views themselves.

A timeline can also be a wallboard: processes in rows, what is running now at the edge, new facts arriving by themselves, the screen left open for days. The rest of this guide builds that, one piece at a time. Everything here is calendar options and event fields; none of it needs a framework.

A week of hours is too wide to read at a glance. timeline.span is the time on screen at once ({ hours: 4 }, 'PT1H', { days: 1 }): the slots share the room, whatever its width, so four hours fill a phone as they fill a wide screen. A span longer than the period fits the period. A view of your own, in views, can be a timeline of several days, with span showing a part of it.

By default ◀ ▶ change period. With timeline.step ({ minutes: 15 }, { hours: 1 }) they slide along the axis by that much instead, and at the end of the axis the next or previous period comes in. Page Up and Page Down do the same from the keyboard, the time cursor on. For any other amount, calendar.shift({ minutes: -45 }) slides by it, in hours and minutes: days throw a RangeError, as the option does (a day is a period, not a shift).

timeline.ticks draws small marks inside each slot, as on a ruler: { every: 1, label: 5 } is a mark each minute and the time written every fifth. A number is both. The marks are as dense as the room allows: the times only with room to write them, the minute marks only a few pixels apart, so four hours across a laptop screen show the marks without their times.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }],
timeline: { slot: 15, span: { hours: 4 }, step: { minutes: 15 }, ticks: { every: 1, label: 5 } },
});
// A button of your own: back 45 minutes.
document.querySelector('#back45')!.addEventListener('click', () => calendar.shift({ minutes: -45 }));

Use the arrows: the axis slides by a quarter of an hour.

timeline.follow keeps the present in view as time passes: true puts the present’s slot at the left edge; the timeline moves on when the next slot begins. Give it { before: { minutes: 5 } } and the present stays that far from the edge, a little of what just happened in view, the axis gliding each minute (eased by the motion adapter, at once under reduced motion). Following pauses as soon as the person scrolls, slides or changes period, and “Today” takes it up again. onFollowChange says when it pauses and resumes: the place for a “Back to live” button. The line at the present, and the axis with it, move once a minute by default; nowRefresh ({ seconds: 5 }) moves them more often.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const live = document.querySelector<HTMLButtonElement>('#live')!;
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }],
timeline: { slot: 15, span: { hours: 4 }, follow: { before: { minutes: 5 } } },
nowRefresh: { seconds: 5 },
// Paused: the button shows; back to live, it goes.
onFollowChange: (following) => (live.hidden = following),
});
live.addEventListener('click', () => calendar.navigate('today'));

An alert, a deployment, a threshold crossed: a moment, not a stretch. An event with display: 'marker' has a start only; it is drawn as a line where it happened with a flag carrying its title (an end or a duration given is ignored, with a marker-length-ignored warning in calendar.kernel.getProblems()). It sits on its resource’s row beside the runs, and hooks.event can write what the flag says. Next to it, display: 'background' tints a stretch behind the runs, a maintenance window for instance.

A run that has started and has not finished has no end to draw. Mark it ongoing: true: it is drawn from its start to now, striped, its end dashed, and grows each minute. An end or a duration given on it is the length expected: while that end is ahead, the bar reaches it, striped up to now and only outlined in dashes past now (the time still to come); once it is passed, the bar grows with now. When the run finishes, tell the calendar with event.update and ongoing: false, with the real end if you have it, else it ends now. An ongoing event is a timed event, not a series, and forget leaves it alone.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'backup', title: 'Backup' }],
events: [
// Started, expected to last 70 minutes, not finished.
{ id: 'run-1', title: 'Backup', start: '2026-10-21T09:00[Europe/Paris]', duration: { minutes: 70 }, resourceId: 'backup', ongoing: true },
],
});
// It finished, at the time the job reported.
calendar.run({ type: 'event.update', id: 'run-1', patch: { ongoing: false, end: '2026-10-21T10:12:40[Europe/Paris]', tone: 'green' } });

A screen like this is told; it does not ask. liveSource (from @dzcalendar/core/live) opens a feed you write (a WebSocket, an MQTT client, a timer) and hands each message to emit; sseSource is the same for Server-Sent Events, with the browser reconnecting a dropped stream. A message is one of:

Message Effect
{ create } A new event
{ update, patch } The patch laid over the event; extendedProps merged. ongoing: false without an end ends it now
{ remove } The event is gone
{ reset } The whole list again, as after a reconnection

For sseSource, a map function turns each server message into one of these, or null to ignore it.

import { createCalendar } from '@dzcalendar/dom';
import { liveSource, sseSource } from '@dzcalendar/core/live';
import type { LiveMessage } from '@dzcalendar/core/live';
import '@dzcalendar/pro';
// Server-Sent Events: a run starts, then ends.
const runs = sseSource('runs', '/api/runs/stream', {
map: (data): LiveMessage | null => {
const m = data as { kind: 'start' | 'end'; id: string; process: string; at: string; failed?: boolean };
if (m.kind === 'start') return { create: { id: m.id, title: 'Run', start: m.at, resourceId: m.process, ongoing: true } };
return { update: m.id, patch: { ongoing: false, end: m.at, tone: m.failed ? 'red' : 'green' } };
},
});
// Any transport: a WebSocket.
const socket = liveSource('socket', {
connect(emit) {
const ws = new WebSocket('wss://example.com/runs');
ws.onmessage = (e) => emit(JSON.parse(String(e.data)) as LiveMessage);
return () => ws.close(); // called when the source is removed or the calendar destroyed
},
});
createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'import', title: 'Orders import' }],
timeline: { span: { hours: 4 }, follow: true },
sources: [runs, socket],
});

The feed is the authority: a person’s edit to one of its events lasts until the feed’s next message. Keep the source objects in a constant, as a new object is a new source, connected again.

A screen left open for weeks must not grow for ever. forget: { olderThan: { days: 2 } } removes, each minute, the events that ended more than that long ago, from whatever source, without an undo entry or an onEventChange. Ongoing events and series stay, and a live source drops what the calendar forgot.

A row’s head can say more than a title: how many of its runs failed (here, a run’s extendedProps.status), whether one is running now. The calendar’s store tells what changed through kernel.subscribe; read the events again, and give the resources anew only when a summary differs: the heads redraw, nothing else. hooks.resource.content draws the head from the resource’s extendedProps.

import { createCalendar } from '@dzcalendar/dom';
import type { ResourceInput } from '@dzcalendar/core';
import '@dzcalendar/pro';
interface Summary {
readonly running: boolean;
readonly failures: number;
}
const processes: ResourceInput[] = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }];
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: processes,
timeline: { span: { hours: 4 }, follow: true },
forget: { olderThan: { days: 2 } },
hooks: {
resource: {
content: ({ resource }) => {
const x = resource.extendedProps as Partial<Summary>;
const box = document.createElement('div');
box.textContent = `${resource.title ?? resource.id}${x.running ? ' · running' : ''}${x.failures ? ` · ${x.failures} failed` : ''}`;
return box;
},
},
},
});
let said = '';
function summarize(): void {
const by = new Map<string, { running: boolean; failures: number }>(processes.map((p) => [p.id, { running: false, failures: 0 }]));
for (const e of calendar.kernel.store.snapshot.allEvents()) {
const s = by.get(e.resourceIds[0] ?? '');
if (!s || e.allDay) continue;
if (e.ongoing) s.running = true;
else if ((e.props as { status?: string }).status === 'failed') s.failures++;
}
const resources = processes.map((p) => ({ ...p, extendedProps: by.get(p.id) }));
const text = JSON.stringify(resources);
if (text === said) return; // nothing differs: the heads are left alone
said = text;
calendar.update({ resources });
}
let queued = false;
calendar.kernel.subscribe((e) => {
if (e.type !== 'store' || queued) return;
queued = true;
queueMicrotask(() => ((queued = false), summarize()));
});
summarize();

In Angular, React and Vue the head is a template (dzResource, renderResource, #resource: see hooks); the summary is the same, computed from the events you already hold.