feat(admin): add observability dashboard UI with Grafana embeds

[Ferryx349]

Description

Summary

• Add admin observability dashboard at /admin with live health, throughput, events, and resource cards
• Stream metrics via existing /admin/metrics SSE endpoint with stale-data and fault indicators
• Embed Grafana solo panels (events/sec, websocket connections, CPU, memory) with provisioned nostream-overview dashboard
• Add logout route, session cookie handling, and CSP/frame-src support for Grafana
• Harden admin health/metrics timeouts and fail-open rate limiting when Redis is unavailable
• Keep admin console opt-in (admin.enabled: false by default)

Related Issue

Fixes :- #663

How Has This Been Tested?

• Set admin.enabled: true & ADMIN_PASSWORD in settings/env, sign in at /admin
• Verify health cards update live (SYS/PROM/DB/RDS)
• Stop Redis -> Redis shows [FAULT], dashboard stays reachable
• Start docker compose up -d otel-collector prometheus grafana -> Grafana panels load
• Run pnpm test:unit for admin routes, grafana utils, event handler, and metrics specs

Video

https://www.youtube.com/watch?v=cRzJ61NDu0o

Note - I have recorded this video before final UI structure, so screens in attached SS and video might differ but functionalities are same.

Screenshots (if appropriate):

Auth

Metrices Dashboard

Graphs

Hamburger (Light Mode)

Grafana dashboard

Types of changes

• Non-functional change (docs, style, minor refactor)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my code changes.
• I added a changeset, or this is docs-only and I added an empty changeset.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: d9e8af7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
nostream	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coveralls]

coverage: 67.884% (+0.1%) from 67.789% — Ferryx349:UI-DASH into cameri:main

[Copilot]

Pull request overview

Adds an opt-in admin observability console at /admin that streams live health/throughput/resource metrics via SSE and embeds Grafana panels for richer charts, including local docker-compose provisioning for Prometheus+Grafana.

Changes:

• Introduces /admin dashboard shell + static assets, plus /admin/metrics SSE streaming and Prometheus query utilities.
• Adds Grafana URL helpers and docker-compose provisioning for a nostream-overview dashboard and Prometheus datasource.
• Hardens admin dependency/metrics timeouts and makes Redis-backed rate limiting fail-open on backend outages.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/unit/utils/prometheus-client.spec.ts	Unit tests for Prometheus URL normalization, scalar parsing, and instant query behavior.
test/unit/utils/admin-metrics.spec.ts	Unit tests for admin metrics snapshot composition, degraded/unavailable states, and caching.
test/unit/utils/admin-grafana.spec.ts	Unit tests for Grafana URL helpers and env var normalization.
test/unit/routes/admin.spec.ts	Route-level tests for admin enablement, dashboard shell, auth gating, and SSE content-type.
test/unit/handlers/event-message-handler.spec.ts	Test coverage for fail-open behavior when rate limiter backend fails.
src/utils/prometheus-client.ts	Prometheus instant-query client with parsing + timeout and warning logs.
src/utils/admin-session.ts	Adds helper for clearing the admin session cookie on logout.
src/utils/admin-metrics.ts	Collects and caches admin metrics snapshots from Prometheus + dependency health.
src/utils/admin-health.ts	Parallel dependency pings with configurable timeouts.
src/utils/admin-grafana.ts	Grafana base/dashboard/embed URL utilities and origin extraction for CSP.
src/routes/admin/index.ts	Admin router wiring: static assets, dashboard routes, logout, health, metrics SSE.
src/handlers/request-handlers/get-admin-dashboard-request-handler.ts	Serves the admin dashboard HTML template with injected settings/URLs.
src/handlers/event-message-handler.ts	Rate limiter failures are treated as fail-open (do not reject events on Redis outages).
src/factories/web-app-factory.ts	CSP updates (incl. frame-src) and protocol fix for derived web relay URL.
src/factories/controllers/post-admin-logout-controller-factory.ts	Factory for admin logout controller.
src/factories/controllers/get-admin-metrics-controller-factory.ts	Factory for admin metrics SSE controller.
src/controllers/admin/post-logout-controller.ts	Logout controller delegating to auth provider.
src/controllers/admin/get-metrics-controller.ts	SSE controller that streams metrics snapshots at a configured interval.
src/app/app.ts	Safer centering logic when terminal width is smaller than text length.
src/admin/password-admin-auth-provider.ts	Implements logout by clearing the session cookie and returning { authenticated: false }.
src/@types/admin.ts	Extends admin auth provider interface with handleLogout.
resources/admin/dashboard.html	New admin dashboard HTML shell with login + KPI cards + Grafana iframes.
resources/admin/assets/dashboard.js	Frontend logic for login/session, SSE streaming, staleness detection, theme toggle, and embeds.
resources/admin/assets/dashboard.css	Styling for the admin console UI in light/dark themes.
grafana/provisioning/datasources/prometheus.yaml	Provisioned Prometheus datasource for Grafana.
grafana/provisioning/dashboards/default.yaml	Provisioned dashboard provider configuration.
grafana/dashboards/nostream-overview.json	Provisioned Grafana dashboard definition used by the admin embeds.
docs/REDIS.md	Documents fail-open rate limiting behavior during Redis outages.
docker-compose.yml	Adds Grafana service + env vars for Prometheus/admin metrics configuration.
CONFIGURATION.md	Documents new observability/admin-related environment variables.
.env.example	Adds example env vars for Prometheus/Grafana/admin console setup.
.changeset/admin-metrics-sse-endpoint.md	Changeset for admin metrics SSE endpoint feature.
.changeset/admin-dashboard-ui.md	Changeset for admin dashboard UI + Grafana embed feature.

Comments suppressed due to low confidence (1)

src/factories/web-app-factory.ts:35

• Admin dashboard loads IBM Plex Mono from https://fonts.googleapis.com / https://fonts.gstatic.com (resources/admin/dashboard.html), but the global CSP currently only allows styles/fonts from self and jsdelivr. This will block the Google Fonts stylesheet and font files in the browser.

Allow these origins in the relevant CSP directives (or alternatively vend the font locally).

 const directives = {
'img-src': ["'self'", 'data:', 'https://cdn.zebedee.io/an/nostr/'],
'connect-src': ["'self'", settings.info.relay_url as string, webRelayUrl.toString()],
'default-src': ["'self'"],
'frame-src': ["'self'", getGrafanaFrameOrigin()],
'script-src-attr': [`'nonce-${nonce}'`],
'script-src': [
"'self'",
`'nonce-${nonce}'`,
'https://cdn.jsdelivr.net/npm/',
'https://unpkg.com/',
'https://cdnjs.cloudflare.com/ajax/libs/',
],
'style-src': ["'self'", 'https://cdn.jsdelivr.net/npm/'],
'font-src': ["'self'", 'https://cdn.jsdelivr.net/npm/'],

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Justxd22]

Hello, im wondering why Grafana? and not raw tailwind components? i've the code for the original screens at #594 i was waiting for ground work, Good job on the other PRs!

[Ferryx349]

@Justxd22 Sure, we can replace the screen with tailwind components. Actually styling was handled with Bootstrap and custom CSS by me, and Grafana was added specifically for the charting layer.

[Ferryx349]

Will it work for you to push tailwind code in seperate PR, then we can make changes accordingly in this PR..
@cameri wdyt?

[cameri]

@Ferryx349@Justxd22 let's do the Tailwind components in a separate PR as it was not an original requirement of this work.

[Ferryx349]

Fixed Conflicts