oct.timing.ledger Namespace Reference

Classes
class	TimingSample

Functions
None	_failure ()
str|None	_token (object value)
None	_append (Path root, TimingSample sample)
list[dict]	read_records (Path root)
Iterator[TimingSample]	timed_stage (Path root, str stage, *, str kind="stage", str|None scope=None, int|None files=None, int|str outcome="ok")
str	command_stage (object ctx)

Detailed Description

Purpose
-------
Persist stage timings.

Responsibilities
----------------
- Keep local timing data bounded, private and advisory.

Diagnostics
-----------
Domain: GENERAL
Levels:
    L1 -- instrumentation failures
    L2 -- lifecycle
    L3 -- semantic details
    L4 -- deep tracing

Contracts
---------
- Timing instrumentation never changes the wrapped operation's outcome.
- Only the fixed timing schema is persisted; command arguments are never stored.

Dependencies
------------
- oc_diagnostics (structured timing diagnostics)
- oct (version and timing contracts)
- click (lazy; walks the registered command groups to name the stage)

Function Documentation

_append()

None oct.timing.ledger._append ( Path root, TimingSample sample )

protected

Serialize one bounded record under a nonblocking interprocess lock.

Definition at line 77 of file ledger.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_failure()

None oct.timing.ledger._failure ( )

protected

Report instrumentation failure without exposing paths or caller data.

Definition at line 64 of file ledger.py.

Here is the caller graph for this function:

_token()

str | None oct.timing.ledger._token ( object value )

protected

Accept short tokens only, never free text or paths.

Definition at line 73 of file ledger.py.

Here is the caller graph for this function:

command_stage()

str oct.timing.ledger.command_stage

(

object

ctx

)

Use registered command names only; never serialize arbitrary argv.

Definition at line 186 of file ledger.py.

read_records()

list[dict] oct.timing.ledger.read_records

(

Path

root

)

Read complete JSON records, ignoring damaged or incomplete lines.

Definition at line 120 of file ledger.py.

Here is the call graph for this function:

timed_stage()

Iterator[TimingSample] oct.timing.ledger.timed_stage	(	Path	root,
		str	stage,
		*	,
		str	kind = "stage",
		str | None	scope = None,
		int | None	files = None,
		int | str	outcome = "ok" )

Measure one operation and preserve all success and exception semantics.

Definition at line 143 of file ledger.py.

Here is the call graph for this function: