Service-level targets with error budgets, and quarterly and annual reports

Monitoring -> Service levels: a target (99.9 %) on an endpoint check, a server or an
integration, measured over calendar months. Shows the figure, downtime used, the
error budget left, and how the last six months went. 80 % of the budget used is a
warning and an overspent budget a critical alert. Endpoints are measured day by day,
servers and integrations to the minute from the audit log.

The report page gains Quarter and Year (same figures, with a Service levels section),
and two settings send the quarterly and annual report after the month that ends them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 22:20:07 +02:00
1 parent 31044b2b64
commit 3b31b16796
31 files changed
+7706 -61

No files matched your search

+94 -12
View File
@@ -1,5 +1,5 @@
/**
* The monthly report: how a month went — availability of servers, integrations and endpoints, incidents and how long they took, updates applied (by hand and by
* The monthly report (and, by the same figures over longer stretches, the quarterly and annual ones): how a month went — availability of servers, integrations and endpoints, incidents and how long they took, updates applied (by hand and by
* patch plans), restore tests and the state of the backups, and what was renewed. Everything in it the app already knows; this gathers it for one calendar month
* (on the clock of the notification time zone) into one structure that the page shows, prints and exports, and into a plain-text version that can be sent like the
* weekly digest.
@@ -18,6 +18,7 @@ import { renewalsBetween } from "./renewals.js";
import { getSettings } from "./settingsStore.js";
import { getUptime } from "./uptimeHistory.js";
import { spanWords } from "./weeklyDigest.js";
import { levelResultsFor, type PeriodResult } from "./serviceLevels.js";
const DAY_MS = 86_400_000;
const MAX_LISTED = 12;
@@ -38,10 +39,14 @@ export interface EndpointRow {
checks: number;
}
export type PeriodKind = "month" | "quarter" | "year";
export interface MonthlyReport {
/** "2026-09". */
/** What stretch it is about: a month (id "2026-09"), a quarter ("2026-Q3") or a year ("2026"). */
period: PeriodKind;
/** The id of that stretch. (Named for the month, which is what it was made for.) */
month: string;
/** "September 2026". */
/** "September 2026", "Q3 2026", "2026". */
label: string;
/** ISO — the start of the month and its end (or now, for a month that is not over). */
from: string;
@@ -52,6 +57,8 @@ export interface MonthlyReport {
servers: AvailabilityRow[];
integrations: AvailabilityRow[];
endpoints: EndpointRow[];
/** How each service-level target did over the stretch (those with a figure for it). */
serviceLevels: PeriodResult[];
incidents: {
began: number;
resolved: number;
@@ -94,6 +101,17 @@ function monthOf(now: Date, tz: string): { year: number; month: number } {
}
export const monthId = (year: number, month: number) => `${year}-${pad(month)}`;
export function isQuarterId(v: unknown): boolean {
return typeof v === "string" && /^\d{4}-Q[1-4]$/.test(v);
}
export function isYearId(v: unknown): boolean {
return typeof v === "string" && /^\d{4}$/.test(v);
}
export const isPeriodId = (v: unknown): v is string => isMonthId(v) || isQuarterId(v) || isYearId(v);
export function periodKind(id: string): PeriodKind {
return isQuarterId(id) ? "quarter" : isYearId(id) ? "year" : "month";
}
const shift = (year: number, month: number, by: number) => {
const index = year * 12 + (month - 1) + by;
return { year: Math.floor(index / 12), month: (index % 12) + 1 };
@@ -121,6 +139,61 @@ export function recentMonths(now: Date, tz: string, count = 12): { id: string; l
});
}
export function periodLabel(id: string): string {
if (isQuarterId(id)) return `Q${id.slice(6)} ${id.slice(0, 4)}`;
return isYearId(id) ? id : monthLabel(id);
}
/** The year and quarter (1–4) `now` is in. */
function quarterOf(now: Date, tz: string): { year: number; quarter: number } {
const { year, month } = monthOf(now, tz);
return { year, quarter: Math.ceil(month / 3) };
}
/** The last whole quarter ("2026-Q2" in July), and the last whole year. */
export function lastFullQuarter(now: Date, tz: string): string {
const { year, quarter } = quarterOf(now, tz);
return quarter === 1 ? `${year - 1}-Q4` : `${year}-Q${quarter - 1}`;
}
export const lastFullYear = (now: Date, tz: string) => String(monthOf(now, tz).year - 1);
/** What can be asked for: this month and eleven before it, this quarter and seven before it, this year and two before it — newest first. */
export function recentPeriods(now: Date, tz: string): { months: { id: string; label: string }[]; quarters: { id: string; label: string }[]; years: { id: string; label: string }[] } {
const { year, quarter } = quarterOf(now, tz);
const quarters = Array.from({ length: 8 }, (_, i) => {
const index = year * 4 + (quarter - 1) - i;
const id = `${Math.floor(index / 4)}-Q${(index % 4) + 1}`;
return { id, label: periodLabel(id) };
});
const years = Array.from({ length: 3 }, (_, i) => ({ id: String(year - i), label: String(year - i) }));
return { months: recentMonths(now, tz), quarters, years };
}
export interface PeriodBounds {
start: Date;
end: Date;
/** The first UTC day of it and of what follows, as "YYYY-MM-DD", for the figures kept per UTC day. */
firstDay: string;
nextFirstDay: string;
}
/** The instants a month, quarter or year begins and ends at, on the clock of `tz`. */
export function periodBounds(id: string, tz: string): PeriodBounds {
if (isYearId(id)) {
const y = Number(id);
return { start: zonedTime(y, 1, 1, 0, 0, tz), end: zonedTime(y + 1, 1, 1, 0, 0, tz), firstDay: `${y}-01-01`, nextFirstDay: `${y + 1}-01-01` };
}
if (isQuarterId(id)) {
const y = Number(id.slice(0, 4));
const first = (Number(id.slice(6)) - 1) * 3 + 1;
const next = shift(y, first, 3);
return { start: zonedTime(y, first, 1, 0, 0, tz), end: zonedTime(next.year, next.month, 1, 0, 0, tz), firstDay: `${y}-${pad(first)}-01`, nextFirstDay: `${monthId(next.year, next.month)}-01` };
}
const [y, m] = id.split("-").map(Number);
const next = shift(y, m, 1);
return { ...monthBounds(id, tz), firstDay: `${id}-01`, nextFirstDay: `${monthId(next.year, next.month)}-01` };
}
/** The instants a month begins and ends at, on the clock of `tz`. */
export function monthBounds(id: string, tz: string): { start: Date; end: Date } {
const [y, m] = id.split("-").map(Number);
@@ -135,7 +208,8 @@ const round1 = (n: number) => Math.round(n * 10) / 10;
export async function buildMonthlyReport(id: string, now: Date = new Date()): Promise<MonthlyReport> {
const settings = await getSettings();
const tz = settings.notifications.timezone || "UTC";
const { start, end: fullEnd } = monthBounds(id, tz);
const bounds = periodBounds(id, tz);
const { start, end: fullEnd } = bounds;
const partial = fullEnd.getTime() > now.getTime();
const end = partial ? now : fullEnd;
const days = Math.max(1, Math.ceil((end.getTime() - start.getTime()) / DAY_MS));
@@ -154,10 +228,8 @@ export async function buildMonthlyReport(id: string, now: Date = new Date()): Pr
// Endpoints: from the daily figures, for the days the month covers. The figures are per UTC day, so a day at either end can belong to a neighbouring month
// by a few hours (more than the time zone is ahead of UTC); a month that is not over takes in today.
const [yy, mm] = id.split("-").map(Number);
const following = shift(yy, mm, 1);
const firstDay = `${id}-01`;
const lastDayExclusive = partial ? new Date(now.getTime() + DAY_MS).toISOString().slice(0, 10) : `${monthId(following.year, following.month)}-01`;
const firstDay = bounds.firstDay;
const lastDayExclusive = partial ? new Date(now.getTime() + DAY_MS).toISOString().slice(0, 10) : bounds.nextFirstDay;
const dailyRows = await db.select().from(endpointDaily).where(and(gte(endpointDaily.day, firstDay), lt(endpointDaily.day, lastDayExclusive)));
const checkNames = new Map((await db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks)).map((c) => [c.id, c.name]));
const perCheck = new Map<number, { total: number; ok: number; msSum: number; msCount: number }>();
@@ -175,7 +247,7 @@ export async function buildMonthlyReport(id: string, now: Date = new Date()): Pr
.sort((a, b) => (a.percent ?? 101) - (b.percent ?? 101) || a.name.localeCompare(b.name));
// Incidents.
const all = await listIncidents({ now: end, limit: 3000 });
const all = await listIncidents({ now: end, limit: 20000 });
const inMonth = (iso: string) => iso >= startIso && iso < endIso;
const began = all.filter((i) => inMonth(i.openedAt));
const resolved = all.filter((i) => i.resolvedAt !== null && inMonth(i.resolvedAt));
@@ -209,8 +281,9 @@ export async function buildMonthlyReport(id: string, now: Date = new Date()): Pr
const renewalRows = await renewalsBetween(start, end);
return {
period: periodKind(id),
month: id,
label: monthLabel(id),
label: periodLabel(id),
from: startIso,
to: endIso,
partial,
@@ -218,6 +291,7 @@ export async function buildMonthlyReport(id: string, now: Date = new Date()): Pr
servers: rowsOf(uptime.servers, serverNames),
integrations: rowsOf(uptime.integrations, integrationNames),
endpoints: endpointRows,
serviceLevels: await levelResultsFor(start, fullEnd, now),
incidents: {
began: began.length,
resolved: resolved.length,
@@ -274,6 +348,13 @@ export function monthlyReportText(r: MonthlyReport): { title: string; message: s
if (integrationAvg !== null) avail.push(`Integrations: ${integrationAvg}% on average.`);
lines("Availability", avail);
if (r.serviceLevels.length > 0) {
const missed = r.serviceLevels.filter((l) => !l.met);
const body = [`${r.serviceLevels.length - missed.length} of ${plural(r.serviceLevels.length, "target")} met${r.partial ? " so far" : ""}.`];
for (const l of r.serviceLevels.slice(0, 8)) body.push(`- ${l.name}: ${l.percent}% against ${l.target}% — ${l.met ? "met" : "MISSED"} (down ${l.downMinutes > 0 ? spanWords(l.downMinutes) : "not at all"}, ${l.allowedMinutes >= 1 ? spanWords(l.allowedMinutes) : "under a minute"} allowed)`);
lines("Service levels", body);
}
const inc = r.incidents;
if (inc.began > 0 || inc.resolved > 0 || inc.stillOpen > 0) {
const body = [`${plural(inc.began, "incident")} began, ${inc.resolved} ended, ${inc.stillOpen} still open.`];
@@ -298,6 +379,7 @@ export function monthlyReportText(r: MonthlyReport): { title: string; message: s
lines("Renewed", r.renewals.slice(0, 10).map((x) => `- ${x.kind === "domain" ? "Domain" : "Certificate"} ${x.subject}: ${x.fromDate} → ${x.toDate}`));
const title = `Homelab monthly report — ${r.label}${r.partial ? " (so far)" : ""}`;
return { title, message: sections.length > 0 ? sections.join("\n\n") : "Nothing was recorded for this month." };
const noun = r.period === "year" ? "annual" : r.period === "quarter" ? "quarterly" : "monthly";
const title = `Homelab ${noun} report — ${r.label}${r.partial ? " (so far)" : ""}`;
return { title, message: sections.length > 0 ? sections.join("\n\n") : `Nothing was recorded for this ${r.period}.` };
}