Health and status

FreeDR reports its own health through the local API, the console Health page, the Windows tray icon and the freedrctl command line. This page explains where health is shown and what each state and counter means.

Pre-release

FreeDR is pre-release. The tray icon and its notices (ADR-0067) are implemented but their native Windows qualification is still pending.

Health endpoints

All endpoints are served by freedr-api on http://127.0.0.1:29173 (default port) and require a signed-in session (browser cookie or freedrctl bearer session). Requests without a session get 401; requests whose Host/Origin is not exactly 127.0.0.1:<port> get 400 invalid request.

Endpoint	What it returns
GET /live	{"status":"live"} when the API answers.
GET /ready	200 with status: "ready" once the API component has started; 503 with status: "starting" otherwise. Includes version and collector snapshots.
GET /version	status: "ok", ready, version and collector snapshots.
GET /status	Overall status plus every component snapshot, including the evidence database writer (db-worker). status is "degraded" while any component is degraded, else "ok".
GET /api/v1/detections/health	Detection engine health (see Detection health).
GET /api/v1/storage/diagnostics	Evidence store sizes, free disk space and control-database integrity (see Storage diagnostics).
GET /api/v1/events/flow?range=1h\|24h&source=<source>	Exact retained-event counts per bucket (5-minute buckets for 1h, 1-hour buckets for 24h), optionally for one source.

/status shape

{
  "status": "ok | degraded",
  "ready": true,
  "version": "<agent version>",
  "collectors": [
    {
      "collector_id": "unified-etw",
      "state": "starting | running | stopped | failed",
      "degraded": false,
      "counters": { "...": 0 },
      "gauges":   { "...": 0 }
    }
  ]
}

Counters and gauges are numbers only. They never contain event data, paths, process identities or Registry values.

Components reported in /status

collector_id	Console label	Becomes degraded when
unified-etw	Windows ETW	The ETW runtime reports degradation or failure, evidence persistence fails, or the telemetry filter policy is degraded (telemetry_filter_policy_degraded).
windows-event-log	Windows Event Log	A configured channel is closed (channels not present on this host do not count), or committing events is failing.
usn	NTFS change journal	The collector failed, or any of read_failures, decode_failures, checkpoint_failures, integration_failures, faulted volumes or failed workers is non-zero. Close-only filtering is normal and does not degrade.
artifact-inventory	File artifact inventory	capacity_drops, commit_drops, write_failures or lookup_failures grow. Per-file acquisition errors are counted (by cause, acquisition_error_<operation>:<code>) but do not degrade.
db-worker	Evidence database writer	rejected, command_queue_full, acknowledgement_unavailable, invalid or write_errors grow.
evidence-cold-export	Cold storage export	A cold-export attempt fails.
tray	Tray	The last tray launch failed (launch_failed).
telemetry-sources	Telemetry sources	A change made in Settings > Sources has no recorded outcome (changes_outcome_unknown), for example because the service stopped mid-change.
provider-settings	Provider settings	Stored enrichment/AI provider settings were invalid or an older version and were reset to defaults (settings_reset_invalid).
machine_state	Machine_state	Never degraded; access_lists_restored counts FreeDR folders whose access list was repaired at service start.
agent-shutdown	Agent shutdown	Reported during shutdown; failed if a component did not stop cleanly.

Degraded semantics

FreeDR separates current health from lifetime diagnostics (ADR-0019, ADR-0080):

• degraded is the component's current fault signal. Lifetime counters only ever grow and are never reset; a non-zero historical counter does not by itself mean a current problem.
• Components with lifetime fault counters (db-worker, artifact-inventory) are faulty only while those counters increase, not forever after the first fault.
• 30-minute hold: after the last fault, a component stays reported degraded for 30 minutes (DEGRADED_HOLD), then clears on its own if no new fault occurs.
• Degraded episodes: every component snapshot carries:
  • degraded_episodes (counter): number of separate degraded periods since the agent started. A fault after the previous hold expired starts a new episode.
  • degraded_last_fault_unix_s (gauge): Unix time of the last fault.
• Overall /status is degraded while any component is degraded.
• Critical conditions (coverage loss, admission/ring loss, worker failure, persistence failure, stalled progress) degrade immediately. Isolated malformed or unsupported records do not; per ADR-0019 a sustained rate of 1,000 malformed decode outcomes in any 30-second window does.

All counters reset when the service restarts (they are "since agent start").

Useful counters

Component	Counters worth watching
unified-etw	events_lost, buffers_lost, unexpected_exits, restart_failures, start_failures, worker_panics, unknown_records, shutdown_drops
windows-event-log	received, committed, inserted, duplicates, subscription_failures, decode_failures, commit_failures, coverage_gaps, bookmark_resets, own_events_excluded; gauges configured_channels, closed_channels, unavailable_channels, powershell_script_block_logging (1 enabled, 0 off)
usn	reads, retained_records, filtered_close_only, journal_resets, coverage_gaps, read_failures, decode_failures, checkpoint_failures, path_unresolved_dropped
artifact-inventory	queued, acquired, committed, capacity_drops, acquisition_errors, commit_drops, write_failures, lookup_failures, access_denied, sharing_violation, not_found
db-worker	submitted, inserted, rejected, invalid, write_errors, batches_flushed; gauge queue_depth
evidence-cold-export	attempts, successes, failures; gauges hot_retention_seconds, next_due_at_us, last_success_at_us, last_failure_at_us
tray	launched, launch_failed, notices_sent, notices_without_tray, health_notices_sent

Detection health

GET /api/v1/detections/health returns:

Field	Meaning
rules	Installed rules (built-in plus custom).
successful_runs, failed_runs, skipped_runs	Rule run totals.
last_completed_at_us	Time of the last completed run.
degraded	Detection engine is currently degraded (startup failure, rule/evaluation error, or control-database persistence problem).
last_runtime_error	Short, sanitized reason (for example sqlite busy or locked, sqlite integrity check failed).
late_runs	Evaluations that overran their deadline and will retry the same window.
lagging_rules	Rules whose current window is still waiting for a late result.
sqlite_health	Control-database integrity check: state (unknown, healthy, degraded), last_checked_at_us, truncated, numeric SQLite codes. The check runs about every 5 minutes.
case_automation	Automatic case assignment: processed count, backlog, last error.

A transient SQLite persistence error clears automatically after a later successful write or a clean integrity check; other rule errors stay visible.

Storage diagnostics

GET /api/v1/storage/diagnostics returns evidence_schema_version, typed_rows, hot_bytes, hot_wal_bytes, cold_bytes, cold_files, disk_free_bytes, control_integrity_messages, control_integrity_truncated, control_foreign_key_violations and control_evidence_table_count.

disk_free_bytes (ADR-0041) is a point-in-time reading of the bytes available on the volume holding the hot evidence database. It is null if the probe fails. It is not a quota or forecast and does not cover cold files stored on another volume.

Health in the console

Health page

Open Health in the sidebar (or http://127.0.0.1:29173/?view=health). It reads /status, /api/v1/detections/health and /api/v1/storage/diagnostics.

• Summary cards: Collecting (telemetry sources and how many are degraded), Storing (hot/cold size, last cold export; Needs attention on writer/export degradation or integrity problems), Detecting (runs and failures), Agent (ready state and version).
• Problems panel: a list of items needing attention: degraded or failed components, detection engine errors, failed rule runs, storage integrity problems and any counter whose name contains drop, loss or lost with a non-zero value. Shows No problems detected when everything is healthy.
• Recent log flow: exact retained-event bars for the last hour or 24 hours, for all sources or one (Process ETW, Registry ETW, File ETW, NTFS journal, Artifact inventory, Windows Event Log / Sysmon).
• Evidence collection loss: artifact-inventory Queue capacity, Acquisition and Commit drop counters (cumulative since agent start, with the change since your last refresh), plus any other source reporting dropped or lost events.
• Collectors & writer: one card per component with its state, a degraded marker and all counters and gauges. The Windows Event Log card shows whether PowerShell script-block logging is enabled.
• Detection engine: rule execution, case automation and the control database check.
• Storage: usage, cold export schedule and results, integrity details. Calculate retained date span scans hot and cold evidence on demand.
• Export diagnostics downloads the last loaded snapshot as freedr-health.json.

Elsewhere in the console

• The top bar connection pill shows Ready, Degraded or Unavailable.
• Overview shows a Collection health card and a Collection & detection health strip (agent ready, number of degraded components, components reporting).
• Alert rules shows a one-line detection engine status above the rule list.
• Settings > Collection lists each component with its state; Settings > About & status shows agent version, ready state, component count and degraded components.
• Settings > Appearance > Auto-refresh can refresh Overview and Health every minute.

Tray icon and health notices

The service keeps freedr-tray.exe running in the signed-in console user's session. It needs no autostart entry and has no API access of its own.

Icon state (highest priority first):

State	Tooltip
Host isolated	FreeDR · Host isolated
Isolation outcome unclear	FreeDR · Host may be isolated – check console
Unresolved Medium, High or Critical alerts	FreeDR · Unresolved alerts
A component is degraded	FreeDR · Protection degraded
OK	FreeDR · No unresolved alerts

Low and Informational alerts never change the icon.

Health notices (balloon toasts) are sent only on transitions:

Title	When
FreeDR · Protection degraded	A component other than the tray became degraded or failed.
FreeDR · Protection recovered	All components report healthy again.
FreeDR · Event Log channel closed	An Event Log channel stopped delivering events (shown instead of the generic degraded notice).
FreeDR · Host isolated / FreeDR · Isolation released	Host isolation changed.

Rules: the service checks every 10 seconds; each kind is shown at most once per 10 minutes; a newly started tray announces a state that is already bad. Selecting a health notice opens the Health page (after sign-in if needed). Health notices are not controlled by the alert-notification preference.

The tray menu has Open console and Exit; left-click also opens the console. If the tray exits unexpectedly the service restarts it (5 seconds, doubling up to 5 minutes). Choosing Exit is respected until the console session changes or you sign in again.

Service stops and configuration tampering are not health notices; they surface as alerts (for example FreeDR service was stopped, recorded at the next start).

Alert notifications

Settings > Notifications controls Windows notifications for new alerts (ADR-0067):

• Off by default; minimum severity defaults to High (choices: Critical, High, Medium, Low). Informational alerts never notify.
• The notice shows only severity and rule name. Selecting it opens the alert, or its case if the alert is in one.
• At most one notice per 5 seconds; a burst collapses into FreeDR · N new alerts.
• Alerts from a muted rule are stored but not announced.
• If no tray is connected (nobody signed in at the console, or RDP only), the notice is counted in notices_without_tray and not shown.

freedrctl status commands

freedrctl asks for the FreeDR password once per command (or reads it from stdin with --password-stdin), uses a temporary session and signs out afterward. --port selects a non-default local port.

Command	Calls	Output
freedrctl status	GET /status	Overall status and all component snapshots (JSON).
freedrctl version	GET /version	Version, ready state and component snapshots (JSON).
freedrctl detection-health	GET /api/v1/detections/health	Detection engine health (JSON).
freedrctl alerts	GET /api/v1/detections/alerts	Alert list with default paging (JSON).
freedrctl rules	GET /api/v1/detections/rules	Installed rules (JSON).
freedrctl service status	Windows Service Control Manager	Stopped, StartPending, Running or StopPending.
freedrctl service start / stop / uninstall	Windows Service Control Manager	Requires the FreeDR password and Windows administrator rights.

freedrctl service install is not supported; install with FreeDR-Setup.exe or by running freedr-agent.exe.