Monitoring & Health

Job-Easy has a deeply integrated monitoring slice that acts as the platform's operations console. It monitors platform health, PostgreSQL, object storage, integrations, queues, and security.

The Honesty Rule

A monitoring panel that reports 0 errors because it lacks the credentials to connect is worse than having no panel at all—it converts an unknown into a false reassurance.

To prevent this, every monitoring endpoint returns a strict PanelEnvelope<T>:

• ok: The system is healthy, the metric is real.
• not_configured: A named credential is missing. This is considered a skipped state, NOT an outage, avoiding a permanently red dashboard for optional integrations.
• unavailable: The upstream service actually failed.
• unsupported: The capability doesn't exist on this deployment.

Secret Redaction

Because failed probes can easily leak sensitive data (e.g. a Prisma error echoing the entire DATABASE_URL), the system relies on a double-redaction process via utils/redact.ts—once before serialization, and once in the JSON viewer.

The Infrastructure view only shows variable names, a boolean presence check, and lengths. Accessors are strongly typed so the raw value can never be leaked to the client, even by accident.

Job History (JobRun)

Every scheduled cron execution is recorded in the JobRun table. The system intentionally performs two writes per run:

1. It writes running at the exact start of the job.
2. It writes the final status (success or failed) at the end.

Because serverless functions can be unceremoniously killed when hitting Vercel's execution ceiling, a killed function can't report its own failure. By writing running upfront, a background reaper (/api/cron/purge-stale) can later find these orphaned rows and correctly close them as timeout.

Manual Cron Invocation

When an admin triggers a job manually, the system makes an HTTP call to its own cron route rather than directly importing the handler. This ensures the manual run takes the exact same middleware and instrumentation path as the automated scheduler, producing an identical JobRun row. There is no SSRF surface because the path is strictly resolved against the internal CRON_JOBS registry.

The One Stream

Polling on Vercel is generally safer than Server-Sent Events (SSE). An open EventSource holds a serverless invocation open for its entire lifetime, billing continuously. Therefore, the SSE branch in useLiveData is switched off globally, and all panels poll driven by a single MonitorRefreshProvider clock.

There is only one exception: GET /api/admin/monitor/jobs/[job]/stream. Because it only opens when an admin manually clicks "Run" and closes the exact moment the run finishes, it is strictly bounded and safe to use.

Incident Tracking (IncidentEvent)

The /api/cron/health worker is the only writer to the HealthCheckResult and IncidentEvent tables.

To prevent alert spam, the system enforces at most one open incident per condition. It leverages a partial unique index in Postgres:

CREATE UNIQUE INDEX ON "IncidentEvent"(key) WHERE "resolvedAt" IS NULL;

Because Postgres treats NULL as distinct from NULL, a standard @@unique constraint wouldn't work. The partial index guarantees the database rejects duplicates at the engine level, so an alert condition that fires for 3 hours only sends one initial email, rather than flooding admin inboxes every minute.