Skip to content

Commit 03b2c36

Browse files
AsieduDevelopmentHubAsieduDevelopmentHub
authored
update: engine_setup.md
1 parent 75b2583 commit 03b2c36

1 file changed

Lines changed: 272 additions & 39 deletions

File tree

‎docs/setup/engine_setup.md‎

Lines changed: 272 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,325 @@
11
# SentraCore Engine Setup
22

3-
The SentraCore engine is a headless Python application that collects system telemetry, processes it through the intelligence pipeline, and serves the results via a local REST API and WebSocket.
3+
The SentraCore engine is a headless Python-based monitoring and intelligence service responsible for:
4+
5+
- collecting system telemetry
6+
- analyzing behavioral trends
7+
- detecting anomalies
8+
- generating predictive insights
9+
- serving live data through local REST and WebSocket interfaces
10+
11+
The engine operates independently from the dashboard and can run in the background as a standalone local service.
12+
13+
---
14+
15+
# Supported Platforms
16+
17+
| Platform | Support Status |
18+
|---|---|
19+
| Windows | Primary Support |
20+
| Linux | Supported |
21+
| macOS | Supported |
22+
23+
Some telemetry metrics may vary slightly across operating systems depending on the system APIs exposed through `psutil`.
424

525
---
626

7-
## Prerequisites
27+
# Prerequisites
28+
29+
## General Requirements
830

931
- Python 3.11 or higher
10-
- Windows OS (some `psutil` telemetry counters are Windows-specific)
1132
- Git
1233

34+
Verify Python installation:
35+
36+
```bash
37+
python --version
38+
```
39+
40+
or on Linux/macOS:
41+
42+
```bash
43+
python3 --version
44+
```
45+
46+
---
47+
48+
# Repository Structure
49+
50+
```text
51+
engine/
52+
├── alerts/ # Alerting and RCA integration
53+
├── api/ # REST API and WebSocket server
54+
├── baseline/ # Adaptive baseline learning
55+
├── buffer/ # Time-series buffers
56+
├── collector/ # Telemetry collection
57+
├── events/ # Event tracking and logging
58+
├── intelligence/ # Trend, anomaly, prediction engines
59+
├── normalization/ # Signal normalization
60+
├── process/ # Process intelligence tracking
61+
├── safeguard/ # Optional safeguard controls
62+
├── stress/ # Stress and stability calculation
63+
└── main.py # Engine entry point
64+
```
65+
1366
---
1467

15-
## Installation
68+
# Installation
1669

17-
From the repository root:
70+
All commands should be executed from the repository root.
1871

19-
### 1. Create a Virtual Environment
72+
---
73+
74+
## 1. Create a Virtual Environment
75+
76+
### Windows
2077

2178
```powershell
2279
python -m venv .venv
2380
```
2481

25-
### 2. Activate the Virtual Environment
82+
### Linux / macOS
83+
84+
```bash
85+
python3 -m venv .venv
86+
```
87+
88+
---
89+
90+
## 2. Activate the Virtual Environment
91+
92+
### Windows
2693

2794
```powershell
2895
.venv\Scripts\Activate
2996
```
3097

31-
### 3. Install Dependencies
98+
### Linux / macOS
3299

33-
```powershell
100+
```bash
101+
source .venv/bin/activate
102+
```
103+
104+
---
105+
106+
## 3. Install Dependencies
107+
108+
```bash
34109
pip install -r requirements.txt
35110
```
36111

37112
---
38113

39-
## Running the Engine
114+
# Running the Engine
115+
116+
The engine must be started as a module from the repository root so internal package imports resolve correctly.
40117

41-
The engine must be run as a module from the root directory so that internal package imports resolve correctly:
118+
### Windows
42119

43120
```powershell
44121
.venv\Scripts\python -m engine.main
45122
```
46123

47-
On startup, the engine will:
48-
- Start the `uvicorn` API server in a background thread.
49-
- Begin the telemetry collection loop.
50-
- Log periodic status updates to the console.
124+
### Linux / macOS
125+
126+
```bash
127+
python -m engine.main
128+
```
129+
130+
---
131+
132+
# Engine Startup Behavior
133+
134+
When launched, the engine will:
135+
136+
- initialize telemetry collectors
137+
- load user preferences and baseline data
138+
- start the FastAPI server
139+
- initialize the WebSocket broadcaster
140+
- begin the monitoring and intelligence pipeline
141+
- start event and alert tracking
142+
143+
The engine runs continuously until stopped manually.
144+
145+
---
146+
147+
# Available Interfaces
148+
149+
Once running, the engine exposes the following local interfaces.
51150

52-
**Available endpoints once running:**
151+
## REST API
53152

54153
| Endpoint | Description |
55154
|---|---|
56-
| `GET http://localhost:8740/api/v1/status` | Full current system state snapshot |
57-
| `GET http://localhost:8740/api/v1/processes` | Top processes by sustained impact |
58-
| `GET http://localhost:8740/api/v1/events` | Recent system events |
59-
| `GET http://localhost:8740/api/v1/alerts` | Alert history with Root Cause Analysis |
60-
| `GET http://localhost:8740/api/v1/preferences` | User alert thresholds and safeguard process list |
61-
| `PUT http://localhost:8740/api/v1/preferences` | Update preferences (JSON body; persisted under datastore) |
155+
| `GET /api/v1/status` | Current system state snapshot |
156+
| `GET /api/v1/processes` | Top ranked processes by impact |
157+
| `GET /api/v1/events` | Recent system events |
158+
| `GET /api/v1/alerts` | Alert history and RCA summaries |
159+
| `GET /api/v1/preferences` | Current user preferences |
160+
| `PUT /api/v1/preferences` | Update persisted preferences |
62161

63-
**Dynamic HTTP port:** if `8740` is already in use, the engine binds the next free port up to `65535` and writes `engine_runtime.json` in the datastore (`http_host`, `http_port`). The Flutter dashboard discovers the active port via that file, a cached last-known port, and a short local scan starting at `8740`.
64-
| `WS ws://localhost:8740/ws/live` | Real-time state broadcast (WebSocket) |
162+
Default local address:
163+
164+
```text
165+
http://localhost:8740/api/v1/
166+
```
65167

66168
---
67169

68-
## Configuration
170+
## WebSocket
171+
172+
| Endpoint | Description |
173+
|---|---|
174+
| `WS /ws/live` | Real-time system state stream |
69175

70-
Key constants are configurable in `engine/config.py`:
176+
Default endpoint:
71177

72-
| Constant | Default | Description |
73-
|---|---|---|
74-
| `COLLECTION_INTERVAL_SEC` | `2` | How frequently telemetry is sampled |
75-
| User preferences (`user_preferences.json`) | defaults in `engine/user_preferences.py` | Per-resource CPU / memory / disk pressure thresholds (0–100) and optional safeguard process list |
76-
| `ALERT_CONSECUTIVE_COUNT` | `3` | Consecutive high readings before alerting |
77-
| `ALERT_COOLDOWN_SEC` | `60.0` | Minimum time between consecutive alerts |
78-
| `BASELINE_MIN_SAMPLES` | `30` | Samples required before baseline is considered ready |
178+
```text
179+
ws://localhost:8740/ws/live
180+
```
79181

80182
---
81183

82-
## Running Tests
184+
# Dynamic Port Allocation
83185

84-
```powershell
85-
.venv\Scripts\python -m pytest tests/ -v
186+
If port `8740` is already in use, the engine automatically searches for the next available port.
187+
188+
The active runtime port is written to:
189+
190+
```text
191+
engine_runtime.json
86192
```
87193

88-
## Running the Linter
194+
This allows the dashboard to discover the currently active engine instance automatically.
89195

90-
```powershell
91-
.venv\Scripts\ruff check engine/ tests/ --select=E9,F63,F7,F82
196+
---
197+
198+
# Configuration
199+
200+
Core engine configuration is located in:
201+
202+
```text
203+
engine/config.py
204+
```
205+
206+
---
207+
208+
## Important Configuration Values
209+
210+
| Setting | Description |
211+
|---|---|
212+
| `COLLECTION_INTERVAL_SEC` | Telemetry collection interval |
213+
| `ALERT_CONSECUTIVE_COUNT` | Required sustained readings before alerting |
214+
| `ALERT_COOLDOWN_SEC` | Minimum time between alerts |
215+
| `BASELINE_MIN_SAMPLES` | Samples required before baseline activation |
216+
217+
---
218+
219+
## User Preferences
220+
221+
User-adjustable preferences are stored separately and persisted locally.
222+
223+
Examples include:
224+
- CPU pressure thresholds
225+
- memory thresholds
226+
- disk pressure thresholds
227+
- anomaly sensitivity
228+
- safeguard process configuration
229+
230+
---
231+
232+
# Testing
233+
234+
Run the Python test suite:
235+
236+
```bash
237+
pytest tests/ -v
238+
```
239+
240+
---
241+
242+
# Static Analysis
243+
244+
SentraCore uses `ruff` for linting and static analysis.
245+
246+
Run:
247+
248+
```bash
249+
ruff check engine/ tests/ --select=E9,F63,F7,F82
92250
```
251+
252+
---
253+
254+
# Logging
255+
256+
The engine supports both console and packaged execution modes.
257+
258+
In packaged (`--noconsole`) environments:
259+
- logging automatically falls back to file-based output
260+
- runtime issues are recorded for diagnostics
261+
262+
---
263+
264+
# Development Notes
265+
266+
- The engine is designed to operate independently from the Flutter dashboard.
267+
- Dashboard communication occurs entirely through local APIs and WebSockets.
268+
- Most engine components are modular and can be extended independently.
269+
270+
---
271+
272+
# Platform Notes
273+
274+
## Windows
275+
Windows currently provides the most complete telemetry support and packaging integration.
276+
277+
---
278+
279+
## Linux
280+
Linux supports core monitoring and dashboard communication features. Some advanced process metrics may vary by distribution and permissions.
281+
282+
---
283+
284+
## macOS
285+
macOS supports the core monitoring pipeline, though certain low-level telemetry values may differ from Windows behavior due to operating system limitations.
286+
287+
---
288+
289+
# Troubleshooting
290+
291+
## Port Already in Use
292+
293+
If the engine cannot bind to port `8740`:
294+
- it will automatically search for another free port
295+
- verify firewall settings if dashboard discovery fails
296+
297+
---
298+
299+
## Missing Dependencies
300+
301+
If startup fails due to missing packages:
302+
303+
```bash
304+
pip install -r requirements.txt
305+
```
306+
307+
Ensure the active virtual environment is enabled before installation.
308+
309+
---
310+
311+
## API Not Reachable
312+
313+
Verify:
314+
- the engine process is running
315+
- no firewall is blocking local connections
316+
- the runtime port matches the dashboard connection target
317+
318+
---
319+
320+
# Stopping the Engine
321+
322+
To stop the engine:
323+
324+
- Press `Ctrl + C` in terminal mode
325+
- or terminate the packaged process from the operating system

0 commit comments

Comments
 (0)