#FE: Log Monitoring screens (from backend Phase 13)
Frontend spec for backend Phase 13 — Log Monitoring add-on — requirements complete 2026-10-07, not built. Two parts of it live on the OSS side (13.3 and 13.5), and as of 2026-10-07 the OSS team has been told and adds them during development — so they are planned dependencies, not unknowns. Rewritten three times on the morning it appeared, the last time to follow the V7-to-V8 change in how it runs. The numbering reached 13.1–13.12: collecting logs is 13.5, reports 13.6, update 13.7, remove 13.8, the activity log 13.9, and 2026-10-07 added three more — low disk space (13.10), notifications (13.11) and unreadable logs (13.12). V8 requirement This is V7's InsightHub, rebuilt as reports inside Central instead of a separate dashboard app on the user's server.
Add-ons page — the card
included with a plan, or bought. Lost on a downgrade
Server — install the toolkit here, then update or remove it; OSS runs its commands
Apps — every app on the server, registered automatically; no per-app switch
Application panel — the reports
Dashboard, Traffic, Errors, Bots, User Agents, Bandwidth
i18n namespaces: addons.logMonitoring.*, logMonitoring.install.*, logMonitoring.reports.*.
#A. The add-on itself
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 13.1 | The add-on | Add-ons card | Included in a plan (7.26) or bought — same as V7. Taking and paying an eligible plan enables it automatically on the account. Tied to the plan: moving to a plan without it switches it off and removes it from all the user's servers, as V7 does on downgrade | The card reads Included when the plan carries it, which is the normal 7.26 behaviour — unlike White label, which reads Purchased. The removal is the part that needs care: it is not a quiet flag change, it uninstalls from every server, so the plan-change screen has to say which servers lose monitoring before the user confirms — and since 13.7 was answered on 2026-10-07, it must also say that every collected report is deleted and that turning the add-on back on starts from zero. The add-ons card needs a state for "switched off because your plan changed" that explains how to get it back, without implying the old reports come back with it |
| 13.2 | Licence | An error state, not a screen | Before every command the toolkit asks ServerAvatar's licence service "has this server bought it?", recognising the server by its IP. Central answers yes for every server on an account that has the add-on — otherwise the reports are refused with "licence required" | The refusal is the frontend's share of this. "Licence required" is not a crash and not an empty report: it means the add-on is gone or the server is not recognised, so the reports screen must say which and point at the add-ons card. And since recognition is by IP while 9.29 lets a server's IP change in Central, this is the most likely way a user meets that message — whether the licence service follows an IP change is not stated (see the open items) |
| 13.11 | Notifications | Existing notification settings | Added 2026-10-07: Log Monitoring installed / updated / removed and low disk space go out as notifications through Phase 11, as V7 | Nothing new to build — these are events in the catalogue the notifications phase already defines (11.5), so they land in an existing group with no screen change. Which group is not stated, and this spec does not pick one. It does mean the low-disk warning reaches the user twice — as a notification and as the warning on the server (13.10) — so the two should read the same way |
| 13.9 | Activity log | Existing activity log | Install, update and remove are recorded (as V7) — the per-app entries went with the per-app switch on 2026-10-07 | New event types for the log that already exists — nothing new to build, but each entry must name the server, since that is now the only level this add-on works at |
#B. Installing it on a server
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 13.3 | Install on a server | Install Log Monitoring — a server-level action, placement undecided, see D-46 | After a server is created, the user clicks Install Log Monitoring. Central asks OSS whether the toolkit is there (installed, and which version); if not, OSS puts it on the server — the program, its settings and a new database. Progress is shown until it finishes. OSS side — the OSS team adds install, update and remove during development (told 2026-10-07) | An OSS dependency with an owner, which is better than it looked an hour earlier — it was first written as something OSS "cannot do today"; it is now scheduled work, so this screen can be designed against it rather than parked. Three things the screen owes the user. It is a real install, not a switch — a program and a database land on their server, so say so before the button. The "already installed?" check comes first, which means three entry states, not two: not installed · installed (with its version) · installed but older. And progress reuses the add-server install pattern (8.9) — live steps, a reason on failure, Retry — rather than a second progress screen of its own |
| 13.4 | Apps become monitored | Nothing to build — there is no control | Changed again 2026-10-07: after install Central asks OSS to register all apps of the server — OSS runs the toolkit's "add app" command with the name, system user, domain, web server and SSL; apps created later through Central are registered too; domain or SSL changes update the registration; and deleted apps are removed by OSS itself (that part already exists there). There is no per-app on / off — as V7, it covers every app on the server | This reverses what this page published an hour earlier. The first version of 13.4 had a per-app switch and this spec described it as "an off switch for exceptions"; the backend has now removed the switch entirely, so there is no per-app control to design at all — monitoring is a property of the server, not of an app. Two consequences worth stating: an app screen must never imply monitoring can be turned off for one app, and the only way to stop it is to remove the toolkit from the server (13.7), which stops it for everything. The automatic housekeeping is the good news — new apps, domain and SSL changes and deletions all keep themselves in step |
| 13.4 | Corrected 2026-11-03 (Pair 2): per-app on / off, as V7 | App → Log Monitoring switch · Server → Log Monitoring "Turn on for all apps" · Create application checkbox | The row above ("no per-app on / off") is superseded. ✅ Built (Step B 2026-11-02; create-app choice 2026-11-03): turn on / off for one app (Pair 2 API134 → "Log Monitoring is on for this application." / API135 → "Log Monitoring is off for this application."; turning off keeps already-collected data until it's pruned) · turn on for every app of the server (API137 → lists registered / already on / failed apps; 409 log_monitoring_not_installed) · create app takes install_log_monitoring (default on; off = turn it on later). An app created through Central is turned on by itself once it's active, when the program is installed and the owner has the add-on | Add a "Turn on Log Monitoring" checkbox (ticked) to Create application, shown only when the owner has the add-on and it's installed on the server. App → Log Monitoring gets an On / Off switch above the report tabs (Off → reports hidden, "Log Monitoring is off for this app"). Server → Log Monitoring gets Turn on for all apps with a per-app result list |
| 13.5 | Collecting the logs | Nothing to build — but it decides what the reports show | New item 2026-10-07: the toolkit's fetch command reads new access-log lines into its database every 15 minutes, and prune deletes data older than the retention days (default 7) once a day. Both run from OSS's own scheduler (there is no separate service). OSS side — added by the OSS team during development | The second OSS part, and the one with the most reach into the screens. Nothing here is built by the frontend, but the schedule decides what the reports can ever show: until fetch runs there is nothing to report, so "collecting data" is a state the design must carry properly rather than an edge case, and it should say why it is empty instead of looking like a slow first run. The 15-minute gap is also the answer to "why is my traffic not showing?", so put it on the reports screen in words |
| 13.7 | Update | Update on the same server screen | OSS replaces the toolkit with a new version and the data is kept (bot detection is re-checked once) | A plain Update with the current and available version. "Data is kept" is worth saying on the screen, because the neighbouring action deletes everything — users who have read the Remove warning will assume the worst about Update too. The bot-detection re-check is the backend's own follow-up, not a user choice |
| 13.8 | Remove | Remove TYPE-TO-CONFIRM | Answered 2026-10-07 — same as V7: unregister all apps, stop collecting, remove the toolkit and delete its database with every collected statistic. Installing again starts fresh — the old history is gone. The same happens on a plan downgrade (13.1) | Now that the answer is known, this is data loss, not a disconnect — so it earns the strongest confirm in the add-on: name the server, say all collected reports are deleted, and say that reinstalling starts from zero. The earlier version of this page could not promise either way; it can now. And the harder consequence is the one the user does not initiate: a plan downgrade deletes the same data on every server, so the plan-change screen must say reports will be deleted, not merely monitoring will stop. There is nothing to download first — the backend offers no export |
#C. The reports
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 13.6 | Reports | In the Application panel (Phase 10) — no item for them in the fixed app menu, see D-46 | Dashboard, Traffic, Errors, Bots, User Agents, Bandwidth — the same groups as V7, 49 reports, and some take a limit, a field or a status code. OSS keeps each answer for a short time, so re-opening is fast. Before the first collection Central shows "collecting data" — corrected 2026-10-07: not zeros. Central → the OSS API → OSS runs the report command → the answer comes back as data | Six groups and 49 reports is a section, not a tab, and it is the largest single addition to the app panel so far. Three rules keep it sane. Per-report options, not one global filter: the backend says some reports take a limit, a field or a status code, so the controls belong to the report and the state stays in the URL so a view can be shared. "Collecting data" is a first-class state, and the wording tightened on 2026-10-07 — it is not a grid of zeros but a message, because a zero is a legitimate value and a user cannot tell an idle site from a broken install. It also may not be temporary: until OSS schedules the collection (13.5) it is the only state the reports can reach. And the reports are read-only, so none of them needs a mutation path. OSS's short-lived cache means a refresh may legitimately return the same numbers — do not present that as stale |
| — | Where the data comes from | — | The reports come from the toolkit on the server, read through the OSS API — and the backend notes the OSS panel itself has no Log Monitoring screen; this is a Central-only add-on API | So these screens have no OSS counterpart to copy, unlike every other app screen in Phase 10. They are our own design, and the offline-panel state matters more than usual: without the panel there are no reports at all, so the group needs the same unreachable state as the rest of the app panel |
#D. When it stops, and why the reports are empty
Three different reasons an app can show nothing, all added or confirmed on 2026-10-07. The frontend's job is to tell them apart — "no data" on its own is the least useful thing these screens could say.
| # | Case | Rules from the backend doc | Frontend notes |
|---|---|---|---|
| 13.10 | Less than 5 GB free on the server | As V7: the toolkit stops collecting to protect the server. Central shows a warning on the server and emails the owner with the free and total space. Collecting restarts by itself once space is freed — nothing to click. (OSS side: OSS shares the last collect result with Central) | The best kind of rule: it fixes itself, so the screen must not offer a fix that does not exist. No "resume" button — say what happened, show the free space, and point at the Disk cleaner (9.20), which is the actual way out. The warning belongs on the server, since it is the server's disk, while the empty reports are on the app — so the app's empty state should name the server-level cause rather than leaving the user to guess |
| 13.12 | An app's log file cannot be read | New 2026-10-07: Central shows a small warning on that app — "logs not readable" — so the user knows why its reports are empty | This is the per-app half of the same problem, and it is the reason this phase can have an empty report with a healthy server. Keep it small and in place: a line on the app's reports, not a banner across the panel, and worded as a fact rather than an error the user caused. One app being unreadable says nothing about the others |
| — | Fetch has not run yet | 13.5 — the first collection has not happened | The third case, and the only one that passes on its own. "Collecting data" (13.6) |
Put plainly, the reports screen needs three distinct empty states: collecting data (wait), logs not readable (this app), and low disk space (this server, clears itself). Plus "licence required" from 13.2, which is not an empty state at all but a refusal.
#What this phase answers
| Open item | Answer |
|---|---|
| Log Monitoring was "an add-on phase, later" on FE: Application screens, FE: Plans & subscription 7.26 and FE: Notifications & mail | It is now a written phase (13.1–13.7) V8 requirement — the third add-on to get one, after White label (Phase 12) |
| What happened to V7's InsightHub? | Both halves are gone. The separate dashboard app, its domain and its domain-change flow are not in V8 — the reports live in Central instead. And the agent service that ran on every server is gone too (added 2026-10-07): the toolkit is a command-line program OSS runs when asked, so nothing sits running on the box. That also retires V7's "monitoring domain change" message, which Phase 11's email map had parked for this phase |
| Is an add-on lost on a downgrade? | It depends on the add-on, and now both answers exist — White label is lifetime (12.11), Log Monitoring is removed from every server (13.1). The downgrade check (7.8) must name the second and not the first |
| What do V7 Log Monitoring owners keep? | They keep the add-on while their plan includes it, and their servers start fresh on the OSS toolkit — the old V7 InsightHub agent service is stopped and removed first, so logs are not read twice. Past report history from V7 is not carried over, so a migrated user's reports legitimately start at zero and need the same "collecting data" message as a new install, not an error |
#Still open after this phase
| # | Question |
|---|---|
| D-46 | Where do the reports and the install action go? 13.6 puts six report groups in the Application panel, but the frontend doc's app menu order is fixed (U14.4) and has no item for them; 13.3's install / enable is a server-level action and the server menu is fixed too (U13.4). Same family as D-40, D-43 and D-45 |
| — | Does the licence follow a changed IP? 13.2 recognises a server by IP; 9.29 lets the IP change in Central. Nothing says whether monitoring keeps working, so no screen promises it Open question |
| — | |
| — | Two parts of this phase are OSS work, now owned rather than open V8 requirement: install, update and remove of the toolkit (13.3, 13.7, 13.8) and running fetch every 15 minutes and prune daily from OSS's own scheduler (13.5). The OSS team was told on 2026-10-07 and adds both during development — so this is sequencing, not a blocker: Central's screens can be designed now, and the reports simply have nothing to show until the schedule exists |
| — | Can the user change the retention days? The default is 7 and prune runs daily (13.5), but nothing says whether either is a setting, so no screen offers to change them Open question |
| — | What about apps created later directly in the OSS panel? 13.4 registers all existing apps at install, and apps created through Central afterwards; an app made in the panel later is still not mentioned Open question |