Embed live SigNoz dashboards anywhere an iframe can go.
Your metrics already live in SigNoz. Your users do not. This project serves every dashboard as a portable, read-only, always-live widget for portals, product pages, NOC walls and reports.
✔ listening on :8080✔ allowlist loaded: dashboards GET + query_range v3/v4/v5✔ writes and everything else -> 403<iframe
src="https://embed.example.com/embed/<dashboardId>?relativeTime=30m&theme=shadcn&mode=light"
style="width:100%;border:0"
allowfullscreen>
</iframe>0
iframe line to embed
0
themes: shadcn + legacy
0
write APIs proxied
0%
read-only surface
A real dashboard served by the embed app: live charts, URL-driven controls, no console login.
What you get
Everything a shared dashboard needs, nothing that can break it
The embed app, the proxy and the URL spec are built as one read-only product. Views are links, data is always fresh, and the write surface simply does not exist.
One-line embed
GET /embed/:dashboardId renders the toolbar plus the dashboard grid. Callers only build a URL, no SDK and no build step.
Always live, never stale
Every load and refresh streams straight from your SigNoz backend. No exports, no screenshots, no scheduled sync jobs.
Read-only by design
No edit, clone, delete, settings, lock or alert UI. Dashboard writes and every non-allowlisted API return 403.
Key flexibility
Effective key = x-embed-api-key ?? env.SIGNOZ_API_KEY. A missing or wrong key renders a friendly empty state, never a stack trace.
Two themes, one contract
shadcn (Tailwind + Recharts) and legacy (antd + ECharts) implement the same ThemeModule contract. Unknown values fall back to shadcn.
Observable by default
GET /healthz and GET /metrics, plus JSON logs that record only the key source and an 8-char hash, never the plaintext key.
Use cases
One embed origin, many audiences
The same deployment serves customer portals, internal tools and big screens. Only the URL changes.
Customer-facing status & SLA pages
Show live health, latency and usage on your support portal without giving customers console access.
In-product analytics
Put real operational charts inside an admin panel, settings page or partner portal.
Ops & NOC walls
Kiosk-ready chrome toggles (title, toolbar, fullscreen) turn any dashboard into a big-screen view.
Reports & reviews
Time range, variables and refresh interval all live in the URL, so every shared link reproduces the exact same view.
Architecture
Static HTML in, streamed queries out
One container serves the embed app and proxies the SigNoz API. The browser never talks to SigNoz directly and never holds a backend address.
Your site
Portal, product, NOC wall
Embed app
/embed/:dashboardId
NestJS proxy
/api/signoz/* :8080
SigNoz
Query service 0.97.0
ALL /api/signoz/* -> SIGNOZ_BASE_URL + path + query
GET /api/v1/dashboards/:id pass through
POST /api/v3|v4|v5/query_range pass through
POST /api/v5/substitute_vars pass through
POST /api/v2/variables/query pass through
GET /api/v1/fields/values pass through
GET /api/v1/version|features pass through
* everything else 403Missing key, invalid key, unknown dashboard, upstream outage and blocked writes map to typed EMBED_* error codes, each rendered as an empty state with Retry where it makes sense.
Design principles
Read-only is not a feature, it is the architecture
Four rules keep the project safe to put in front of strangers and cheap to extend.
Docs-first
docs/product-tech-design.md is the single source of truth: design changes update the document before the code.
Default deny
The proxy is an allowlist of read-only routes. Everything else under /api/* returns 403 and is never forwarded.
Keys in memory only
The URL key stays in memory, never localStorage or cookies. Logs keep the key source and an 8-char hash only.
Theme plugins
A new theme adds themes/<name>/ plus one registry line. core/ stays untouched, so the contract cannot sprawl.
FAQ
Questions owners ask before embedding
Do viewers need a SigNoz account?
No. The iframe renders the dashboard without a login page. Data access is authorized by an API key injected server-side by the proxy.
Can someone edit or delete my dashboard through the embed?
No. Dashboard PUT/POST/DELETE, /lock, and rules/alerts/user/org endpoints are blocked with 403. The frontend implements no editing entries.
Can one dashboard serve different customers, regions or tiers?
Yes. var-<name> query params override dashboard variable defaults, so a single dashboard can be re-scoped per link.
Is putting an API key in the URL safe?
Treat it as sensitive: URLs end up in browser history, proxy logs and referers. Use short-lived, read-only keys and rotate on leak. Prefer the env default key when the embed origin is trusted.
Which SigNoz versions are supported?
SigNoz v0.97.0 query semantics are pinned. The proxy passes through the v3/v4/v5 query_range APIs and the variables APIs without validating unknown fields.
Can I ship my own theme?
Yes. Implement the ThemeModule contract (Tokens, Toolbar, WidgetCard, ErrorState), register it with one line, and select it with ?theme=<name>.
Ship a live dashboard this afternoon
Point the container at your SigNoz backend, copy the iframe line, and your customers get charts instead of screenshots.