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()
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.
excBaseException — The exception that ended the attempt.
Classes
Attempt
Attemptclass 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.
ledgerLedger — The ledger to write through.runRun | None — The run this attempt belongs to, orNonefor no recording at all.taskstr — The registered task name.parent_keystr | None — The calling task’s key, orNoneat the top level.
emit()
emit()def emit(self, kind: EventKind, detail: str = "") -> None: ...Record an event and flush everything queued behind it.
kindEventKind — What happened.detailstr — Free text; onlyfaileduses it.
failed()
failed()def failed(self, exc: BaseException) -> None: ...Record that this attempt raised.
excBaseException — The exception that ended it.
started()
started()def started(self) -> None: ...Record that this attempt began, without writing yet.
Event
Eventclass 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.
seqint — Monotonic database sequence number used for ordering.run_idstr — The run this belongs to.attemptstr — UUID4 hex identifying the task attempt.taskstr — The registered task name.keystr | None — The envelope key, once it is known;Noneonstarted.parent_keystr | None — Calling task’s key, orNoneat the top level.kindEventKind — What happened.atstr — ISO-8601 UTC timestamp.detailstr — Empty except onfailed, where it carries the exception type, its message, and a bounded tail of its traceback.
EventKind
EventKindclass EventKind(enum.Enum):
def __init__(self): ...Task-attempt event kinds.
Ledger
Ledgerclass Ledger(builtins.object):
def __init__(self, records: RecordStore, enabled: bool = True) -> None: ...Write run records and events, warning once on storage failure.
recordsRecordStore — The record store owning therunsandeventstables.enabledbool — Whether to record runs and events.
enabled bool
enabled boolReturn whether this ledger writes anything.
append()
append()def append(self, rows: list[EventRow]) -> None: ...Write a batch of events in one transaction.
rowslist[EventRow] — The events to write, in order.
attempt()
attempt()def attempt(
self, run: Run | None, task: str, parent_key: str | None
) -> Attempt: ...Open one attempt at one task within a run.
runRun | None — The run it belongs to;None(no run, or a broken ledger) yields an attempt that writes nothing.taskstr — The registered task name.parent_keystr | None — The key of the task whose body made this call, orNoneat the top level.
end_run()
end_run()def end_run(self, run: Run | None, outcome: str) -> None: ...Close a run with its outcome.
runRun | None — Run to close, orNoneto do nothing.outcomestr —"succeeded"or"failed".
start_run()
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.
namestr | None — An explicit name, overriding the derived one.
subscribe()
subscribe()def subscribe(self, callback: Callable[[Event], None]) -> None: ...Register a callback for each written event.
callbackCallable[[Event], None] — Called with each written event. Its own failures are swallowed like any other ledger failure.
unsubscribe()
unsubscribe()def unsubscribe(self, callback: Callable[[Event], None]) -> None: ...Remove a previously registered callback.
callbackCallable[[Event], None] — The callback to remove; unknown ones are ignored.
Run
Runclass 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.
run_idstr — A uuid4 hex string, unique per run.namestr — Name derived fromrun_id.started_atstr — ISO-8601 UTC time the run opened.ended_atstr | None — ISO-8601 UTC end time, orNoneif the run has not closed.outcomestr | None —"succeeded","failed", orNonewhile unfinished.hostnamestr — The host that opened the run.