Chapter 11 — Runtime Control, Signals, Metrics, and Logs
Controlling IrisTracker During Training
The Bench tracker controls and the run's iris.cmd file
operate the same supported control surface. Commands are read when the
training loop polls should_extract() or calls extract(). A command
cannot take effect while training is not reaching those calls.
| Command | User-facing effect |
|---|---|
frame |
Request an extraction at the next poll. |
interval <v> |
Set a fixed sampling interval in steps, or a percentage of declared total steps. |
cutback <fast> <slow> |
Set the fast and steady-state bounds for adaptive capture. |
sensitivity <S> |
Adjust how readily adaptive capture becomes denser; higher means more frames. |
total <N> |
Update the total-step value used to interpret percentage settings. |
mode auto |
Let IRIS™ choose capture coverage according to available resources. |
mode standard, mode lean, mode skeleton, mode skip |
Request a coverage mode; a manual request cannot force capture beyond what resources permit. |
dryrun on, dryrun off |
Switch the supported wiring/credit-reachability check mode on or off. Dryrun records no science and consumes no credits. |
For example, from the run directory:
echo "interval 500" > iris.cmd
This is an example interval, not a recommended interval for every model.
The file accepts one command per line and is consumed by the tracker.
Coordinate multiple writers so a shell edit does not replace a command
someone else just staged. Inspect iris.log to confirm what was applied.
Reported loss and accuracy
Trainer-derived metrics must be reported by the trainer. report_loss
provides a scalar loss; report_metrics accepts declared training and
held-out values, including per-domain values. Probe-derived metrics are
computed on the fixed inspection probes and are a separate source.
For the structured metrics interface, loss is token-weighted mean cross-entropy over non-padding targets and accuracy is top-1 next-token accuracy on the same token set, expressed from 0 to 1. Use a User Defined Signal with an explicit definition for a different task metric rather than silently changing the meaning of a built-in field.
User Defined Signals and Functions
tracker.report_signal(
0, float(learning_rate), label="Learning rate",
unit="", description="Learning rate used for this optimizer step"
)
Keep an index's meaning stable. Signals are scalar measurements reported by your code. A derived function combines channels already recorded in the run; it is not another observation of the model. Label its expression and inputs, preserve gaps, and check definitions before comparing runs.
Read the logs and coverage
iris.log records tracker-side state, frame outcomes, and applied commands.
iris-bench.log records the dashboard process. A missing channel can mean
not applicable, not captured, pending, or shed. Consult the stated reason
before treating an empty plot as a measurement or changing your training.
Older Apple silicon spectra
Runs recorded on Apple silicon with a tracker predating the 20 October 2026 fix, and more than one probe batch per frame, have untrustworthy spectra. This includes affected v0.95-Beta runs. The Bench, printed report, and AI export mark affected figures. Record the run again with the current tracker; reopening an old bundle does not repair its captured spectra.
