aeat.core.observability._recorder module

The single record_event() emit primitive used by every call site.

Routes structured aeat.core.observability._models.RunEvent records through the standard logging machinery so any handler attached to the root logger — notably the per-run aeat.core.observability._sink.JsonlRunSink — picks them up automatically while a aeat.core.observability.run_context() is active.

record_event(kind, *, payload, module=None)

Record a single RunEvent against the active run context.

Context propagation note: the active run_id is carried via contextvars.ContextVar. These propagate across asyncio.create_task() and asyncio.run() automatically (PEP 567), but NOT across plain threading.Thread targets nor asyncio.to_thread() / loop.run_in_executor workers unless the caller wraps the target with contextvars.copy_context(). A call to record_event() from a detached thread therefore raises aeat.core.observability.RunContextMissingError. Callers that need the event recorded in such a thread must either re-enter aeat.core.observability.run_context() inside the worker or copy the context explicitly.

Parameters:

• kind (RunEventKind) – The event kind.

• payload (RunEventPayload) – A RunEventPayload with exactly one variant set.

• module (str | None) – Optional explicit module string; defaults to the caller’s __name__ resolved by _caller_module().

Return type:

RunEvent

Returns:

The constructed RunEvent (also forwarded to the JSONL sink via the run_event logging extra).

Raises:

RunContextMissingError – If no run context is active on the current contextvar.