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.
Showing a span
Section titled “Showing a span”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.
Sliding by a step
Section titled “Sliding by a step”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).
A ruler
Section titled “A ruler”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 }));import { Component, viewChild } from '@angular/core';import { DZ_CALENDAR, DzCalendar } from '@dzcalendar/angular';import '@dzcalendar/pro';
@Component({ selector: 'app-supervision', imports: [DZ_CALENDAR], template: ` <button (click)="cal().controller.shift({ minutes: -45 })">Back 45 minutes</button> <dz-calendar #calendar timeZone="Europe/Paris" view="resourceTimelineDay" [resources]="processes" [options]="options" />`,})export class Supervision { readonly cal = viewChild.required<DzCalendar>('calendar'); readonly processes = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }]; readonly options = { timeline: { slot: 15, span: { hours: 4 }, step: { minutes: 15 }, ticks: { every: 1, label: 5 } }, };}import { DzCalendar, useCalendarController } from '@dzcalendar/react';import '@dzcalendar/pro';
const PROCESSES = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }];const TIMELINE = { slot: 15, span: { hours: 4 }, step: { minutes: 15 }, ticks: { every: 1, label: 5 } };
export function Supervision() { const controller = useCalendarController(); return ( <> <button onClick={() => controller.shift({ minutes: -45 })}>Back 45 minutes</button> <DzCalendar controller={controller} timeZone="Europe/Paris" defaultView="resourceTimelineDay" resources={PROCESSES} timeline={TIMELINE} /> </> );}<script setup lang="ts">import { DzCalendar, createCalendarController } from '@dzcalendar/vue';import '@dzcalendar/pro';
const processes = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }];const controller = createCalendarController();const options = { timeline: { slot: 15, span: { hours: 4 }, step: { minutes: 15 }, ticks: { every: 1, label: 5 } },};</script>
<template> <button @click="controller.shift({ minutes: -45 })">Back 45 minutes</button> <DzCalendar :controller="controller" time-zone="Europe/Paris" view="resourceTimelineDay" :resources="processes" :options="options" /></template>Use the arrows: the axis slides by a quarter of an hour.
Following the present
Section titled “Following the present”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'));import { Component, signal, viewChild } from '@angular/core';import { DZ_CALENDAR, DzCalendar } from '@dzcalendar/angular';import '@dzcalendar/pro';
@Component({ selector: 'app-supervision', imports: [DZ_CALENDAR], template: ` @if (!following()) { <button (click)="cal().controller.today()">Back to live</button> } <dz-calendar #calendar timeZone="Europe/Paris" view="resourceTimelineDay" [resources]="processes" [options]="options" />`,})export class Supervision { readonly cal = viewChild.required<DzCalendar>('calendar'); readonly following = signal(true); readonly processes = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }]; readonly options = { timeline: { slot: 15, span: { hours: 4 }, follow: { before: { minutes: 5 } } }, nowRefresh: { seconds: 5 }, onFollowChange: (f: boolean) => this.following.set(f), };}import { useState } from 'react';import { DzCalendar, useCalendarController } from '@dzcalendar/react';import '@dzcalendar/pro';
const PROCESSES = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }];const TIMELINE = { slot: 15, span: { hours: 4 }, follow: { before: { minutes: 5 } } };const EVERY_FIVE_SECONDS = { seconds: 5 };
export function Supervision() { const [following, setFollowing] = useState(true); const controller = useCalendarController(); return ( <> {!following && <button onClick={() => controller.today()}>Back to live</button>} <DzCalendar controller={controller} timeZone="Europe/Paris" defaultView="resourceTimelineDay" resources={PROCESSES} timeline={TIMELINE} nowRefresh={EVERY_FIVE_SECONDS} onFollowChange={setFollowing} /> </> );}<script setup lang="ts">import { ref } from 'vue';import { DzCalendar, createCalendarController } from '@dzcalendar/vue';import '@dzcalendar/pro';
const processes = [{ id: 'import', title: 'Orders import' }, { id: 'backup', title: 'Backup' }];const following = ref(true);const controller = createCalendarController();const options = { timeline: { slot: 15, span: { hours: 4 }, follow: { before: { minutes: 5 } } }, nowRefresh: { seconds: 5 }, onFollowChange: (f: boolean) => (following.value = f),};</script>
<template> <button v-if="!following" @click="controller.today()">Back to live</button> <DzCalendar :controller="controller" time-zone="Europe/Paris" view="resourceTimelineDay" :resources="processes" :options="options" /></template>Markers
Section titled “Markers”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.
Ongoing events
Section titled “Ongoing events”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' } });Live sources
Section titled “Live sources”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.
Forgetting the old
Section titled “Forgetting the old”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.
Process heads
Section titled “Process heads”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.
See also
Section titled “See also”- Resources & timeline: resources, the tree, and the timeline views.
resourcesandtimeline: every field and setting.- Views: the other views, and views of your own.
- Events: every field of an event, and the commands that change one.
- Event sources: URL, function and iCalendar sources.