Mondaic

salvus.flow.acta.observability.ledger

salvus.flow.acta.observability.ledger salvus flow acta observability ledger

Run and task-attempt events stored in the record database.

Events are ordered by seq. Writes are best-effort and warn once on failure. The CANCELLED event kind is reserved and is not emitted.

Functions

failure_detail()

def failure_detail(exc: BaseException) -> str: ...

Render an exception as a failed event’s detail.

Include the exception type, message, and traceback tail up to DETAIL_LIMIT.

Parameters
  • exc BaseException — The exception that ended the attempt.
Returns str

Classes

Attempt

class Attempt(builtins.object):
    def __init__(
        self,
        ledger: Ledger,
        run: Run | None,
        task: str,
        parent_key: str | None,
    ) -> None: ...

Batch events for one task attempt.

Flush started with the next event. Write running before dispatch.

Parameters
  • ledger Ledger — The ledger to write through.
  • run Run | None — The run this attempt belongs to, or None for no recording at all.
  • task str — The registered task name.
  • parent_key str | None — The calling task’s key, or None at the top level.
Methods
emit()
def emit(self, kind: EventKind, detail: str = "") -> None: ...

Record an event and flush everything queued behind it.

Parameters
  • kind EventKind — What happened.
  • detail str — Free text; only failed uses it.
Returns None
failed()
def failed(self, exc: BaseException) -> None: ...

Record that this attempt raised.

Parameters
  • exc BaseException — The exception that ended it.
Returns None
started()
def started(self) -> None: ...

Record that this attempt began, without writing yet.

Returns None

Event

class Event(builtins.object):
    def __init__(
        self,
        seq: int,
        run_id: str,
        attempt: str,
        task: str,
        key: str | None,
        parent_key: str | None,
        kind: EventKind,
        at: str,
        detail: str,
    ) -> None: ...

An immutable task-attempt event.

Parameters
  • seq int — Monotonic database sequence number used for ordering.
  • run_id str — The run this belongs to.
  • attempt str — UUID4 hex identifying the task attempt.
  • task str — The registered task name.
  • key str | None — The envelope key, once it is known; None on started.
  • parent_key str | None — Calling task’s key, or None at the top level.
  • kind EventKind — What happened.
  • at str — ISO-8601 UTC timestamp.
  • detail str — Empty except on failed, where it carries the exception type, its message, and a bounded tail of its traceback.

EventKind

class EventKind(enum.Enum):
    def __init__(self): ...

Task-attempt event kinds.

Ledger

class Ledger(builtins.object):
    def __init__(self, records: RecordStore, enabled: bool = True) -> None: ...

Write run records and events, warning once on storage failure.

Parameters
  • records RecordStore — The record store owning the runs and events tables.
  • enabled bool — Whether to record runs and events.
Attributes
enabled bool

Return whether this ledger writes anything.

Methods
append()
def append(self, rows: list[EventRow]) -> None: ...

Write a batch of events in one transaction.

Parameters
  • rows list[EventRow] — The events to write, in order.
Returns None
attempt()
def attempt(
    self, run: Run | None, task: str, parent_key: str | None
) -> Attempt: ...

Open one attempt at one task within a run.

Parameters
  • run Run | None — The run it belongs to; None (no run, or a broken ledger) yields an attempt that writes nothing.
  • task str — The registered task name.
  • parent_key str | None — The key of the task whose body made this call, or None at the top level.
Returns Attempt
end_run()
def end_run(self, run: Run | None, outcome: str) -> None: ...

Close a run with its outcome.

Parameters
  • run Run | None — Run to close, or None to do nothing.
  • outcome str — "succeeded" or "failed".
Returns None
start_run()
def start_run(self, name: str | None = None) -> Run | None: ...

Open a run, or return None if the ledger is off or broken.

Parameters
  • name str | None — An explicit name, overriding the derived one.
Returns Run | None
subscribe()
def subscribe(self, callback: Callable[[Event], None]) -> None: ...

Register a callback for each written event.

Parameters
  • callback Callable[[Event], None] — Called with each written event. Its own failures are swallowed like any other ledger failure.
Returns None
unsubscribe()
def unsubscribe(self, callback: Callable[[Event], None]) -> None: ...

Remove a previously registered callback.

Parameters
  • callback Callable[[Event], None] — The callback to remove; unknown ones are ignored.
Returns None

Run

class Run(builtins.object):
    def __init__(
        self,
        run_id: str,
        name: str,
        started_at: str,
        ended_at: str | None,
        outcome: str | None,
        hostname: str,
    ) -> None: ...

One invocation, from the outermost session context to its close.

Parameters
  • run_id str — A uuid4 hex string, unique per run.
  • name str — Name derived from run_id.
  • started_at str — ISO-8601 UTC time the run opened.
  • ended_at str | None — ISO-8601 UTC end time, or None if the run has not closed.
  • outcome str | None — "succeeded", "failed", or None while unfinished.
  • hostname str — The host that opened the run.