Observability

Runtime telemetry surface — service health, system logs, error reports, feedback, and audit trail. Instance admins only.

The Observability surface lives at /observability in the QuoxCORE dashboard. It is a peer top-level area to Settings, dedicated to runtime telemetry: logs, errors, service health, user feedback, and the audit trail.

It is gated to instance administrators. Members and org admins who do not also hold an instance-admin role do not see the Observability entry in the sidebar, and direct URL access is blocked by a route guard.

Why a separate surface

Configuring a system and watching it run are different jobs. Mature products consistently split them — Stripe Workbench, Vercel Observability, Supabase Logs Explorer, GitLab Admin → Monitoring. QuoxCORE follows the same pattern: Settings is for changing behaviour, Observability is for inspecting what happened.

Before the SET-IA settings refactor, these surfaces lived under /admin/* mixed with instance configuration. They were extracted to /observability so each surface has a single concern.

Tabs

Access control

The role-gating is enforced at three levels:

1. Sidebar visibility — navRegistry only renders the Observability entry when the user has the appropriate role.
2. Route guard — <ProtectedRoute minRole="admin"> wraps the layout in App.jsx.
3. Backend — every endpoint behind /api/admin/* (which Observability reads) goes through requireInstanceAdmin('readonly') middleware.

A non-admin attempting /observability/logs directly hits an "Access Denied" panel rendered by the layout's auth check, never any data.

Common triage flows

"A user reports the chat is broken"

1. Open Service Health — confirm collector, auth, and qdrant are green
2. Open System Logs — filter service=collector level=error, look for stack traces around the user's report time
3. Open Error Reports — scan for unhandled errors with the user's org_id or recent timestamp
4. If the issue traces to credentials, open Settings → Provider Keys to verify the resolved key is healthy

"Audit needs evidence of a config change"

1. Open the org dashboard at /orgs/<org-id> → Activity tab — every settings change is hash-chained through VOLT and surfaces here
2. The instance-level audit (admin grants, encryption rotations, instance config patches) is recorded server-side via logAdminAccess() — surfaced in a future unified Audit Trail tab on this page
3. For compliance bundles, use /evidence (Evidence Explorer) which builds a per-control PDF

"Feedback queue is unread"

1. Open User Feedback — sorted by created_at desc, unread items have a badge
2. Click an item to read the full body, change status, leave an internal note
3. Resolved items remain queryable indefinitely (subject to the retention.system_logs_days config in Settings → Instance → Retention Defaults)

Where things were before

If you used QuoxCORE before the SET-IA refactor, the URLs you remember have all been preserved as redirects:

Bookmarks survive forever — the redirects ship with the dashboard.