exlab_wizard.logging.context#

Per-task structured-tag context vars for the logging system. Backend Spec §16.2.3.

The logger format string includes structured tags ([host:..], [equip:..], [proj:..], [kind:..], [run:..]) whose values are pulled from contextvars.ContextVar snapshots at log-emit time. contextvars are async-safe: a set_run_context call inside one asyncio task does not bleed into another concurrent task. This is what lets the orchestrator mode (§13) run multiple equipment sessions concurrently and still emit cleanly tagged log lines.

The tags are deliberately scoped to the creation lifecycle (host / equipment / project / run-kind / run-id). Component tags ([component:tray], [plugin:..]) are emitted directly via logger.info("...", extra={...}) calls in the relevant component code; they do not flow through this module.

Functions

clear_run_context()

Reset every context var to None.

get_run_context()

Return a snapshot of the active context as a plain dict.

set_run_context(*[, host, equipment_id, ...])

Push the supplied context vars on entry and reset them on exit.
exlab_wizard.logging.context.clear_run_context()[source]#

Reset every context var to None.

Provided for test fixtures that want to ensure a clean slate between cases. Production code should rely on set_run_context()’s exit semantics; calling clear_run_context mid-run would mask a nested with block’s prior values, which is almost always wrong.

Return type:

None

exlab_wizard.logging.context.get_run_context()[source]#

Return a snapshot of the active context as a plain dict.

Used by the formatter to render structured tags. Keys match the kwarg names of set_run_context(); values are None when the var is unset.

Return type:

dict[str, str | None]

exlab_wizard.logging.context.set_run_context(*, host=None, equipment_id=None, project_short_id=None, run_kind=None, run_id=None)[source]#

Push the supplied context vars on entry and reset them on exit.

Vars whose argument is None (the default) are left unchanged. This lets a caller incrementally widen the context (e.g. set host and equipment_id in an outer with block, then add run_id in a nested inner block) without destroying the outer values.

The context manager is implemented via contextvars.Token so nested entries are restored to their prior value on exit (not to None). Each token corresponds to exactly one ContextVar.set call.

The caller is responsible for ensuring values are non-empty strings; this helper does no validation. Passing an empty string "" is treated as a real value (it suppresses the default-None suppression in the formatter), which is almost certainly a caller bug – so callers should pass None explicitly when they mean “don’t touch this var”.

Parameters:
Return type:

Iterator[None]