Sensors and Dashboard

Introduction

This document describes the sensor dashboard, sensor list, sensor detail, metrics, install command, and virtual sensor workflows.

---

Main Files

File	Responsibility
modules/sensors/pages/SensorDashboardPage.tsx	Dashboard landing page with sensor counts, alert summary, heartbeat activity
modules/sensors/pages/SensorListPage.tsx	Sensor list route, permissions, data refresh flags, and dialog orchestration
modules/sensors/partials/SensorListTable.tsx	Sensor table, heartbeat/health badges, metrics action, row actions
modules/sensors/dialogs/CreateSensorDialog.tsx	Create/register sensor dialog
modules/sensors/dialogs/EditSensorDialog.tsx	Edit sensor dialog
modules/sensors/pages/SensorDetailPage.tsx	Sensor detail page, install command, interface and virtual sensor management
modules/sensors/partials/SensorSetupCard.tsx	Virtual sensor card and activate/deactivate/delete controls
modules/sensors/dialogs/AddSetupDialog.tsx	Create virtual sensor from two available interfaces
modules/sensors/dialogs/SensorMetricsDialog.tsx	Sensor metrics visualization dialog
hooks/useApi.ts	useSensors() and permission hooks
lib/api.ts	sensor, virtualSensor, and legacy sensorSetup endpoint groups

---

Dashboard Page

• Route: /dashboard
• Component: ChartSensor

Dashboard behavior:

1. Context Initialization: Reads organizationId from auth cookies.
2. Fetch Counts: Calls api.sensor.getCounts(organizationId).
3. Fetch Analytics: Calls api.opensearch.getDashboardSummary() for the last 24 hours.
4. Fetch Heartbeats: Calls api.sensor.getLatestHeartbeats() for recent sensor activity.
5. Render Metrics: Displays active/inactive counts, total uptime estimate, alert statistics, and heartbeat table.

The component supports both activeSensors/inactiveSensors/totalSensors and active/inactive/total count shapes.

---

Sensor List Page

• Route: /dashboard/all-sensor
• Component: AllSensor

Sensor list behavior:

1. Data Loading: Loads sensors with useSensors([deletionFlag, createFlag, editFlag]).
2. Permission Check: Loads current user permissions with useUserPermissions().
3. Action Visibility: Shows create, edit, and delete actions based on sensor permission slugs.
4. State Polling: Polls latest heartbeat state every 60 seconds.
5. Health Polling: Polls latest metrics every 60 seconds for health status.
6. Form Handling: Opens create/edit dialogs inside shared Dialog components.
7. Metrics View: Opens sensor metrics in SensorMetricsDialog.
8. Navigation: Navigates to sensor detail through /dashboard/sensor/:sensorId.

Health badge logic is based on latest CPU and memory metrics:

Condition	Status
Max CPU/memory >= 90	Critical
Max CPU/memory >= 70	Warning
Below 70	Healthy

Online state is based on latest heartbeat data. If the backend does not provide isOnline, the frontend treats heartbeats younger than 5 minutes as online.

---

Sensor Detail Page

• Route: /dashboard/sensor/:sensorId
• Component: SensorDetail

Detail behavior:

1. Context Initialization: Reads sensorId from route params.
2. Data Loading: Calls api.sensor.get(sensorId).
3. Render Details: Displays status, enrollment, host, OS, architecture, agent version, interface, and virtual sensor information.
4. Install Token: Creates an install token through api.sensor.createInstallToken(sensorId).
5. Clipboard Action: Copies the returned installCommand to clipboard.
6. Data Refresh: Allows refresh without leaving the page.
7. Virtual Sensors: Manages virtual sensors through AddSetupDialog and SensorSetupCard.

The page computes available interfaces by filtering sensor.interfaces where:

• isEligible is true.
• assignedVirtualSensorId is empty.

A new virtual sensor can be created only when at least two eligible interfaces are available.

---

Virtual Sensor Workflow

Virtual sensors were previously named "sensor setup" in the UI and API layer. The code keeps both endpoint groups:

• api.virtualSensor
• api.sensorSetup as a legacy alias

Current backend paths use: /sensors/:sensorId/virtual-sensors

Supported operations:

Operation	API Call
List	api.sensorSetup.getAll(sensorId)
Create	api.sensorSetup.create(sensorId, data)
Update	api.sensorSetup.update(sensorId, setupId, data)
Delete	api.sensorSetup.delete(sensorId, setupId)
Activate	api.sensorSetup.activate(sensorId, setupId)
Deactivate	api.sensorSetup.deactivate(sensorId, setupId)

SensorSetupCard polls every 5 seconds while a virtual sensor is in activating state. It stops polling when the backend returns active or failed.

---

Virtual Sensor Form Rules

AddSetupDialog enforces client-side validation:

• Interface 1 is required.
• Interface 2 is required.
• Interface 1 and Interface 2 must be different.
• Name is optional.
• Home network CIDR is optional.

The backend remains responsible for final validation and deployment behavior.

---

Permissions

Sensor actions use these slugs from src/lib/constants.ts:

Action	Permission Slug
Create sensor	create-sensor
Edit sensor	update-sensor
Delete sensor	delete-sensor
Read sensor	read-sensor

UI permission checks hide actions. They do not replace backend authorization.

---

Failure Modes

Scenario	Frontend Behavior
Sensor list load fails	Hook records an error and logs to console
Heartbeat polling fails	Error is logged; existing list still renders
Metrics polling fails for one sensor	That sensor is skipped silently
Sensor detail load fails	Toast error and loading ends
Install command creation fails	Toast error
Virtual sensor activation fails	Card shows failed state when backend returns failure
Virtual sensor delete fails	Toast explains deactivation may be required first