OtlpDashboard

OpenTelemetry Dashboard

"Grafana was overwhelming, while Aspire was lacking."

This dashboard is the "just right" middle ground: a lightweight, self-hosted OTLP receiver and viewer designed for those who need professional observability without the setup fatigue.

A self-hosted OTLP receiver and viewer for traces, logs, and metrics. .NET 10 + EF Core backend, Vue 3 / Nuxt 4 SPA. Stores telemetry in SQLite, PostgreSQL, or SQL Server. Speaks OTLP gRPC on :4317 and OTLP HTTP/Protobuf on :4318 (the same port also serves the SPA).

Website: adiakys.github.io/OtlpDashboard

Live demo: adiakys.github.io/OtlpDashboard/demo — static build with mock telemetry, no backend required. Login accepts any password (e.g. demo).

The demo runs against an in-browser mock backend (a tiny TS shim

that intercepts every API call and returns generated DTOs) — not the

real .NET host. It exists to let people click around without us

hosting anything; behaviour can drift from the real server in subtle

ways (some flows are stubbed, some validation paths return generated

data instead of real errors). For a faithful preview run the docker

compose stack below.

---

Quick start

Docker — full demo stack

The bundled docker-compose.yml starts the dashboard against Postgres plus a small demo workload (sample-server + sample-client + the OpenTelemetry Collector) that pushes traces, logs, and metrics so the dashboard isn't empty on first boot:

docker compose up --build

OTLP gRPC : localhost:4317

OTLP HTTP : localhost:4318

SPA : http://localhost:4318

Sources for the demo workload live under demo/ — sample app (Server / Client), the built-in widget-library pack (demo/packs/default/, distributed as a separate repo and consumed via git submodule), the demo-stack starter dashboard (demo/packs/default-dashboard/), and the Collector config. To run only the dashboard against an external Postgres / SQL Server, strip the demo services from your override file and point Dashboard__Storage__Provider + ConnectionStrings__* at your DB.

Local dev (no Docker)

# Backend

dotnet run --project src/OpenTelemetryDashboard.Host

Frontend (separate terminal, hot-reload, proxies /api to :4318)

cd web && pnpm install && pnpm dev

The backend runs migrations on every boot, so the SQLite file appears at ./src/OpenTelemetryDashboard.Host/data/telemetry.db on first run.

---

Configuration

All settings live under Dashboard:* in appsettings.json and can be overridden by environment variables using double underscores (e.g. Dashboard__BrowserToken).

Auth tokens

Two static bearer tokens gate the surface:

Auth is opt-in per surface, identically in Development and Production:

• Set a token → that surface requires it.
• Leave a token empty → that surface is public (allow-all). Leaving DASHBOARD__BROWSERTOKEN empty also makes the SPA skip the login screen (/api/v1/info reports requireAuth: false), so the dashboard opens straight away — convenient for a local Docker / Docker Compose run.

Either unset token surfaces as Degraded on /healthz (in any environment) and is logged at startup, so an open deployment is visible rather than silent.

The SPA's /login form exchanges the password for an HttpOnly + SameSite=Strict session cookie via POST /api/v1/auth/login; JS never sees the token after the exchange. POST /api/v1/auth/logout clears the cookie. OTLP clients send the API key as Authorization: Bearer or as the x-otlp-api-key header.

Retention (max days)

Background job that drops rows older than the configured age. Defaults target a "debug + recent forensics" workload — logs hold a month so last-week incidents stay investigable; traces and metrics rotate weekly because high-cardinality spans and split-by metric attributes inflate fast.

"Dashboard": {

"TelemetryLimits": { "MaxLogDays": 30, // default "MaxTraceDays": 7, // default "MaxMetricDays": 7, // default "SweepIntervalMinutes": 60 } }

Or via env vars:

Dashboard__TelemetryLimits__MaxLogDays=30

DashboardTelemetryLimitsMaxTraceDays=7 DashboardTelemetryLimitsMaxMetricDays=7 DashboardTelemetryLimitsSweepIntervalMinutes=60

A value of 0 disables retention for that signal (records are kept indefinitely) — /healthz then reports Degraded so an unbounded window can't hide silently. The sweep runs each SweepIntervalMinutes per signal independently — a failure on one kind doesn't stop the others.

Storage provider

Dashboard__Storage__Provider=Sqlite        # default

ConnectionStrings__Sqlite="Data Source=/app/data/telemetry.db"

DashboardStorageProvider=PostgreSql ConnectionStrings__PostgreSql="Host=...;Database=telemetry;Username=...;Password=..."

DashboardStorageProvider=SqlServer ConnectionStrings__SqlServer="Server=...;Database=telemetry;User Id=...;Password=...;TrustServerCertificate=True"

On PostgreSQL backed by SSD storage, set random_page_cost = 1.1 (the default of 4 assumes spinning disks). Trace list filters look up the spans of a few recent traces by trace_id; with the default cost the planner prefers scanning the whole time window instead, which is several times slower:

ALTER DATABASE telemetry SET random_page_cost = 1.1;

---

MCP server (read-only)

An optional Model Context Protocol server exposes the same data as the read API (logs, traces, metrics) so an LLM client — Claude Code, Claude Desktop, MCP Inspector, etc. — can query the dashboard directly. Disabled by default; set the flag to mount it:

Dashboard__Mcp__Enabled=true

Mounted at /mcp on the same port as the SPA (:4318) over Streamable HTTP, gated by the same browser bearer token (DASHBOARD__BROWSERTOKEN) that protects /api/v1/*. Tools exposed:

Wire it into Claude Code by dropping a .mcp.json at your project root:

{

"mcpServers": { "otel-dashboard": { "type": "http", "url": "http://localhost:4318/mcp", "headers": { "Authorization": "Bearer ${DASHBOARD_BROWSER_TOKEN}" } } } }

Built on the official ModelContextProtocol.AspNetCore SDK (jointly maintained by Anthropic and Microsoft).

---

Widgets

Dashboards are made of widgets dropped onto a 12-column grid. Three sources:

• `std` — built into the bundle (Stat, Line, Sparkline, Gauge, Bar gauge, Pie, Heatmap, Recent traces, Top traces, Logs stream, Text).
• `custom` — preset of a builtin saved by the user, persisted in the DB.
• ` ` — read-only widgets shipped by an installed library (filesystem or installed from a Git repo).

The picker dialog (+ Add widget while editing a dashboard) shows all three groups in the same modal. The search box filters by name, description, *or* source — type std, custom, or a library id to filter a whole bucket.

Custom legend labels

Line, Pie, Bar gauge and Heatmap widgets label their series, slices, bars or rows with the metric's attributes (Line adds the metric name when it shows several), which can get long. To shorten them, open the widget's config drawer and fill the Legend field (one per selected metric on Line). Use {attribute} to insert an attribute value, e.g. Requests {http.request.method} renders as Requests POST. Leave it empty to keep the default label. In pack JSON the same value is the legend field of the metric binding.

Creating a custom widget

1. Open a dashboard, click Edit, add a builtin widget.
2. Configure it (metric binding, thresholds, range, …).
3. In the config drawer click Save as widget, give it a name, icon, and default size.

It now appears in the picker under My widgets, with inline edit and delete buttons that show on hover.

Notes:

• The seed config is captured *at save time* — editing the template later changes only metadata (name, description, icon, default size). The seed config is immutable; clone + delete to change it.
• Existing dashboard instances of a deleted custom widget render a placeholder, not a crash.

Packs (widget libraries + dashboards)

Everything that can ship with the dashboard — widget libraries, built-in dashboards, and any future asset type — is distributed as a pack: a single directory with pack.json at its root. The dashboard scans every entry in Dashboard:Packs:Paths (in order) and surfaces every pack's contents in the picker (libraries) and dashboard list (built-ins).

The shipped image already configures two paths in scan order:

1. /app/data/packs — runtime-managed (volume, git installs, drag-and-drop)
2. /app/builtin-packs — baked into the image layer (no volume shadowing on rebuild)

Derived images don't need to set any environment variable — just COPY into the second path:

FROM opentelemetrydashboard:latest

COPY my-pack/ /app/builtin-packs/my-pack/

When two paths expose packs with the same pack.json#id, the first in scan order wins and the rest are skipped with a warning — so a runtime install can override a baked-in default by sharing its id.

Two sample packs live under demo/packs/:

• default/ (a submodule pointing at Adiakys/OtlpDashboard-default-pack) ships the .NET and PostgreSQL widget libraries.
• default-dashboard/ ships the starter dashboard pre-bound to the demo compose stack.

Both are bind-mounted by docker-compose.yml, so docker compose up --build shows libraries + starter dashboard out of the box.

Install one of two ways:

1. Drop a folder. Copy the pack into the packs path (volume-mount, Ansible, etc.). Click the refresh icon in the widget picker (or POST /api/v1/packs/reload) to re-scan.
2. Install from a Git repo. Click the git-branch icon in the picker header (or POST /api/v1/packs/install with { url, ref, path? }). The server runs a shallow clone via LibGit2Sharp, parses pack.json, resolves HEAD to a commit SHA, and atomically moves the directory into the runtime-managed root. Allowed hosts are Dashboard:Packs:AllowedGitHosts (default github.com, gitlab.com). Use a tag for stable pinning; branches work but get a UI warning. The optional path parameter re-roots the install on a sub-directory, useful for monorepos that ship multiple packs side by side. Updates: the "Update" button on git-installed packs re-pulls the same ref (fetch && reset --hard).

Pack layout

my-pack/

├── pack.json ├── README.md (optional — surfaced in the UI) ├── LICENSE (optional) ├── libraries/ │ ├── core/ │ │ ├── manifest.json │ │ └── widgets/ │ │ ├── sla-tracker/