Sentinel

Read SiMa Sentinel telemetry from the selected board and control its traces. Sentinel serves its API on a unix socket that is never exposed over the network, so Insight reaches it from the board itself: in process when Insight runs on the board, and otherwise by running a small client there over SSH. Metric values are null when the board cannot measure them, never zero.

📄️Get Sentinel availability on the selected board

Reports whether the `simaai-sentinel` daemon is installed, running and answering on its unix socket, together with its version and the board it belongs to. A daemon that is missing, stopped or unreadable is reported as `available: false` with `status.state` and `status.error`, not as an HTTP failure; only board-level failures (no board selected, unreachable, timeout) use an error status. The daemon state is cached briefly per board, so polling this endpoint does not run a command on the board for every call. Pass `refresh=1` for an explicit re-check that bypasses this cache.

📄️Install Sentinel on the selected board

Runs `sima-cli neat install sentinel` on the board itself (the installer has no `--ip`) with `SIMA_INSTALL_CONTEXT=1`, `SIMA_CLI_CHECK_FOR_UPDATE=0` and a temporary download directory, using passwordless sudo. An installed and healthy daemon is never reinstalled: the installer restarts the daemon and would end a trace in flight, so that case returns `409 already_installed`. Without passwordless sudo the response names the exact command to run on the board.

📄️Get the board's current telemetry

Joins Sentinel's metric definitions with its latest sample so every value carries its label, unit, group and thresholds, and ranks each value as `ok`, `warn`, `critical` or `unavailable`. A metric the board cannot measure has `value: null` and status `unavailable`; it is never reported as zero. Definitions are cached per board for a minute, while the sample is read on every call. Samples are also appended to a bounded per-board history: pass `history=<n>` to get the last `n` samples as aligned per-metric series for sparklines. The history holds one run of polling: a sample more than a minute after the last one starts it again, since the series are drawn with their points evenly spaced and nothing polls this endpoint while the Stats page is closed, and so does a restart of the daemon, which every call checks. Cached samples, definitions and history are keyed by the board's generation and fingerprint, so selecting another board starts empty.

📄️Get the active trace

Returns Sentinel's active trace and its running summary in `sentinel`, or `trace: null` when nothing is being recorded.

📄️Start a named trace

Starts recording a named trace around a workload. Only one trace can be active and names must be unique, so a second start returns `409 trace_conflict` with Sentinel's own message. The request is validated before it reaches the board: a missing or empty name, a name containing a comma, an over-long note, or tags that are not a list of non-empty strings return `400 invalid_request` without touching it.

📄️Stop the active trace

Stops the active trace and persists it as a run, returning Sentinel's answer in `sentinel`. Returns `409 trace_conflict` when no trace is active or, when `trace_id` is sent, when the active trace is another one, and `409 stale_snapshot` without touching the board when `generation` names a board that is no longer selected. Current Sentinel versions compare `trace_id` and stop under one run-store lock; older schema-1 daemons retain their compatible check-then-stop behavior.

📄️List saved runs

Returns Sentinel's recording and completed run summaries in `sentinel.runs`, newest retention first. Runs are stored on the board and survive a daemon restart.

📄️Get one saved run

Returns one run by unique name or stable id, with its metadata, metric definitions and raw samples, in `sentinel`. An unknown or ambiguous name returns `404 not_found` with Sentinel's message. A run whose answer exceeds the 12 MiB Insight reads from the daemon (about three hours of samples) returns `502 response_too_large` with the limit in `limit_bytes`, rather than a truncated body.

📄️Delete one saved run

Permanently deletes one completed run from the board and returns the deleted run's `id` and `name` in `deleted`, with Sentinel's run list afterwards in `sentinel`. Sentinel's API has no delete, so Insight resolves the name or id against the daemon's run list first and then runs `simaai-sentinel runs delete <id>` on the board with the id the daemon reported; the path value itself is never passed to the board. A run Sentinel does not list returns `404 not_found` without running anything. A run that is still recording returns `409 trace_conflict`; stop the trace first. When `generation` is sent and the selected board has changed since, `409 stale_snapshot` is returned and nothing is deleted. A CLI failure keeps its output in `detail`: `tool_missing` when `simaai-sentinel` is not on the board, `sentinel_denied` when the board user may not remove the file, and `sentinel_failed` otherwise, including when the run is still listed afterwards.

📄️Compare saved runs

Compares two or more runs on the same elapsed timeline and returns run metadata, per-run statistics and deltas against the first run, which is the baseline. `raw=1` adds timestamped samples and is much larger. Fewer than two runs, or more than eight, return `400 invalid_request` without touching the board; an unknown run returns `404 not_found`.