Operate HEAT Capture
Run a session
-
Sign in. A session cannot start without a signed-in user whose account details are complete.
-
Enable the modules you need and check they are running. Modules are started at the session boundary, so enable them before starting the session.
-
Start the session.
-
Watch the delivery counters during the exercise. Packets received should track packets sent, and parked packets should stay at zero on a healthy link.
-
Stop the session. Stopping drains what is queued before finishing, so allow it a few seconds.
Session states
| State | Meaning |
|---|---|
| No session | Nothing is being recorded. |
| Active | A session exists on the platform and modules are capturing. |
| Paused | New packets are rejected before storage. Modules and plugins may keep producing data, but data received during the pause is neither recorded nor delivered. |
| Stopped | The session is closed on the platform and the local store has been drained and compacted. |
Pause stops HEAT Capture from accepting new data. Data produced during the pause is discarded, not buffered for resume. Resume accepts newly arriving packets again.
What stops a session from starting
| Condition | What you see |
|---|---|
| A session is already active | The request is refused as a conflict |
Free disk below MinimumFreeSpaceBytes | The request is refused and reports the capacity snapshot, including the path, bytes available and the minimum |
| Signed-in user incomplete | The log records that a re-login is required, naming the missing fields |
| No user signed in | The request is refused as unauthorised |
The log line for the disk case is:
Cannot start capture session: {StoragePath} has {AvailableBytes} bytes free, below the {MinimumBytes} byte minimum.What happens when a session stops
- New packets are no longer accepted.
- The delivery loop is given up to 15 seconds to finish in-flight work.
- Queued disk writes are drained, with up to 30 seconds allowed.
- The session end time is written to the session’s metadata file.
- A final delivery pass runs, with up to 30 seconds allowed.
- The session directory is compacted.
Anything still undelivered stays on disk and is replayed on a later launch.
Disk safety
Capture is disk-first: every packet is written locally before delivery is attempted.
| Threshold | Default | Behaviour |
|---|---|---|
| Warning free space | 20 GiB | The interface warns that space is low |
| Minimum free space | 5 GiB | Capture will not start, and a running capture is stopped |
When a running capture is stopped for space, the log records:
Stopping capture because the HARDStore drive is below its minimum free-space threshold.The internal append queue is bounded. If it fills, capture stops rather than discarding packets:
Storage append queue rejected a packet because it is full or stopping; stopping capture to prevent further data loss.Network loss
Losing the platform connection does not stop the session.
-
Packets continue to be written to the local store.
-
Delivery retries with exponential backoff up to
MaxBundleRetriesattempts. -
After that, the affected packets are parked for the next launch and delivery moves on:
Parked {Count} packet(s) for node {NodeId} after {Retries} failed delivery attempts; will retry next launch.
Parked packets remain on disk marked as pending. Nothing is lost by an outage that ends before the disk fills.
Recovering undelivered sessions
On launch the application scans the capture store for session directories that still contain pending data and replays them, subject to two conditions:
- A user must be signed in with a valid token. The scan runs once per application run, after sign-in.
- The stored session’s platform URL must match the currently configured
HEAT_URL. Sessions recorded against a different platform are never replayed automatically.
An administrator can inspect and act on the queue:
| Action | Endpoint |
|---|---|
| List sessions with pending data | GET /api/storage/pending-sessions |
| Retry one session now | POST /api/storage/pending-sessions/{id}/retry |
| Discard one session | DELETE /api/storage/pending-sessions/{id} |
These require a signed-in user with the Admin role. Discarding is permanent and is recorded in the log with the user who did it.
If the application still believes a session is active after an unclean shutdown, clear the stuck
state with POST /api/session/reset-session. That clears local state only; a session left open on
the platform by a crash is not closed automatically.
Disk housekeeping
Session directories are not removed on a schedule. A completed, fully delivered session is compacted, but nothing purges old sessions by age or by total size.
Plan for this: check pending sessions periodically, and delete delivered session directories from the capture store as part of routine maintenance. Confirm that a session holds no pending data before deleting it.
Logs
| Item | Value |
|---|---|
| Location | C:\ProgramData\VRAI\HEATCapture\Logs\log.txt |
| Level | Information |
| Rolling | Daily, and at 5 MiB per file |
| Retention | 5 files, 30 MiB total, oldest trimmed at startup |
The desktop application’s log level is fixed at Information and cannot be raised from
configuration. Recent entries are also available in the interface, and through
GET /api/ui/log, which accepts take, level, since and afterSequence.
When reporting a problem to VRAI, attach log.txt and the output of
GET /api/operations/summary, which carries the storage, delivery, module and process state in one
document.