Operating Best Practices

Field-tested guidance for keeping a Xisom box healthy in production. Each section links to the reference page with the full detail. Sections marked Placeholder are being finalized with field data — treat them as direction, not settled numbers.

The operating loop

flowchart LR
  P["Prepare<br/>modelctl"] --> D["Deploy<br/>upload + create flow + enable"]
  D --> M["Monitor<br/>latency · throughput · EP"]
  M -->|"drift / new data"| P
  M -->|"version up"| D

Model preparation

Validate against the box’s ONNX Runtime version before shipping — pin --target-ort so a too-new opset fails on the workstation, not on the floor.
Quantize deliberately. Dynamic INT8 makes models smaller and usually faster, at some accuracy cost — re-validate the quantized model and check prediction quality before it goes live.
Pin reproducible bundles (--timestamp) so the artifact on the box matches what you reviewed. See Preparing Models.

Datasource sizing

Match window size × feature count between model and datasource — the platform checks the shape when a flow is created and again when it is enabled, and rejects a mismatch. Record these two numbers with every model.
Prefer OPC-UA subscriptions over polling where the server supports them.
Use CSV replay to validate a model against recorded data before connecting a live plant source. See Input Datasources.

Monitoring & alerting

Watch p95/p99 latency, not just the average — tail latency is where edge inference degrades first.
An execution-provider fallback to CPU is a regression signal — if a box that should run on CUDA (CPU as fallback) reports CPU, investigate before throughput drops.
Live metrics retain for 1 day — export anything you need for longer-term trending. See Monitoring.

Deployment & versioning

Check the release version after every update — Settings → About shows the release installed on the box. See Versions & Updates.
Stage on the Docker lab before promoting a model or release to a production box. See Docker Lab.

Database compaction

The database deletes old rows on a schedule, but a database created by an older release keeps the freed space instead of returning it to the disk. Run compact-db.sh once on such a box, and again whenever the Database row on the Storage Health card stays large.

Plan a short maintenance window. The script stops the whole stack and starts it again when it is done.
It measures the database first. If the database already returns space on its own and there is little to gain, it stops without changing anything.
Otherwise it asks for confirmation and takes a database snapshot before it compacts.

See Disk fills / database grows unbounded for the steps.

Security

Apply least privilege — reserve admin accounts for actions that need them (output test writes, key management); operators sign in as operators.
Review the audit trail periodically — it records who accessed the system and when.
Terminate TLS at the reverse proxy in front of the dashboard and API, and use authenticated brokers / secured OPC-UA policies for datasources. See Security.

Next steps

Preparing Models Convert, validate, quantize, package.

Monitoring Read the inference dashboard.

Security Access control, hardening, audit.