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,6 +1,6 @@
|
||||
import { Router } from "express";
|
||||
import { requireAuth, requireRole } from "../auth/middleware.js";
|
||||
import { buildMonthlyReport, isMonthId, lastFullMonth, monthlyReportText, recentMonths } from "../services/monthlyReport.js";
|
||||
import { buildMonthlyReport, isPeriodId, lastFullMonth, monthlyReportText, recentPeriods } from "../services/monthlyReport.js";
|
||||
import { recordAudit } from "../services/audit.js";
|
||||
import { notifyNow } from "../services/notify.js";
|
||||
import { getSettings } from "../services/settingsStore.js";
|
||||
@@ -10,29 +10,30 @@ export const reportsRouter = Router();
|
||||
|
||||
reportsRouter.use(requireAuth);
|
||||
|
||||
/** The month asked for, or the last whole one; null when what was asked is not a month. */
|
||||
async function monthFrom(query: unknown): Promise<{ id: string; months: { id: string; label: string }[] } | null> {
|
||||
/** The month, quarter or year asked for, or the last whole month; null when what was asked is not one that can be had. */
|
||||
async function monthFrom(query: unknown): Promise<({ id: string } & ReturnType<typeof recentPeriods>) | null> {
|
||||
const tz = (await getSettings()).notifications.timezone || "UTC";
|
||||
const months = recentMonths(new Date(), tz);
|
||||
if (query === undefined || query === "") return { id: lastFullMonth(new Date(), tz), months };
|
||||
if (!isMonthId(query) || !months.some((m) => m.id === query)) return null;
|
||||
return { id: query, months };
|
||||
const options = recentPeriods(new Date(), tz);
|
||||
if (query === undefined || query === "") return { id: lastFullMonth(new Date(), tz), ...options };
|
||||
const all = [...options.months, ...options.quarters, ...options.years];
|
||||
if (!isPeriodId(query) || !all.some((m) => m.id === query)) return null;
|
||||
return { id: query, ...options };
|
||||
}
|
||||
|
||||
// How a month went, for everyone signed in: it is only what the pages it comes from already show them. ?month=2026-09, the last whole month by default;
|
||||
// ?format=text is the plain-text version a notification carries.
|
||||
// How a month, a quarter or a year went, for everyone signed in: it is only what the pages it comes from already show them. ?month=2026-09 (or ?month=2026-Q3,
|
||||
// ?month=2026), the last whole month by default; ?format=text is the plain-text version a notification carries.
|
||||
reportsRouter.get("/monthly", asyncHandler(async (req, res) => {
|
||||
const picked = await monthFrom(req.query.month);
|
||||
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months, like 2026-09." });
|
||||
const picked = await monthFrom(req.query.month ?? req.query.period);
|
||||
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months (2026-09), the last eight quarters (2026-Q3) or the last three years (2026)." });
|
||||
const report = await buildMonthlyReport(picked.id);
|
||||
if (req.query.format === "text") return res.json(monthlyReportText(report));
|
||||
res.json({ report, months: picked.months });
|
||||
res.json({ report, months: picked.months, quarters: picked.quarters, years: picked.years });
|
||||
}));
|
||||
|
||||
// Send it now to the notification channels, as if it were the day. Administrators.
|
||||
reportsRouter.post("/monthly/send", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
const picked = await monthFrom((req.body as { month?: unknown } | undefined)?.month);
|
||||
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months, like 2026-09." });
|
||||
if (!picked) return res.status(400).json({ error: "invalid_month", message: "Ask for one of the last twelve months (2026-09), the last eight quarters (2026-Q3) or the last three years (2026)." });
|
||||
const { title, message } = monthlyReportText(await buildMonthlyReport(picked.id));
|
||||
await notifyNow(title, message);
|
||||
await recordAudit({ actor: req.currentUser!, category: "report", action: "send_monthly", targetType: "report", detail: { month: picked.id } });
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
import { Router } from "express";
|
||||
import { eq } from "drizzle-orm";
|
||||
import { z } from "zod";
|
||||
import { db } from "../db/client.js";
|
||||
import { endpointChecks, integrations, servers, serviceLevels } from "../db/schema.js";
|
||||
import { requireAuth, requireRole } from "../auth/middleware.js";
|
||||
import { recordAudit } from "../services/audit.js";
|
||||
import { invalidateAlertsCache } from "../services/alerts.js";
|
||||
import { levelStatuses, listLevels, MAX_LEVELS, MAX_TARGET, MIN_TARGET, SUBJECT_TYPES, type SubjectType } from "../services/serviceLevels.js";
|
||||
import { asyncHandler } from "../utils/asyncHandler.js";
|
||||
|
||||
export const serviceLevelsRouter = Router();
|
||||
serviceLevelsRouter.use(requireAuth);
|
||||
|
||||
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
|
||||
|
||||
const levelSchema = z.object({
|
||||
name: z.string().trim().min(1).max(100),
|
||||
subjectType: z.enum(SUBJECT_TYPES),
|
||||
subjectId: z.number().int().positive(),
|
||||
target: z.number().min(MIN_TARGET, `A target is at least ${MIN_TARGET}%.`).max(MAX_TARGET, `A target is at most ${MAX_TARGET}% — 100% leaves no room for any downtime.`),
|
||||
alert: z.boolean().optional(),
|
||||
});
|
||||
|
||||
async function subjectExists(type: SubjectType, id: number): Promise<boolean> {
|
||||
const table = type === "endpoint" ? endpointChecks : type === "server" ? servers : integrations;
|
||||
return (await db.select({ id: table.id }).from(table).where(eq(table.id, id)).limit(1)).length > 0;
|
||||
}
|
||||
|
||||
const round3 = (n: number) => Math.round(n * 1000) / 1000;
|
||||
|
||||
/** Everything that can have a target, for the form. */
|
||||
async function subjects() {
|
||||
const [e, s, i] = await Promise.all([
|
||||
db.select({ id: endpointChecks.id, name: endpointChecks.name }).from(endpointChecks).orderBy(endpointChecks.name),
|
||||
db.select({ id: servers.id, name: servers.name }).from(servers).orderBy(servers.name),
|
||||
db.select({ id: integrations.id, name: integrations.name }).from(integrations).orderBy(integrations.name),
|
||||
]);
|
||||
return { endpoint: e, server: s, integration: i };
|
||||
}
|
||||
|
||||
// Every target, where this month's error budget stands and how the last months went: for everyone signed in, like the pages the figures come from.
|
||||
serviceLevelsRouter.get("/", asyncHandler(async (_req, res) => {
|
||||
res.json({ levels: await levelStatuses(), subjects: await subjects() });
|
||||
}));
|
||||
|
||||
// Setting targets is an administrator's.
|
||||
serviceLevelsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
const parsed = levelSchema.safeParse(req.body);
|
||||
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "That isn't a target.", details: parsed.error.flatten() });
|
||||
if ((await listLevels()).length >= MAX_LEVELS) return res.status(409).json({ error: "too_many", message: `At most ${MAX_LEVELS} targets.` });
|
||||
if (!(await subjectExists(parsed.data.subjectType, parsed.data.subjectId))) return res.status(400).json({ error: "unknown_subject", message: "That doesn't exist." });
|
||||
const [row] = await db
|
||||
.insert(serviceLevels)
|
||||
.values({ name: parsed.data.name, subjectType: parsed.data.subjectType, subjectId: parsed.data.subjectId, target: round3(parsed.data.target), alert: parsed.data.alert ?? true, createdBy: req.currentUser!.name ?? req.currentUser!.email ?? null })
|
||||
.returning();
|
||||
await recordAudit({ actor: req.currentUser!, category: "service_level", action: "create", targetType: "service_level", targetId: row.id, detail: { name: row.name, subjectType: row.subjectType, target: row.target } });
|
||||
invalidateAlertsCache();
|
||||
res.status(201).json({ id: row.id });
|
||||
}));
|
||||
|
||||
serviceLevelsRouter.put("/:id", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
const id = idOf(req.params.id);
|
||||
const parsed = levelSchema.safeParse(req.body);
|
||||
if (!Number.isInteger(id) || !parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.success ? "That isn't a target." : (parsed.error.issues[0]?.message ?? "That isn't a target.") });
|
||||
const [before] = await db.select().from(serviceLevels).where(eq(serviceLevels.id, id)).limit(1);
|
||||
if (!before) return res.status(404).json({ error: "not_found" });
|
||||
if (!(await subjectExists(parsed.data.subjectType, parsed.data.subjectId))) return res.status(400).json({ error: "unknown_subject", message: "That doesn't exist." });
|
||||
await db.update(serviceLevels).set({ name: parsed.data.name, subjectType: parsed.data.subjectType, subjectId: parsed.data.subjectId, target: round3(parsed.data.target), alert: parsed.data.alert ?? before.alert }).where(eq(serviceLevels.id, id));
|
||||
await recordAudit({ actor: req.currentUser!, category: "service_level", action: "update", targetType: "service_level", targetId: id, detail: { name: parsed.data.name, target: round3(parsed.data.target), ...(before.target !== parsed.data.target ? { targetFrom: before.target } : {}) } });
|
||||
invalidateAlertsCache();
|
||||
res.json({ ok: true });
|
||||
}));
|
||||
|
||||
serviceLevelsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
const id = idOf(req.params.id);
|
||||
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
|
||||
const [before] = await db.select().from(serviceLevels).where(eq(serviceLevels.id, id)).limit(1);
|
||||
if (!before) return res.status(404).json({ error: "not_found" });
|
||||
await db.delete(serviceLevels).where(eq(serviceLevels.id, id));
|
||||
await recordAudit({ actor: req.currentUser!, category: "service_level", action: "delete", targetType: "service_level", targetId: id, detail: { name: before.name } });
|
||||
invalidateAlertsCache();
|
||||
res.status(204).end();
|
||||
}));
|
||||
@@ -168,7 +168,7 @@ const updateSchema = z.object({
|
||||
.partial()
|
||||
.optional(),
|
||||
monthlyReport: z
|
||||
.object({ enabled: z.boolean(), day: z.number().int().min(1).max(28), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
|
||||
.object({ enabled: z.boolean(), quarterly: z.boolean(), annual: z.boolean(), day: z.number().int().min(1).max(28), time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/) })
|
||||
.partial()
|
||||
.optional(),
|
||||
});
|
||||
|
||||
Reference in new issue
Block a user