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:
1 parent
31044b2b64
commit
3b31b16796
31 files changed
+7706
-61
No files matched your search
@@ -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}.` };
|
||||
}
|
||||
Reference in new issue
Block a user