cesnimda
25 lines
3.9 KiB
Markdown
25 lines
3.9 KiB
Markdown
# System Status and diagnostics
|
|
|
|
## What the page can report today
|
|
|
|
| Signal | Source and limit |
|
|
| --- | --- |
|
|
| Backend status and refresh | The admin status GET reports environment, build and runtime details. Its success indicates a response from that endpoint. The UI timestamp is when the browser received that response. A failed refresh retains the earlier timestamp with the existing warning. |
|
|
| Database | The status GET attempts database reads and reports connectivity and query warnings. This is a point-in-time observation. |
|
|
| AI | The status GET displays summarizer metrics and their own available timestamps. The manual probe is a separate existing action. A status response alone does not prove a model, OCR, or a processing task succeeded. |
|
|
| Processing | The Admin Processing monitor owns worker flags, recorded operations, counts, and recorded failures. A flag alone gives no liveness guarantee. Any future status summary should link to that owner and label unsupported queues or heartbeats as unavailable. |
|
|
| Mail, external providers and scheduled enrichment | No system-wide measurement is established in this slice. A per-user connection and configuration flags are insufficient evidence for service health. Aggregate only supported service signals and keep account or job content out of the admin view. |
|
|
| API errors and timings | Existing AI timings remain scoped to AI. General request error rates and latency need their own instrumented source, time window and sample counts. |
|
|
|
|
Source owners are `AdminSystemController.Get`, `AdminProcessingController` and `AdminSystemPage`. Preserve the separation between an observed value, an earlier value with its timestamp, a failure to read and a signal the app does not measure. Each eventual backend metric needs its own observation time and sampling window where applicable.
|
|
|
|
## Proposed operator flow
|
|
|
|
In an Advanced diagnostics section, list the approved suite name, description, target environment, last execution and result. An unavailable suite shows its reason and has no Start control. An authorised operator reviews the fixed environment and scope before starting. A run row shows queued, running and terminal status with time and progress from the runner. History exposes a bounded, sanitised summary and a run ID.
|
|
|
|
The existing `MaintenanceJobDispatcher` only accepts `cv-benchmark` and dispatches a fixed Gitea workflow from `main`. The workflow uses a private CV corpus and AI service on the production host and publishes reports back to the running backend. Its queue acknowledgement is not a completion receipt. Retain CV Benchmark Review and its historical evidence for CV extraction qualification. Keep dispatch separate from the proposed isolated suites. This review executed neither path.
|
|
|
|
The first candidate for isolated execution is a fixture-only API smoke suite with a disposable datastore, synthetic records and AI/mail/providers disabled. A server-side allowlist must bind each suite ID to an immutable executable, target and resource limits. Inputs must never include shell commands, arbitrary arguments, URLs, credentials or a caller-selected environment. Validate administrator role and current session on every read and start, and recheck authorisation at dispatch. Use a separate least-privilege runner without production credentials, mounts or network paths. Apply time and concurrency limits, deduplicate starts, and record actor, suite, environment, revision, time and outcome. User data and secrets must never enter logs or history. Show structured allowlisted results and retain them only for an agreed interval.
|
|
|
|
Before enabling Start, qualify role and session denial, unknown suite IDs, duplicate starts, expired runs, cancellation and timeout cleanup, sanitised output, and absence of access to production or provider routes. Qualify status and history with fixtures independently of execution. Actual suite approval, runner isolation, retention and deployment remain separate decisions.
|