Configuration

Configuration

The settings page is at Dashboard > Plugins > Playback Statistics. Eight settings decide what is recorded, how long it is kept, and how much a report may ask for.

The checked reference, with the accepted range of every field and what each one does not do, is docs/configuration.md; the test suite reads that table against the code, so it is the one to trust on a number.

What each setting is for

setting	default	what it decides
Capture enabled	on	Whether plays are recorded at all. Off means nothing new is written; it hides and deletes nothing already stored.
Play row retention days	90	How old a raw play row may get before the retention sweep deletes it.
Daily aggregate retention days	400	How old a day's totals may get before the same sweep deletes them.
Maximum range days	367	The widest range a report may ask for. A longer range is refused, never quietly shortened.
Maximum rows per response	1000	The most rows a report may carry. A larger answer is refused, never cut to the first of them.
Rollup time zone	UTC	The zone a day is counted in. Rows are stored in UTC, so this decides which day a late evening play falls on.
Excluded user ids	empty	Accounts whose plays are not recorded. This is an administrator excluding somebody, not somebody excluding themselves.
Excluded item types	empty	Kinds of item whose plays are not recorded.

A value outside what a setting accepts is refused rather than clamped, and the field falls back to its default. Refusing is deliberate: a retention of eleven thousand days clamped to ten years is a setting that means something other than what it says, and nobody would be told. The page names the fields that fell back, above the form.

What takes effect when

None of the eight needs a restart. Each is read at the moment it is used: capture and the two exclusion lists before every play is written, both retention windows at every sweep, and the zone and the two caps at every request for a report.

Nothing here is retroactive, with one exception. Turning capture off, or adding an account or an item type to an exclusion list, stops new rows and removes none. The two retention settings take effect on the next sweep, not on save, so shortening either deletes nothing at the moment the page is saved.

The exception is the zone, and it changes a reading rather than a row. A stored play does not move; what moves is which local day it is counted on, so the same rows can produce different daily totals under a different zone. An aggregate computed under the old zone is not reused: the store states the zone its rollups were keyed in, and a report asked for in a zone with other rules folds the play rows instead.

The two retention windows, and which deletion cannot be undone

The sweep is a scheduled task. It runs daily and can be started by hand from the server's scheduled tasks page, where it is called Delete playback statistics past their retention windows. It is one task over both windows, off one reading of the clock, so the two boundaries cannot be measured from different days.

Neither window is a display filter. A row past its window is deleted from the store, the plugin keeps no second copy, and there is no undo. A window shortened by accident and corrected an hour later does not bring back what the sweep removed in between. The plugin takes no export of its own, so the only thing a row can be restored from is a copy somebody made deliberately.

Which of the two numbers is larger decides whether the aggregate deletion can be undone, and nothing on the settings page says so.

• Aggregate retention larger than row retention, which is the shipped arrangement: a day's totals outlive the rows they were folded from, so when they go they are the only remaining record of that day and the deletion is terminal.
• Aggregate retention smaller than or equal to row retention: the rows are still in the store when the totals go, so the day can be folded again, and until it is, a report over that range reads the rows instead. A slower report rather than a wrong one.

Both are accepted and nothing refuses either. Inside one run the aggregates go first, so a sweep stopped halfway leaves the second case recoverable rather than making it terminal by taking the rows away first.

What is deleted when a play row passes its window is the row itself: which account played which item, when it started and stopped, how much was watched, the client and device, and whether the server transcoded and why. What is deleted when a day's totals pass theirs is that day's counts per account, item type and client. No name is in the second.

Two things an administrator does not switch on and cannot switch off

Deleting an account from the server deletes every row belonging to it, at the moment the server publishes the deletion, and gives the space back to the file.

A daily task covers the account deleted while this plugin was not loaded, since a plugin that is not running hears nothing. It reads every account the store still names, asks the server about each, and deletes the rows and the consent record of the ones the server no longer has. It is in the scheduled tasks list as Delete playback statistics belonging to accounts the server no longer has. An account the server cannot be asked about, because the lookup failed rather than because it is gone, keeps its rows: a failure costs a run rather than somebody's history.