Skip to main content

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.

📄️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.

📄️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.