Aller au contenu

Supervision en direct (Pro)

Ce guide parle d’une timeline glissante d’exécutions qui arrivent en direct. Il prolonge les ressources et les vues timeline : lisez d’abord ce guide pour les ressources, les lignes et les vues elles-mêmes.

Une timeline peut aussi être un tableau mural : des traitements en lignes, ce qui tourne maintenant au bord, des faits qui arrivent d’eux-mêmes, l’écran laissé ouvert des jours. La suite de ce guide le construit pièce par pièce. Tout tient dans des options du calendrier et des champs d’événement ; rien ne demande un framework.

Une semaine d’heures est trop large pour se lire d’un coup d’œil. timeline.span est le temps affiché à la fois ({ hours: 4 }, 'PT1H', { days: 1 }) : les créneaux se partagent la place, quelle que soit sa largeur, si bien que quatre heures remplissent un téléphone comme un grand écran. Un span plus long que la période épouse la période. Une vue à vous, dans views, peut être une timeline de plusieurs jours dont span montre une partie.

Par défaut ◀ ▶ changent de période. Avec timeline.step ({ minutes: 15 }, { hours: 1 }) ils font glisser l’axe de ce pas, et au bout de l’axe la période suivante ou précédente entre. Page précédente et Page suivante font de même au clavier, le curseur dans le temps. Pour toute autre valeur, calendar.shift({ minutes: -45 }) glisse d’autant, en heures et minutes : des jours lèvent une RangeError, comme pour l’option (un jour est une période, pas un glissement).

timeline.ticks trace de petites graduations dans chaque créneau, comme sur une règle : { every: 1, label: 5 } est un trait chaque minute et l’heure écrite toutes les cinq. Un nombre vaut pour les deux. Les graduations sont aussi denses que la place le permet : les heures seulement si elles ont la place d’être écrites, les traits de minute seulement à quelques pixels d’écart, si bien que quatre heures sur la largeur d’un portable montrent les traits sans leurs heures.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'import', title: 'Import des commandes' }, { id: 'backup', title: 'Sauvegarde' }],
timeline: { slot: 15, span: { hours: 4 }, step: { minutes: 15 }, ticks: { every: 1, label: 5 } },
});
// Un bouton à vous : reculer de 45 minutes.
document.querySelector('#back45')!.addEventListener('click', () => calendar.shift({ minutes: -45 }));

Utilisez les flèches : l’axe glisse d’un quart d’heure.

timeline.follow garde le présent en vue au fil du temps : true met le créneau du présent au bord gauche ; la timeline avance quand le créneau suivant commence. Donnez-lui { before: { minutes: 5 } } et le présent reste à cette distance du bord, un peu de ce qui vient de se passer en vue, l’axe glissant chaque minute (adouci par l’adaptateur de mouvement, d’un coup avec la réduction des animations). Le suivi se met en pause dès que la personne fait défiler, glisse ou change de période, et « Aujourd’hui » le reprend. onFollowChange dit quand il se met en pause et reprend : l’endroit d’un bouton « Retour au direct ». La ligne du présent, et l’axe avec elle, avancent une fois par minute par défaut ; nowRefresh ({ seconds: 5 }) les fait avancer plus souvent.

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: 'Import des commandes' }, { id: 'backup', title: 'Sauvegarde' }],
timeline: { slot: 15, span: { hours: 4 }, follow: { before: { minutes: 5 } } },
nowRefresh: { seconds: 5 },
// En pause : le bouton apparaît ; de retour au direct, il disparaît.
onFollowChange: (following) => (live.hidden = following),
});
live.addEventListener('click', () => calendar.navigate('today'));

Une alerte, un déploiement, un seuil franchi : un instant, pas une durée. Un événement avec display: 'marker' n’a qu’un début ; il est dessiné comme un trait à l’endroit où il s’est produit, avec un fanion portant son titre (une end ou une duration donnée est ignorée, avec un avertissement marker-length-ignored dans calendar.kernel.getProblems()). Il se place sur la ligne de sa ressource à côté des exécutions, et hooks.event peut écrire ce que dit le fanion. À côté, display: 'background' teinte une plage derrière les exécutions, une fenêtre de maintenance par exemple.

Une exécution commencée et pas finie n’a pas de fin à dessiner. Marquez-la ongoing: true : elle est dessinée de son début à maintenant, hachurée, sa fin en pointillé, et grandit chaque minute. Une end ou une duration donnée est la durée prévue : tant que cette fin est à venir, la barre l’atteint, hachurée jusqu’à maintenant et seulement cernée de pointillés au-delà (le temps encore à venir) ; une fois cette fin passée, la barre grandit avec maintenant. Quand l’exécution se termine, dites-le au calendrier avec event.update et ongoing: false, avec la vraie end si vous l’avez, sinon elle se termine maintenant. Un événement en cours est un événement horaire, pas une série, et forget le laisse tranquille.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'backup', title: 'Sauvegarde' }],
events: [
// Commencée, prévue pour 70 minutes, pas terminée.
{ id: 'run-1', title: 'Sauvegarde', start: '2026-10-21T09:00[Europe/Paris]', duration: { minutes: 70 }, resourceId: 'backup', ongoing: true },
],
});
// Elle s’est terminée, à l’heure que la tâche a signalée.
calendar.run({ type: 'event.update', id: 'run-1', patch: { ongoing: false, end: '2026-10-21T10:12:40[Europe/Paris]', tone: 'green' } });

Un écran comme celui-ci reçoit les nouvelles ; il ne les demande pas. liveSource (de @dzcalendar/core/live) ouvre un flux que vous écrivez (un WebSocket, un client MQTT, une minuterie) et passe chaque message à emit ; sseSource fait de même pour les Server-Sent Events, le navigateur rouvrant un flux interrompu. Un message est l’un de ceux-ci :

Message Effet
{ create } Un nouvel événement
{ update, patch } Le patch posé sur l’événement ; extendedProps fusionnés. ongoing: false sans fin le termine maintenant
{ remove } L’événement disparaît
{ reset } Toute la liste à nouveau, comme après une reconnexion

Pour sseSource, une fonction map transforme chaque message du serveur en l’un d’eux, ou en null pour l’ignorer.

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 : une exécution démarre, puis se termine.
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: 'Exécution', start: m.at, resourceId: m.process, ongoing: true } };
return { update: m.id, patch: { ongoing: false, end: m.at, tone: m.failed ? 'red' : 'green' } };
},
});
// N’importe quel transport : un 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(); // appelée quand la source est retirée ou le calendrier détruit
},
});
createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineDay',
resources: [{ id: 'import', title: 'Import des commandes' }],
timeline: { span: { hours: 4 }, follow: true },
sources: [runs, socket],
});

Le flux fait autorité : la modification d’un de ses événements par une personne dure jusqu’au message suivant du flux. Gardez les objets source dans une constante : un nouvel objet est une nouvelle source, reconnectée.

Un écran laissé ouvert des semaines ne doit pas grossir sans fin. forget: { olderThan: { days: 2 } } retire, chaque minute, les événements terminés depuis plus longtemps que cela, de n’importe quelle source, sans entrée d’annulation ni onEventChange. Les événements en cours et les séries restent, et une source en direct oublie ce que le calendrier a oublié.

L’en-tête d’une ligne peut en dire plus qu’un titre : combien de ses exécutions ont échoué (ici, le extendedProps.status d’une exécution), s’il y en a une en cours. Le store du calendrier dit ce qui a changé par kernel.subscribe ; relisez les événements, et ne redonnez les ressources que lorsqu’un résumé diffère : les en-têtes se redessinent, rien d’autre. hooks.resource.content dessine l’en-tête à partir des extendedProps de la ressource.

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: 'Import des commandes' }, { id: 'backup', title: 'Sauvegarde' }];
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 ? ' · en cours' : ''}${x.failures ? ` · ${x.failures} en échec` : ''}`;
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; // rien n’a changé : les en-têtes sont laissés tels quels
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();

Dans Angular, React et Vue l’en-tête est un gabarit (dzResource, renderResource, #resource : voir hooks) ; le résumé est le même, calculé à partir des événements que vous détenez déjà.