xtr_stopwatch ¶
Times what code does: named events, grouped by category, nested in sections.
A profile wants to know where a request spent its time — which listener,
which query, which template — and on one axis, so the pieces can be drawn
as a timeline. :class:~xtr_stopwatch.stopwatch.Stopwatch records exactly
that: each event is a name, a category and the periods it ran for, and every
event of a section is measured from the section's own origin.
What is timed belongs to the calling context, so concurrent requests served by one process each see only their own events.
SECTION_CATEGORY
module-attribute
¶
The category of the event spanning a child section.
SECTION_CHILD_EVENT
module-attribute
¶
The event spanning a child section, kept in the section that opened it.
SECTION_EVENT
module-attribute
¶
The event spanning a section, started in it as it opens and stopped as it closes.
EventNotStartedError ¶
Bases: StopwatchError
An event was stopped, or lapped, while it was not running.
A stop with no start to pair it with has no period to close, so it is refused rather than recorded as nothing.
Attributes:
-
name(str) –The event that was not running.
Record the event that was not running.
NoStartedSectionError ¶
Bases: StopwatchError
A section was stopped while none was open.
The root section is always open and is never stopped, so stopping with only the root in place has nothing to stop.
Attributes:
-
section_id(str) –The id the section would have been stored under.
Record the id the stop was asked for.
StopwatchError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything timing can go wrong with; catch a subclass to handle one cause. Every subclass carries what went wrong as typed attributes and composes its own message from them.
UnknownEventError ¶
Bases: StopwatchError, LookupError
An event was asked for that the current section never started.
Also a :class:LookupError, as a missing key is.
Attributes:
-
name(str) –The event that is not known.
Record the event that is not known.
UnknownSectionError ¶
Bases: StopwatchError, LookupError
A section was reopened by an id the current section holds no child under.
Reopening adds periods to a section that was stopped earlier, and that is only meaningful at the level it lives at: a section started elsewhere is refused rather than silently begun afresh here.
Also a :class:LookupError, as a missing key is.
Attributes:
-
section_id(str) –The id that is not a child of the current section.
Record the id that was asked for.
Section ¶
Holds the events timed while it was the current section.
A section measures every event it holds from one origin — the instant it was opened — so its events line up on one timeline. The root section has no origin of its own; each of its events is measured from the instant it first started.
Make a section measuring its events from origin.
Parameters:
-
origin(float | None, default:None) –The instant the section began, in milliseconds since the epoch;
Nonefor the root. -
clock(ClockInterface | None, default:None) –What time is read from.
Noneuses a :class:~xtr_clock.MonotonicClock.
children
property
¶
The sections opened inside this one, in the order they opened.
open ¶
Return the child named section_id, opening a new one when there is none.
start_event ¶
Start name here, making the event the first time it is started.
stop_event ¶
Stop name here.
Raises:
-
EventNotStartedError–When this section never started
name, or it is not running.
lap_event ¶
get_event ¶
get_events ¶
Return every event of this section by name, in the order each first started.
Stopwatch ¶
Times what code does, as named events grouped into sections.
stopwatch = Stopwatch()
stopwatch.open_section()
stopwatch.start("load", "orm")
...
stopwatch.stop("load")
stopwatch.stop_section("request-42")
stopwatch.get_section_events("request-42")["load"].get_duration()
An event is started and stopped by name in the current section; a
section opened inside another nests under it, and is stored under the id
it is stopped with. Opening a section starts :data:SECTION_EVENT in it
and :data:SECTION_CHILD_EVENT in its parent, both stopped as it closes,
so a section's own duration is one of its events.
What is timed belongs to the calling context: every concurrent unit of
work — every request a server handles at once — sees only its own
sections. :meth:reset starts the calling context afresh, which is how a
unit of work begins with nothing timed.
Make a stopwatch reading clock.
Parameters:
-
clock(ClockInterface | None, default:None) –What time is read from.
Noneuses a :class:~xtr_clock.MonotonicClock, because a duration must not follow a wall-clock correction.
detached_variable
instance-attribute
¶
The variable a new connection must start without, and the value it starts from.
A server may start a connection from a copy of another's context taken mid-request; whoever builds the stopwatch for a container registers this, so that request's timing never reaches the new one.
open_section ¶
Open a section inside the current one, or reopen the child named section_id.
Raises:
-
UnknownSectionError–When
section_idis given and the current section holds no child under it.
stop_section ¶
Close the current section, storing it under section_id.
Raises:
-
NoStartedSectionError–When only the root section is open.
start ¶
Start the event name in the current section and return it.
Keep the returned event to stop it: it stays the same object even if the context is reset while it runs.
stop ¶
Stop the event name in the current section and return it.
Raises:
-
EventNotStartedError–When
nameis not running there.
lap ¶
Stop the event name and start it again at once.
Raises:
-
EventNotStartedError–When
nameis not running in the current section.
is_started ¶
Tell whether the event name is running in the current section.
has_open_section ¶
Tell whether the calling context has a section open, without starting anything.
A unit of work timing itself opens a section; code that times what it does on a shared stopwatch asks this first, so a context nobody times in — a worker's own loop, a long command — never accumulates events.
get_event ¶
Return the event name of the current section.
Raises:
-
UnknownEventError–When the current section never started
name.
get_section_events ¶
Return the events of the section stored as section_id; empty when there is none.
get_sections ¶
Return every stopped section by id, the root included.
reset ¶
Forget everything the calling context timed, and start it afresh.
Other contexts are left as they are, and an event already handed out stays the object it was, so stopping it still closes its period.
StopwatchEvent ¶
StopwatchEvent(origin: float, category: str | None = None, name: str | None = None, clock: ClockInterface | None = None)
Times one named thing, however many times it runs.
Each :meth:start opens a period and the matching :meth:stop closes
it, so a listener called three times is one event with three periods
rather than three events. Starts nest: a start while already running opens
a second period, and stops close them last-opened first.
Every reading is in milliseconds from :attr:origin — the instant the
event's section began — so the events of a section share one axis and can
be drawn on one timeline.
Make an event measured from origin.
Parameters:
-
origin(float) –The instant readings are measured from, in milliseconds since the epoch.
-
category(str | None, default:None) –What kind of work this is, grouping events on a timeline;
"default"when not given. -
name(str | None, default:None) –What the event is called, for errors and for plain data.
-
clock(ClockInterface | None, default:None) –What time is read from.
Noneuses a :class:~xtr_clock.MonotonicClock, because a duration must not follow a wall-clock correction.
origin
property
¶
The instant readings are measured from, in milliseconds since the epoch.
stop ¶
lap ¶
Close the open period and open the next one at the same instant.
Raises:
-
EventNotStartedError–When no period is open.
get_periods ¶
Return every closed period, in the order they closed.
get_start_time ¶
Return when the event first began, in milliseconds from the origin.
The first closed period's start, or the first open one's when none has
closed yet; 0.0 for an event that never started.
get_end_time ¶
Return when the last closed period ended, in milliseconds from the origin.
get_duration ¶
Return the time spent in every period, open ones up to now, in milliseconds.
to_dict ¶
Return the event as plain data, readable once serialised to JSON.
StopwatchPeriod ¶
One start and the stop that closed it.
Both ends are milliseconds from the origin of the event the period belongs to, so periods of one event — and of every event of one section — line up on the same axis.
Record a period from start to end, both in milliseconds from the origin.