Copyright © 2026 Saccadic LLC · Patent pending.

Browse chapters
  1. Release NotesChanges by version
  2. Chapter 1What IRIS Is and Is Not
  3. Chapter 2The IRIS Data Model
  4. Chapter 3How IRIS Measures
  5. Chapter 4Safe Interpretation and the First 15 Minutes
  6. Chapter 5Dashboard Overview
  7. Chapter 6Installation
  8. Chapter 7Configuration
  9. Chapter 8Build the Model Spec and Probe Set
  10. Chapter 9Minimal Tracker Integration
  11. Chapter 10Launch the Bench and Verify Capture
  12. Chapter 11Runtime Control, Signals, Metrics, and Logs
  13. Chapter 12Integration Patterns by Model Family
  14. Chapter 13Distributed Training
  15. Chapter 14Artifacts, Reports, Export, and Security
  16. Chapter 15Troubleshooting
  17. Chapter 16Whole Model and Layer Structure
  18. Chapter 17Domain Training and Affinity
  19. Chapter 18Attention-Head Diagnostics
  20. Chapter 19MoE Expert and Router Diagnostics
  21. Chapter 20Facets and Emergent Pathways
  22. Chapter 21Gradient Residuals, Stability, Curvature, and Update Efficiency
  23. Chapter 22Adaptive Cadence and Event Detection
  24. Chapter 23CLI Reference
  25. Chapter 24Configuration-Key Reference
  26. Chapter 25API Reference
  27. Chapter 26File and Schema Reference
  28. Chapter 27Glossary and Concept Index
  29. Chapter 28The Flow Map
  30. Appendix ADiagnostic Availability Matrix
  31. Appendix BLLM Prompt Library
On this page

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.