openvidu/openvidu-dashboard/openspec/specs/analytics-ui/spec.md

# analytics-ui Specification

## Purpose
The Analytics page: usage of the deployment over the global time range as KPI tiles, time-series charts and
breakdowns (ingress with its input type included), with locked cards for quality, diagnostics and top rooms, a locked
per-node scope, and CSV export per section.

## Requirements

### Requirement: Analytics route and URL state

Edition: CE. `/analytics` SHALL be a range-scoped route whose state lives only in `from`, `to`, `tz`, `granularity`
(default `auto`) and `scope` (default `global`); invalid values SHALL fall back silently, and `scope` SHALL be
dropped when `per-node-breakdown` is not enabled.

#### Scenario: Deep link

- **GIVEN** `/analytics?from=now-7d&to=now&tz=UTC&granularity=1h`
- **WHEN** the page opens in a new browser
- **THEN** every request carries the same range and `granularity=1h`, and the selectors show "Last 7 days", "UTC"
  and "1 h"

#### Scenario: Node scope in CE

- **GIVEN** the UI loaded `features: []`
- **WHEN** `/analytics?scope=node:n1` opens
- **THEN** the URL is rewritten without `scope` and every request uses the global scope

### Requirement: Granularity selector

Edition: CE. The granularity selector SHALL offer `auto`, its label always naming what `auto` resolves to for the
current range whatever value is selected, and only the explicit values the API accepts for the range; changing it SHALL
write `granularity` to the URL. A chart of metrics stored only in hourly and daily documents SHALL be requested at `1h`
while the effective granularity is below `1h` and read "Hourly" in its subtitle.

#### Scenario: Seven-day range

- **GIVEN** `from=now-7d&to=now&granularity=auto`
- **WHEN** the selector renders
- **THEN** it reads "auto (1 h)" and offers `1h`, `6h` and `1d`, not `5m` or `15m`

#### Scenario: Explicit value selected

- **GIVEN** `from=now-7d&to=now&granularity=1d`
- **WHEN** the user opens the selector
- **THEN** "1 d" is selected and the auto option reads "auto (1 h)"

#### Scenario: Hourly-only chart on the default range

- **GIVEN** the default 24 h range at `auto`
- **WHEN** the Egress section renders
- **THEN** the `egressStarted` chart is requested at `5m` and the `egressEnded` chart at `1h` with 24 buckets and the
  subtitle "Hourly"

#### Scenario: Old 24-hour range

- **GIVEN** an absolute 24 h range that ended 30 days ago and a 5-minute rollup retention of 7 d
- **WHEN** the selector renders
- **THEN** it reads "auto (1 h)" and offers `1h`, `6h` and `1d`

#### Scenario: Short 5-minute rollup retention

- **GIVEN** `GET /api/v1/info` reports `retention.statsMs` of 7 d and `retention.rollups5MinMs` of 2 d, and an
  absolute 24 h range that ended 3 days ago
- **WHEN** the selector renders
- **THEN** it reads "auto (1 h)" and does not offer `5m` or `15m`

#### Scenario: Explicit values of the range

- **WHEN** the selector lists its explicit values for the current range
- **THEN** it offers `5m` and `15m` only for ranges of at most 24 h inside the 5-minute rollup retention, and no value
  above 1 000 buckets

### Requirement: KPI tiles

Edition: CE. The tile row SHALL show, in this order, Rooms created, Participant sessions, Unique identities (labelled
"sum of N UTC days"), Data up / down (up and down on two lines, each with its arrow), Connection success, Egress
(count and total duration) and Ingress (sessions and total duration) from the summary endpoint with the shared
formatters, show "n/a" with a hint for a value the summary omits and keep the last value while refreshing.

#### Scenario: Tiles from the summary

- **GIVEN** a summary with `roomsCreated: 1203`, `bytesUp: 1200000000000`, `bytesDown: 3400000000000`,
  `uniqueIdentities: { value: 4120, days: 7 }`, `ingressSessions: 12` and `ingressDurationMs: 21600000`
- **WHEN** the tiles render
- **THEN** they read "1,203", "↑ 1.2 TB" over "↓ 3.4 TB" under "Data up / down", "4,120" with the label "Unique
  identities (sum of 7 UTC days)", and the Ingress tile "12" with the hint "6 h 00 m in total"

#### Scenario: Tile order

- **WHEN** the tile row renders
- **THEN** the labels read Rooms created, Participant sessions, Unique identities, Data up / down, Connection
  success, Egress and Ingress

#### Scenario: Missing average

- **GIVEN** a summary without `avgRoomSize`
- **WHEN** the Rooms section tiles render
- **THEN** the Average room size tile reads "n/a" with the hint "Not provided by this server version"

### Requirement: Rooms section

Edition: CE. The Rooms section SHALL show a bar chart of `roomsCreated` and `roomsEnded` per bucket and the tiles
Average room size (rounded to a whole number of participants) and Average room duration (in the shared duration
format) from the summary.

#### Scenario: Rooms over 24 hours

- **GIVEN** the default range at `auto` and a summary with `avgRoomSize: 4.4` and `avgRoomDurationMs: 360000`
- **WHEN** the section renders
- **THEN** the chart shows 288 five-minute buckets with two bar series in fixed colours and the tiles read
  "4 participants" and "6 m 00 s"

### Requirement: Participants section

Edition: CE. The Participants section SHALL show `participantsJoined` and `participantsAborted` as lines,
`connectionSuccessRate` as a percentage line in its own chart, a participant kind breakdown without SIP, CONNECTOR and
BRIDGE in which every kind has a distinct colour, and `uniqueIdentities` as bars per UTC day only when the effective
granularity is `1d`, otherwise a hint that unique identities are available at daily granularity.

#### Scenario: Weekly range hides unique identities

- **GIVEN** `from=now-7d` at `auto`
- **WHEN** the section renders
- **THEN** no `uniqueIdentities` series is requested and the card shows "Unique identities are available at daily
  granularity" with a "Switch to 1 d" action

#### Scenario: Daily override

- **GIVEN** `granularity=1d`
- **WHEN** the section renders
- **THEN** the unique identities bars are shown with the note "per UTC day" under the chart title, clear of the legend

#### Scenario: Kind breakdown

- **GIVEN** a breakdown with `STANDARD: 900`, `EGRESS: 40`, `AGENT: 12`, `INGRESS: 3` and `SIP: 1`
- **WHEN** the section renders
- **THEN** the chart shows Standard, Egress, Agent and Ingress, each in a different palette colour, and no SIP entry

### Requirement: Client breakdowns section

Edition: CE. The Client breakdowns section SHALL show SDK, OS, browser and connection type from the breakdowns
endpoint as donuts with legend, direct labels, fixed colours per key, "Other" beyond eight entries and a table toggle
listing key, count and percent, every SDK, OS and connection type key shown by its shared friendly label (browser
names as stored) and every percent in the shared percent format ("62.8 %").

#### Scenario: Nine SDKs

- **GIVEN** nine SDK keys in the range
- **WHEN** the SDK donut renders
- **THEN** eight slices plus "Other" are drawn and the table toggle lists all nine with counts and percentages

#### Scenario: Donut percent

- **GIVEN** an SDK breakdown in which `js` holds 628 of 1 000 sessions
- **WHEN** the SDK donut renders
- **THEN** the direct label of its slice and the percent column of its table read "62.8 %"

#### Scenario: Friendly labels

- **GIVEN** a connection type breakdown with a known key and a key the label map does not know
- **WHEN** the donut and its table render
- **THEN** the known key reads its friendly label and the other key reads as stored

### Requirement: Bandwidth section

Edition: CE. The Bandwidth section, headed "Data transferred", SHALL show `bytesUp` and `bytesDown` per bucket in the
area chart "Data up / down", one unstacked area per direction with byte formatting, and the two totals from the summary
as tiles.

#### Scenario: Bandwidth chart

- **GIVEN** series with bytes in half of the buckets
- **WHEN** the chart renders
- **THEN** the x-axis spans the whole range, empty buckets read 0 and the tooltip formats values as "1.2 GB"

#### Scenario: Unstacked directions

- **GIVEN** a bucket with 2 GB up and 3 GB down
- **WHEN** the chart titled "Data up / down" renders
- **THEN** the Down area reaches 3 GB from zero, not 5 GB on top of the Up area

### Requirement: Egress section

Edition: CE. The Egress section SHALL show the tiles Total egress and Total duration (the summary's `egressStarted` and
`egressDurationMs`), `egressStarted` as the bar chart "Egress started" beside the "Egress type" donut, and the
`egressEnded.<status>` series as the stacked bar chart "Egress ended by status"; each chart requested at `1h` while
the effective granularity is finer reads the "Hourly" note under its title.

#### Scenario: Ended by status

- **GIVEN** egresses ended as `complete`, `aborted`, `limit_reached` and `failed` (the `egressEnded.<status>` series)
- **WHEN** the chart renders
- **THEN** four stacked segments per bucket are drawn in four distinguishable colours, `failed` in the red slot and
  `aborted` apart from the red of aborted participants, and the legend names all four

#### Scenario: Totals

- **GIVEN** a summary with `egressStarted: 120` and `egressDurationMs: 36000000`
- **WHEN** the section renders
- **THEN** the tiles read Total egress "120" and Total duration "10 h 00 m"

#### Scenario: Status colours

- **WHEN** the "Egress ended by status" chart renders
- **THEN** failed statuses are drawn in red and every status in its own distinguishable colour

### Requirement: PRO strip and locked cards

Edition: CE. Right after the Ingress section, in the same column of cards as the CE sections, the page SHALL render
the cards Quality, Diagnostics and Top rooms; when the matching feature is disabled each card SHALL render the compact
in-card lock, sized to its message rather than to the real card, without any request.

#### Scenario: Strip in CE

- **GIVEN** the UI loaded `features: []`
- **WHEN** the Analytics page renders
- **THEN** the three PRO cards follow the Ingress section and show the compact lock with their feature title, each
  only as tall as its message, and no request to `/analytics/top`, `/analytics/scopes` or a PRO metric is sent

### Requirement: Diagnostics section

Edition: CE. Without `analytics-diagnostics` the Diagnostics card SHALL render its lock, reading "Diagnostics is
available in OpenVidu PRO".

#### Scenario: Locked in CE

- **GIVEN** the UI loaded `features: []`
- **WHEN** the card renders
- **THEN** its heading reads "Diagnostics" and the lock reads "Diagnostics is available in OpenVidu PRO"

### Requirement: Ingress section

Edition: CE. The Ingress section SHALL render right after the Egress section and before the Quality card, never
locked, with the tiles Total sessions (`ingressSessions` of the summary) and Total duration (`ingressDurationMs` of
the summary), `ingressSessions` as the bar chart "Ingress sessions", which reads "Hourly" in its note while it is
requested at `1h` below an effective `1h`, and the `ingressInputType` breakdown as the donut "Ingress input type".

#### Scenario: Ingress sessions

- **GIVEN** a summary with `ingressSessions: 12` and `ingressDurationMs: 21600000`
- **WHEN** the card renders
- **THEN** bars per bucket are drawn and the tiles read Total sessions "12" and Total duration "6 h 00 m"

#### Scenario: Ingress input type donut

- **GIVEN** a breakdown `ingressInputType` with `rtmp` 8, `whip` 3 and `url` 1
- **WHEN** the card renders
- **THEN** the donut "Ingress input type" shows the slices RTMP 8 (66.7 %), WHIP 3 (25.0 %) and URL 1 (8.3 %)

#### Scenario: Ingress in CE

- **GIVEN** the UI loaded `features: []`
- **WHEN** the Analytics page renders
- **THEN** the Ingress section follows the Egress section and precedes the locked Quality card, shows its data without
  a lock, and its ingress series request is sent

### Requirement: Per-node scope selector

Edition: CE. Without `per-node-breakdown` the page header SHALL show the scope selector disabled on "All nodes"
with a lock icon whose tooltip says per-node analytics is available in OpenVidu PRO.

#### Scenario: Locked in CE

- **GIVEN** `features` without `per-node-breakdown`
- **WHEN** the header renders
- **THEN** the selector reads "All nodes", is disabled with the lock icon and no `/analytics/scopes` request is sent

### Requirement: CSV export per section

Edition: CE. Every section card except Top rooms SHALL have an "Export CSV" action in its header that downloads the CSV
of the card's series or breakdowns with the current URL parameters through the shared HTTP service, saves it under the
server file name and is disabled on locked cards.

#### Scenario: Bandwidth export

- **GIVEN** the Bandwidth card over the last 7 days
- **WHEN** the user clicks "Export CSV"
- **THEN** `GET /api/v1/analytics/export.csv?kind=series&metrics=bytesUp,bytesDown&from=…&to=…&tz=…&granularity=…`
  is requested with the bearer token and the browser saves `analytics-series-….csv`

#### Scenario: Export failure

- **WHEN** the export request fails
- **THEN** a toast shows the error message and request id and the card stays interactive

### Requirement: Card states

Edition: CE. Each card SHALL show a skeleton of its height only until its first data, "No data in this range" with a
"Widen range" action, only as tall as that message, when every point is empty, and, when its request fails, the shared
error notice with retry and request id above the card's last content, without affecting other cards; the page SHALL show
an info banner when `from` is older than the retention of the source collection.

#### Scenario: One card fails

- **GIVEN** the breakdowns request fails and the series requests succeed
- **WHEN** the page renders
- **THEN** the Client breakdowns card shows the error notice with "Retry" and the other cards show their data

#### Scenario: Failed refresh keeps the content

- **GIVEN** every card showing data
- **WHEN** a manual refresh fails for the series of the Rooms card
- **THEN** the Rooms card keeps its chart and tiles under the error notice, and no skeleton replaces them

#### Scenario: Empty card

- **GIVEN** a range in which the Egress card has no data
- **WHEN** the page renders
- **THEN** the Egress card shows "No data in this range" with "Widen range", only as tall as that message and not as
  tall as its charts would be

#### Scenario: Range older than the hourly retention

- **GIVEN** `from` 500 days ago and an hourly retention of 400 d
- **WHEN** the page renders
- **THEN** a banner reads "Hourly data older than 400 days is not retained; daily values are shown" and the charts use
  `1d`

### Requirement: Analytics refresh

Edition: CE. The page SHALL NOT refresh on its own, whatever the range: the header's refresh control SHALL show only
the manual refresh button and the last update time, without an interval menu, and a manual refresh SHALL re-query
every section with one request per endpoint, keep the previous values while it runs and update the charts in place.

#### Scenario: Absolute range

- **GIVEN** `from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z`
- **WHEN** the page is open for several refresh intervals
- **THEN** no further analytics requests are sent after the initial load

#### Scenario: Relative range

- **GIVEN** `from=now-24h&to=now`
- **WHEN** the page is open for several minutes
- **THEN** no further analytics requests are sent after the initial load, and the header shows the refresh button
  and "updated hh:mm:ss" with no interval menu

#### Scenario: Manual refresh

- **GIVEN** the page loaded with `from=now-24h&to=now`
- **WHEN** the user presses the refresh button
- **THEN** each analytics endpoint the page uses is requested once, the cards keep their values until the answers
  arrive, and the charts update without a skeleton

### Requirement: Analytics chart notes

Edition: CE. Every time-series chart of the Analytics page SHALL name, in the note under its heading, its bucket
("Hourly" for a chart requested at `1h` while the effective granularity is finer, otherwise the effective granularity)
and the time zone of its time axis; the unique identities chart names UTC and keeps "per UTC day".

#### Scenario: Default range

- **GIVEN** the default 24 h range at `auto` with `tz=Europe/Madrid`
- **WHEN** the charts render
- **THEN** the note of "Rooms created and ended" names the five-minute bucket and Europe/Madrid, and the note of
  "Egress ended by status" reads "Hourly" with Europe/Madrid

#### Scenario: Daily unique identities

- **GIVEN** `granularity=1d` and `tz=Europe/Madrid`
- **WHEN** the unique identities chart renders
- **THEN** its note reads "per UTC day" and names UTC, not Europe/Madrid

### Requirement: Media statistics coverage notes

Edition: CE. With `mediaStats: "none"` in the summary, the Data up / down tile SHALL read "—" with the hint "Not
reported by the servers of this range" and the Bandwidth section SHALL show the notice "The servers of this range do
not report media statistics" instead of its chart and tiles. With `"partial"`, the tile and the section SHALL keep their
values and add the note "Only from the servers that report media statistics".

#### Scenario: No server reports media statistics

- **GIVEN** a summary with `mediaStats: "none"`
- **WHEN** the page renders
- **THEN** the Data up / down tile reads "—" with its hint, and the Bandwidth section shows the notice and no chart

#### Scenario: Some servers report media statistics

- **GIVEN** a summary with `mediaStats: "partial"`, `bytesUp: 1200000000` and `bytesDown: 3400000000`
- **WHEN** the page renders
- **THEN** the tile reads "↑ 1.2 GB" over "↓ 3.4 GB" with the hint "Only from the servers that report media
  statistics", and the Bandwidth chart renders with the same note under its heading

#### Scenario: Every server reports media statistics

- **GIVEN** a summary without `mediaStats`
- **WHEN** the page renders
- **THEN** the tile and the Bandwidth section render as before, without the note