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 9 — Minimal Tracker Integration

Inline tracker integration

Create the tracker once, poll its schedule after training steps, extract when requested, and flush before exiting. step should count optimizer steps. The following is the integration shape; the spec, model, and training loop are supplied by your application.

from iris.inline import IrisTracker

tracker = IrisTracker(
    output_dir="/path/to/models/my-run",
    spec_dict=my_spec,
    probes_path="my_model.probes.json",
)
tracker.set_optimizer(optimizer)

for step in range(n_steps):
    # Your existing forward, backward, and optimizer step.
    # Keep your model, objective, and training data unchanged.
    tracker.report_loss(loss, step=step)
    if tracker.should_extract(step):
        tracker.extract(model, step=step)

tracker.flush()

The optimizer in set_optimizer must be the one whose .step() actually runs. If your loop clears gradients before extraction, optimizer registration is needed for supported gradient-dependent readings; otherwise extract before zero_grad(). Read the recorded coverage and the log when gradient data is absent, including early or unscheduled frames.

Reporting outcomes

report_loss is optional: it supplies a trainer-derived loss curve. Use report_metrics for declared training/held-out loss and accuracy, and report_signal for your own scalar observables. These reported values remain distinct from IRIS™'s probe and internal measurements. See Chapter 25 for interfaces and metric definitions.

Preserve training behavior

The tracker is an observer. It does not write your parameters or gradients. Measurement calls can run model forwards and optional callbacks, so keep callbacks side-effect-free and give them a fixed evaluation batch rather than the training iterator. Custom hooks and model behavior still need review in your integration. Compare a short instrumented run against your baseline on the hardware and determinism settings you actually use.

Check the first capture

Before committing a long job, confirm that iris.log records successful frames and that the .iris bundle grows. Open the run in the Bench and check model identity, steps, domains, and intended channels. Training continuing normally is not evidence that capture succeeded.

Use should_extract(step) every optimizer step for live schedule controls. The legacy every_n_steps argument is ignored; use supported constructor settings and runtime controls. Re-extracting an already measured step does not create another frame.