# Monitors
URL: /monitors

Collect background measurements during OpenHTF phase execution with monitors. Poll instrument values at fixed intervals while your test logic runs.

Sample measurements in the background while a phase runs.

Some tests need to monitor a value continuously — current draw during a burn-in, temperature during a stress test, voltage during a load cycle. OpenHTF monitors run a sampling function in a background thread at a fixed interval, recording each sample as a dimensioned measurement with a millisecond timestamp.

Use the `@monitors.monitors()` decorator to attach a background monitor to a phase. The monitor function runs repeatedly in a background thread while the decorated phase executes.

The test record will contain a `current_draw` measurement with timestamped samples at \~500ms intervals.

Name of the output measurement. Created automatically as a dimensioned measurement with a millisecond time axis.

Function that returns the value to record. Called repeatedly by the background thread. Can accept `test` as an argument and use plugs.

Unit of measure for the recorded values (e.g. `units.AMPERE`, `units.VOLT`).

Milliseconds between samples. Default is `1000` (1 second). Set to `0` for continuous sampling with no delay.

The monitor function can use plugs, just like a regular phase. Plugs declared on the monitor function are automatically passed through.

A monitor's measurement is dimensioned, so scalar validators do not apply directly. Use `dimension_pivot_validate` from the validators reference to check every sample, or read the samples back in a later phase with `test.get_measurement('current_draw').value.to_dataframe()`.

When the decorated phase starts, a daemon thread launches the monitor function.

The monitor function is called at each `poll_interval_ms` interval.

Each returned value is stored with a millisecond timestamp relative to the phase start.

When the phase completes (pass or fail), the monitor thread stops.

The resulting dimensioned measurement appears in the test record with `MILLISECOND` as the time dimension.

<Card title="Measurements" href="/measurements" description="Multi-dimensional measurements, which monitors produce." />

<Card title="Plugs" href="/plugs" description="Monitors can use plugs to read instruments." />

<Card title="Validators reference" href="/reference/validators" description="dimension_pivot_validate for time series." />