Dashboards¶

The numbers that matter live in two places in the sidebar: open tickets, errors this week, average latency, pending approvals.

Goals (/smallstack/goals/) is the numbers themselves: the metrics that define them, goal lists that judge them against targets, and reports that compare them across periods.
Dashboards (/smallstack/dashboards/) is how they're shown: dashboards of cards, the saved components (card designs) they're built from, and playlists that rotate them.

	What it is
Metric	One named number: counted from a dataset ("requests that answered 5xx"), entered by hand, or one metric divided by another. See Building metrics. The reusable unit: one metric can sit on many dashboards, reports and goal lists.
Goal list	Metrics against their targets, in sections: on target, at risk or missed. See Goals.
Report	A table of metrics across periods — this month vs last month vs the year so far — that can be downloaded as CSV.
Dashboard	A grid of cards: a metric as a number, a dataset filtered for the card and split or charted, a widget, a goal list, a note.
Component	A saved card: a dataset filtered for it (any design), or a saved metric for a single number, which lends the card its format, unit and colour rules until the card overrides them.

Getting a team started¶

For a weekly operations meeting, from nothing:

Metrics. Under Goals → Metrics → New metric, build the numbers you read each week, and choose Shared under Who can see it. Counted from a dataset, set Date to count by, so it can be narrowed to a week. A number from outside can be entered by hand, and a percentage is a rate: see Building metrics.
A goal list. Goals → Goal lists → New goal list: choose Shared and judge it over Previous week, then add sections and targets. See Goals.
A dashboard, also shared, opening on the previous week, with those metrics, grouped cards and a Calendar card for what's coming.
A playlist under Dashboards → Playlists: the dashboard, then the goal list as Goals now, Last week and Week over week.

Put the meeting itself on the calendar as a repeating event, and use Print on the goal list for a paper copy. Last week's hand-entered numbers can be typed on Monday morning: the saved week picks them up.

While a list tracks weeks (new ones do), the week just ended is saved early each Monday; see Saving weeks in Goals. An agent can do all of this: see Agents and the API.

The ladder: dataset → metric → card¶

A dataset is a named, filterable table the project has declared (requests, tickets, health checks…). SmallStack bundles its own (requests, heartbeats, job runs…); your own data becomes one with a few lines of code, which a developer can add from docs/skills/datasets.md (@dataset). A metric stores which rows (a filter) and how to roll them up (count, sum, average…). A card shows the metric's current value, coloured by its thresholds; click it to see the rows behind the number. Because the card re-runs the stored filter every time, it is always current.

Reading a dashboard¶

Period (top left) narrows every period-aware card to "This week", "Last week", "7 days", "This month" and so on (see Periods, below). A card whose metric has no date column ignores it, and so does a card pinned to all time.
Click a number to open the rows behind it. On a grouped card, each group opens its own rows.
A card that says restricted draws on data your account can't read. The dashboard is shared with you; that card's data isn't.
A dashboard with Refreshes every N s re-fetches its cards on its own; Refresh, in the page's header, reloads them now.
Linked cards. Some dashboards connect their cards: clicking a slice, bar or calendar day in one card narrows another to it instead of opening rows. The narrowed card says so, e.g. Showing POST ✕; the ✕ puts it back.
On Today or This week / month / quarter / year, each card shows its change from the period before, e.g. ▼ 35% vs all of last month. "All of" means this period is still running and is being compared with a finished one. The change is grey on purpose: whether up is good depends on the metric.

Periods¶

On the page	In forms and the API	Means
Today / Yesterday	`today`, `yesterday`	that calendar day
This week	Week to date, `wtd`	Monday up to now, so it's still running
Last week	Previous week, `pwtd`	the last full week, Monday to Sunday
This month, This quarter, This year	`mtd`, `qtd`, `ytd`	from the 1st up to now
Last month, Last quarter, Last year	`pmtd`, `pqtr`, `prev_year`	the last full one
This month, whole / This year, whole	`this_month`, `this_year`	the whole calendar month or year, including days still to come
7 days, 30 days, 90 days	`last_7`, `last_30`, `last_90`	rolling, from that many days ago through today
Next 7 days, Next 30 days	`next_7`, `next_30`	rolling, from today on

Periods still running are compared with all of the period before, so early in a week a number that only goes up looks low. For a meeting, read Last week, which compares with the week before.

Point at a card and a ⋯ appears at its corner (on a touch screen it's always there). What it offers depends on the card and on you:

Edit card opens the card's builder in a window over the dashboard: its design, metric, options, style and drill-down, with a live preview. Save and you're back on the dashboard. A card that belongs to this dashboard only changes here. A saved card (one from Components) changes on every dashboard that shows it, and the window says so. You see Edit on a saved card only if you may edit that card.
Make a unique copy is on a saved card that other dashboards show too. The card stays where it is, looking as it did, but stops following the saved card: it becomes this dashboard's own. Tick Copy its metric too (it's ticked to start with) and the card gets its own copy of the metric as well, named after the dashboard, so you can change its filter here without changing the number anywhere else. The saved card and the other dashboards are left as they were.
Give it its own metric is on a card that already belongs to this dashboard: it copies the metric the same way, without changing the card.
Move or resize starts arranging the cards (the same as Edit layout).
Open the metric goes to the page of the number the card draws. Edit the metric goes straight to its filter, when it's yours to change.
Refresh this card reloads just that one.
Remove from dashboard asks first, then takes the card off. Its metric stays, and so does a saved card under Components.

Someone who can open a dashboard but not edit it sees only Open the metric and Refresh.

A card other dashboards show too is marked, for anyone who can edit the dashboard: a small tab on its bottom edge with a link and the number of dashboards showing it. Editing that card changes all of them.

A new dashboard from an old one. Open the old one and choose Duplicate, then on the copy: remove the cards you don't want, choose Make a unique copy (or Give it its own metric) on each one that should show different numbers, and use Edit the metric to change each filter. The original dashboard and its numbers don't change. A number entered by hand isn't copied, because its values are typed against that one metric.

Editing a layout¶

On a dashboard you can edit, click Edit layout:

Drag cards to move them; drag a corner to resize. The grid is 12 columns wide.
Add card → pick a type:
Saved card — one you've built under Components (when you have any).
Single stat — one number, from a saved metric.
Gauge — one number on a half dial, coloured by its rules.
A grouped stat or a chart (requests by method, latency over time) filters a dataset of its own, so it's built under Components and placed as a saved card, or added here and opened with Edit card.
Goals — a goal list's summary and first goals.
Calendar — upcoming entries, a month or a day-range board.
Info card — any card from the main /smallstack/ dashboard (staff).
Note — a heading or a note, in markdown, with its own text colour, size and alignment.
Menu — a row or column of links, to other dashboards or anywhere.
Remove takes a card off (the metric itself stays).
Save layout. Cancel throws the changes away.

Settings edits the name, picture, tags, the default period and auto-refresh. It also lists every card with its design, metric, size and current value. Sorting that table only changes the table; a card's place on the dashboard doesn't move.

Reports¶

A report row can have a target (and an at-risk line), like a goal. Its values are then coloured on target, at risk or missed, a Target column appears, and the CSV adds each value's status. In the report editor, set a row's target under its name, or choose Use the colour rules to start from the metric's.

In the report editor, clicking a column heading (Metric, Target or At risk) sorts the rows and changes the order the report reads in. Undo puts them back, and nothing changes until you save. Columns can be dragged wider or narrower.

A report's numbers open their rows too. The first column shows its change from the second, and the reports list shows each report's movement in one line ("▲ 2 up, ▼ 5 down"). When you edit a report, the preview shows its real values as you build it. The first period you tick is the first column.

Print on a report opens a document of it, then your browser's print dialog. A report with more than three period columns prints sideways.

Finding things¶

The two overviews, Dashboards and Goals, each show a short sample of what's there, most recently changed first, and each section sorts on its own:

On the Dashboards overview	Shown	The rest
Dashboards	8 as cards, or 20 as a list	All N dashboards
Playlists	6	All N playlists
Saved cards	6	All N cards

An overview never pages. Past those numbers, the link beside each section opens its full list, which shows 15 to a page with a Rows per page choice (15, 25, 50 or 100). The pager appears once there are more than 15. My dashboards pages the same way.

Tags are how you group things. Add them to anything in its settings (ops, weekly review), and every overview and list shows a Tags bar across the top with each tag in use and how many things carry it. Choose one to narrow the page to it; Show everything clears it. Before anything is tagged, the bar says how to add the first one. The tag follows you from an overview into a full list. A row's own tags are chips too. A tag matches whole: ops doesn't find devops. The search box on a list also looks in tags, and there it matches part of a word.

Hover over a metric or goal name in a list to see its description, if it has one.

Archived things are out of the lists and pickers but not gone (see Archiving, below). A list with some shows Show archived (N) beside its tags; the overviews say what's archived, e.g. Archived: 2 metrics, 1 report, each a link.

Addresses¶

Every dashboard, report, playlist and goal list has an address, such as /smallstack/dashboards/d/site-health/. You don't type it. It's made from the name when you create the thing: Site health becomes site-health, and a second one with the same name becomes site-health-2.

Renaming doesn't change the address, so bookmarks, links, pages that embed a dashboard and wall screens pointed at a playlist keep working. A thing's settings page shows its address.

An administrator (a superuser, or a member of the admin group) can change an address on purpose, under Change the address in its settings. Playlists and Goals cards that show it follow the change; links and bookmarks to the old address stop working. Metrics and saved cards have a permanent key instead, also made from the name.

Archiving, deleting and duplicating¶

Each of these asks first and says what it will do.

Archive puts something away without breaking anything. It leaves the lists and pickers, but every dashboard, report and goal using it keeps showing it. To bring it back, choose Show archived on its list, open it and press Restore. When in doubt, archive.
Delete can't be undone, so the confirmation says what goes and what stays:
A metric: the dashboard cards, report rows, goals and saved cards that use it. They're removed in the same step unless you untick the box. (Deletes by an agent or the API always remove them.)
A saved card: each dashboard showing it keeps it as a card of its own.
A goal list: its goals and its saved week-by-week history.
A report, dashboard or playlist: only itself; the metrics and dashboards it uses stay. A report offers a last CSV, a dashboard a copy of its layout.
Duplicate opens the form for a copy, named "… (copy)", filled in from the original. The copy starts personal and nothing is saved until you press Save.

On your own pages¶

Any page in your project can show what these pages show:

{% load dashboard_tags %}
{% dashboard "site-health" %}
{% metric_card "open_tickets" period="mtd" %}
{% goal_list "weekly-ops" %}
{% card "requests_by_method" %}
{% report "monthly-kpis" %}

Or take the numbers and draw them your own way: {% metric_value "open_tickets" as m %} gives the value, its colour state and its change; {% goal_values "weekly-ops" as g %} the verdicts.

The cards, numbers and drill-downs are the same ones these pages show. People who can't open something see nothing. The Dashboard starter page has a working example of each.

Every metric, dashboard and report is either personal (yours; only you can edit it) or shared (every signed-in user can open it; staff edit it). Only staff can share. Staff can open anyone's personal items to help, but only the owner edits them.

A shared dashboard can hold only shared metrics, and a personal one can hold shared metrics and your own. It can't use someone else's personal metric.

Sharing a personal dashboard. Its owner can let others open it without giving it away: Share in its header turns on everyone or adds people by name (each gets a notification). They can view it; only the owner edits it. The badge says who it's shared with.

Sharing a dashboard doesn't share its data. Every dataset has its own access level, and all the ones SmallStack bundles are staff-only, except that a hand-entered metric shows to anyone who can see the metric. So someone without staff access who opens a shared dashboard or goal list built on them sees restricted on each card, and "No numbers yet" on the goals. To give a whole team the numbers, make them staff, or have a developer declare a dataset of your own with access="auth", which opens it to everyone signed in.

A demo¶

uv run python manage.py seed_dashboards creates a Site health dashboard and a Monthly KPIs report from the built-in datasets (requests, health checks, approvals), plus a Server error rate metric: one metric divided by another. It shows the metric, grouped and note cards.

Dashboards