# dsc analytics — specification
A new top-level command that pulls a small, deliberately chosen set of metrics from a Discourse to help an admin or community manager assess **community health**, **growth**, and **activity** at a glance.
This document is normative for the design and output of the command. User-facing documentation will live at `docs/analytics.md` once the command is implemented.
## Motivation
The Discourse admin dashboard exposes many charts, but several of the most prominent ones are weak or misleading signals on their own:
- **Page views** and **consolidated page views** are inflated by crawlers and logged-out skim traffic. They don't tell you whether the community is alive.
- **Signups** count anyone who created an account, including spam regs that never post a single word. They overstate growth.
- **Topic views** and **profile views** behave the same way and reward "viral" but low-engagement content.
- **DAU** in isolation moves with seasonality and notification emails; it's only useful as a ratio (DAU/MAU) and across consecutive periods.
- **"Time to first response"** is reported without context (median vs mean, including or excluding solved topics, etc.) and reads as a vanity number.
`dsc analytics` deliberately omits these as headline numbers. The metrics it does report are chosen so that each one, on its own, tells you something actionable about the community.
## Goals
1. One command, one screen of output, every number interpretable without a footnote.
2. Every metric has a clear "good direction" (up / down / stable) and a baseline you can compare against.
3. Every metric is reproducible from Discourse's public/admin APIs without any third-party analytics provider.
4. Machine-readable output for piping into dashboards, journals, and cron-driven trend tracking.
## Non-goals
- Not a replacement for full BI / data warehouse analytics.
- Not a real-time monitoring tool. Granularity is daily at best, weekly is typical.
- No traffic / referrer / SEO metrics — those belong elsewhere.
- No per-user drill-down. `dsc user info` and `dsc user activity` cover that.
## Command shape
```text
dsc analytics <discourse> [--since <when>] [--compare] [--section health|growth|activity|all]
[--format text|json|yaml|markdown|markdown-table|csv]
```
Aliases: `dsc stats` is accepted as an alias for discoverability but `analytics` is canonical.
### Flags
- `--since <when>` (or `-s`) — the window to report on. Accepts the same relative durations as `dsc user activity` (`24h`, `7d`, `30d`, `1w`, `1m`, `90s`) or an ISO-8601 date/timestamp. Defaults to `30d`.
- `--compare` (or `-c`) — also fetch the immediately preceding window of equal length and show a delta column. For example with `--since 30d --compare`, the prior 30 days are pulled and reported alongside.
- `--section` — restrict output to one section. Defaults to `all`.
- `--format` (or `-f`) — see "Format baseline" in `spec/spec.md`. Default is `text`. `markdown` and `markdown-table` are intended for piping into a `dsc topic reply` so that admins can keep a rolling community-health thread on their own forum (mirrors the `dsc user activity` archive workflow).
### Auth
- Requires admin scope. Most reports are admin-only on Discourse.
- If the configured key is not admin, the command should fail fast with the standard `missing api key for {discourse}; please set apikey or check your config` message rather than silently dropping sections.
### Honours `--dry-run`?
No. Read-only command.
## Sections and metrics
Output is grouped into three sections. Each metric prints on its own line: a short label, the value for the window, and (with `--compare`) the prior-window value and an arrow.
### Growth
The question this section answers: **is the community gaining or losing engaged people?**
| New contributors | Users whose **first ever post** was in the window. | Replaces "signups". Counts only people who actually started participating. |
| Reactivated users | Users who posted in the window after **≥ 90 days** of silence. | Surfaces win-back without conflating with new growth. |
| Lost regulars | Users who posted ≥ 4 times in the prior 90 days but **zero times** in the window. Reported only when `--since` is ≥ 30d. | The honest counterpart to "new contributors" — most dashboards never show churn at all. |
| Net active change | New contributors + reactivated − lost regulars. | A single net-flow number that captures whether the active base grew. |
| Trust-level promotions | Count of TL0→TL1, TL1→TL2, TL2→TL3 promotions in the window. | "People crossing the engagement threshold" beats "total users at TL1+". |
### Activity
The question this section answers: **is the place busy and broad, or quiet and lopsided?**
| Topics created | New topics in the window (excluding PMs and topics in archetype `private_message`). | Straightforward. |
| Posts created | New posts (replies + topic OPs). | Straightforward. |
| Posts per topic | Posts created ÷ topics created. | Conversation depth. A spike in topics with a flat ratio means activity isn't producing discussion. |
| Unique posters | Distinct users who created at least one post in the window. | Breadth. Pairs with the next metric to detect lopsidedness. |
| Top-10 share | % of all posts in the window written by the 10 most active posters. | A concentration warning. Healthy public communities sit roughly in the 30–55% band; sustained > 70% is a fragility signal. |
| Reply coverage | % of topics created in the window that received **at least one reply from a different user** within 7 days. | The inverse of "no-reply rate". Replaces the ambiguous "time to first response" headline. |
| Median time to first reply | Median minutes from topic creation to first reply, computed only over topics that received a reply. | Same denominator caveat is now visible because it sits next to "reply coverage". |
### Health
The question this section answers: **are the people here treating the place, and each other, well?**
| Likes per post | Likes given in the window ÷ posts created in the window. | Cheap proxy for peer recognition. Tracks well across periods even though the absolute number is noisy. |
| Returning poster rate | % of posters in the window who also posted in the **previous** window of equal length. | Real retention. More honest than DAU/MAU on its own. |
| Flags raised | User-raised flags in the window (excluding system / auto flags). | Conflict signal. Spikes warrant attention even when other metrics look fine. |
| Flag resolution time | Median hours from flag creation to staff disposition. | Moderation responsiveness. Pairs with "flags raised" to distinguish "calm" from "neglected". |
| Moderator action rate | Moderator actions per 1,000 posts in the window (silences, suspends, post deletions, topic closes, recategorisations). | Normalises moderator load against site activity. A jump per 1,000 posts is informative; raw counts aren't.|
| Solo-thread rate | % of topics in the window where only the OP posted (no replies from anyone else, ever). | Loneliness signal. Rising solo-thread rate is one of the earliest indicators of community decay. |
## Output
### Text (default)
Single screen. Section headers, fixed-width metric labels, right-aligned numbers, optional delta column with arrows under `--compare`.
```text
analytics for myforum — last 30 days (2026-03-27 → 2026-04-26)
growth
new contributors 42 ↑ 31 (+35%)
reactivated users 11 ↑ 8 (+38%)
lost regulars 7 ↑ 5 (+40%)
net active change +46 ↑ 34
trust-level promotions 19 ↑ 12 (+58%)
activity
topics created 128 ↑ 117 (+9%)
posts created 964 ↑ 902 (+7%)
posts per topic 7.5 ↓ 7.7
unique posters 188 ↑ 174 (+8%)
top-10 share 41% ↓ 47%
reply coverage 83% ↑ 79%
median time to first reply 38m ↓ 51m
health
likes per post 1.9 ↓ 2.1
returning poster rate 61% ↑ 58%
flags raised 14 ↑ 9
flag resolution time 4.2h ↑ 6.1h
moderator action rate 6.3 / 1k posts ↓ 7.0
solo-thread rate 12% ↓ 15%
```
The arrow direction is colour-coded by **whether the change is desirable**, not just by sign:
- "lost regulars going up" is bad → red.
- "solo-thread rate going down" is good → green.
- "median time to first reply going down" is good → green.
A single column of arrows that always meant "up" would be misleading. Each metric carries an internal `desirable_direction` so the renderer can colour it correctly.
### JSON / YAML
Stable schema, suitable for trend tracking via cron:
```jsonc
{
"discourse": "myforum",
"window": { "since": "2026-03-27T00:00:00Z", "until": "2026-04-26T00:00:00Z", "label": "30d" },
"compare": { "since": "2026-02-25T00:00:00Z", "until": "2026-03-27T00:00:00Z" },
"growth": {
"new_contributors": { "current": 42, "previous": 31, "delta_pct": 35.5, "desirable": "up" },
"reactivated_users": { "current": 11, "previous": 8, "delta_pct": 37.5, "desirable": "up" },
"lost_regulars": { "current": 7, "previous": 5, "delta_pct": 40.0, "desirable": "down" },
"net_active_change": { "current": 46, "previous": 34, "desirable": "up" },
"trust_level_promotions":{ "current": 19, "previous": 12, "delta_pct": 58.3, "desirable": "up" }
},
"activity": { /* … */ },
"health": { /* … */ }
}
```
- `delta_pct` is omitted when the previous value is zero (otherwise it's `Infinity` and unhelpful).
- All durations are emitted in seconds in JSON/YAML; the text/markdown renderers humanise them.
- Schema is versioned via a top-level `"schema": 1` field so downstream consumers can pin.
### Markdown / markdown-table
Intended for piping into a topic reply or a status page. `markdown` produces a heading per section followed by a bullet list; `markdown-table` produces one table per section. Example workflow:
```bash
# Weekly community-health roll-up posted to a private staff topic
dsc analytics myforum --since 7d --compare --format markdown \
| dsc topic reply myforum 4242 --title "Community health — $(date -u +%Y-W%V)"
```
### CSV
One row per metric, columns: `section,metric,current,previous,delta,delta_pct,desirable_direction,unit`. Stable enough to append to a tracking spreadsheet.
## Data sources
All metrics are computed from the Discourse admin reports/API surface. The implementation MUST prefer the highest-level endpoint that already returns the metric, only falling back to derivation when no first-class report exists. Concretely:
- `/admin/reports/{id}.json?start_date=…&end_date=…` covers most counts: `signups`, `topics`, `posts`, `likes`, `flags`, `users_by_trust_level`, `trust_level_growth`, `moderators_activity`, `time_to_first_response`, `topics_with_no_response`, etc.
- `/admin/users/list/{filter}.json` is used for new-contributor first-post detection where the report doesn't carry it.
- `/admin/dashboard.json` is **not** trusted as a source — it bundles many of the metrics this command intentionally avoids and the bundle changes between Discourse releases.
Caching: a per-invocation cache in memory only. No on-disk cache in this iteration.
## Edge cases and explicit decisions
- **New install with < 30 days of history.** If `--since` exceeds the install age, the window is clamped to the install age and a one-line note is printed under the heading: `(window clamped — install is N days old)`. JSON includes `"clamped": true`.
- **Window of zero topics.** Sections still render; `posts per topic`, `reply coverage`, and `median time to first reply` print `—` (em dash) and JSON emits `null`. They MUST NOT print `NaN` or `0`.
- **Discourse running with `login_required = true` and the API key lacks admin scope.** Fail fast, do not silently degrade.
- **Anonymised / deleted users.** Their posts still count in totals; they're excluded from "unique posters" because Discourse anonymises the username.
- **PMs, whisper posts, and posts in private categories that the API key can't see.** Excluded everywhere. The command reports community-public health, not staff-channel health.
- **Time zones.** Windows are computed in UTC. The text header prints UTC dates explicitly so cron'd output is unambiguous.
## CLI consistency conformance
This command must comply with the standards in `spec/spec.md`:
- `--format text|json|yaml` baseline plus the listed extras.
- Empty / clamped sections follow the empty-list behaviour: text renders `—`; JSON/YAML emit `null` or `0` as appropriate (never strings like `"n/a"`).
- Errors use the standard messages (`discourse not found: …`, `missing apikey for …`).
- Short flags lowercase; `-s`, `-c`, `-f` chosen to mirror existing commands.
## Future work (out of scope for v1)
- Per-category breakdown (`--category support,announcements`).
- Per-group breakdown (`--group regulars`).
- A `dsc analytics watch` long-running mode that posts a weekly roll-up to a configured topic on a schedule.
- A `--baseline <path>` flag that loads a previously emitted JSON snapshot and computes deltas against it, decoupling "compare" from a fixed prior window.
- Surfacing of "topics that are spiking" (a leaderboard of topics whose post rate in the last 24h exceeded their 7-day baseline by N×). Useful but not headline-health.
## Implementation follow-ups
v1 ships ~half the metrics directly from `/admin/reports/{id}.json`; the per-user-walk metrics print `— (n/i)` and remain unimplemented. These notes capture the open design decisions for filling them in.
### Stubbed metrics and the per-user-walk cost concern
`new_contributors`, `reactivated_users`, `lost_regulars`, `top_10_share`, and `returning_poster_rate` all require per-user post-history walks beyond what `/admin/reports/{id}.json` exposes directly. On a busy forum a naive implementation is N HTTP calls per `dsc analytics` run (where N = unique posters in the window), which can be 200+ requests and 5-10 seconds of latency.
**Recommended path:** gate the expensive metrics behind a `--full` flag. Default invocation runs in <1s with the Discourse-report-derivable metrics; `--full` opts into the per-user walk with a documented latency cost. Alternatively cap the walk at the top N posters by post count and report "reactivated among heavy posters" as a proxy.
> **When implementing the per-user-walk metrics, filter out Discourse system accounts.** `admin_list_users` returns `system` (id `-1`) and `discobot` (id `-2`) in the `active` listing. Without an `.filter(|u| u.id > 0)` at the right point, they will be counted as "lost regulars" (because they don't post) and inflate the unique-poster denominators. Cheap one-liner; just don't forget. See [spec/user-list-negative-ids.md](user-list-negative-ids.md) for the underlying typing fix that enabled correct parsing.
### Cheap wins still to land
These don't need the user-walk and could ship as an early follow-up patch:
- **`solo_thread_rate`** - `% of topics in the window where only the OP posted`. One call per category via `/c/{category}/l/latest.json` filtered by `created_at`. Cheap.
- **Window clamping for new installs** - if `--since` exceeds install age, clamp and print a `(window clamped — install is N days old)` note. One `GET /about.json` call.
- **ANSI colour on arrows** - autodetect TTY, respect `NO_COLOR`. Mirror whatever convention `dsc list` uses today so behaviour is consistent across the CLI.
### Open report-id verification
The `flag_response_time` report ID returns 500 on at least one tested forum. May have been renamed (`time_to_resolution`?) or removed. Currently rendered as `—`. Reconfirm against a current Discourse before wiring in.
`time_to_first_response.average` is exposed by Discourse; the spec calls for **median**. The daily `data` array could be re-aggregated to a real median, but this requires raw post timestamps rather than the report's pre-aggregated daily averages. v1 uses Discourse's `average` and documents the caveat in [docs/analytics.md](../docs/analytics.md). Promote to a real median if a forum operator complains.
### Schema versioning is a public contract
The JSON / YAML output emits `"schema": 1`. Once shipped, breaking a key warrants `"schema": 2`. Treat this as a stability commitment; downstream consumers (cron-driven trend tracking, third-party dashboards) will pin against it.