stormlog.infer.populations

Who a case’s numbers are about, and the interval its rates divide by.

A case’s measured requests are its cohort. Their statuses split the cohort into explicit populations (offered, dropped, sent, unreachable, delivery_unknown, rejected, accepted, successful, failed, timed out, cancelled), each counted once, and the cohort is checked for the records a run should have: unique identities, every scheduled arrival exactly once, and times inside the case’s window. A duplicated record cannot stand in for a missing one.

Rates divide by an interval named by what it is. An open loop’s rate counts the requests scheduled in its window, however late they finished, per second of the schedule’s own window, which ends where the schedule does and not where sending happened to end. A closed loop’s rate counts every measured request per second from the start of the phase to the end of its drain.

Functions

case_populations(records, *[, segments, ...])

Each measured case's cohort, populations and intervals.

count_population(requests, *[, scheduled, ...])

Count requests by status; the identities in Population always hold.

goodput(requests, spec, interval, *[, ...])

Judge a case's offered requests against spec; rates per interval.

rate(count, interval)

count per second of interval; None when it has no length.

Classes

CaseIntervals(rate[, scheduled_window, ...])

The interval rates divide by, and the others a reader may want.

CasePopulation(case_id, population, ...)

MeasuredInterval(kind, started_at_ns, ...)

A span of client wall time, named by kind and by what it counts.

Population(offered, scheduled, dropped, ...)

A cohort's requests by what happened to them.

Segment(name, start_offset_ns, end_offset_ns)

A slice of a case, by offsets from its measured phase's start.

SegmentPopulation(population, interval, ...)

The requests that belong to one segment, and the segment's interval.
class stormlog.infer.populations.CaseIntervals(rate, scheduled_window=None, dispatch_window=None, drain=None, measured_span=None, configured_rate_per_second=None, realized_offered_rate_per_second=None, rate_reason=None)[source]

Bases: object

The interval rates divide by, and the others a reader may want.

rate is the scheduled window for an open loop, the measured span for a closed loop, and the span of the recorded requests for an artifact older than phase windows. It is None for an open loop whose schedule has no known end, and for a phase that never recorded its window, or recorded one without bounds. rate_reason says why it is not the first choice when it is not.

Parameters:
rate: MeasuredInterval | None
scheduled_window: MeasuredInterval | None = None
dispatch_window: MeasuredInterval | None = None
drain: MeasuredInterval | None = None
measured_span: MeasuredInterval | None = None
configured_rate_per_second: float | None = None
realized_offered_rate_per_second: float | None = None
rate_reason: str | None = None
to_record()[source]
Return type:

dict[str, Any]

class stormlog.infer.populations.CasePopulation(case_id: 'str', population: 'Population', intervals: 'CaseIntervals', segments: 'Mapping[str, SegmentPopulation]' = <factory>)[source]

Bases: object

Parameters:
case_id: str
population: Population
intervals: CaseIntervals
segments: Mapping[str, SegmentPopulation]
class stormlog.infer.populations.MeasuredInterval(kind, started_at_ns, ended_at_ns, numerator_cohort)[source]

Bases: object

A span of client wall time, named by kind and by what it counts.

Parameters:

  • kind (Literal['scheduled_window', 'measured_span', 'dispatch_window', 'drain', 'request_span', 'segment'])

  • started_at_ns (int)

  • ended_at_ns (int)

  • numerator_cohort (Literal['arrival_cohort', 'all_measured', 'overlapping'])

kind: Literal['scheduled_window', 'measured_span', 'dispatch_window', 'drain', 'request_span', 'segment']
started_at_ns: int
ended_at_ns: int
numerator_cohort: Literal['arrival_cohort', 'all_measured', 'overlapping']
property seconds: float | None

Its length; None when it is empty, so nothing divides by zero.

to_record()[source]
Return type:

dict[str, Any]

class stormlog.infer.populations.Population(offered, scheduled, dropped, sent, unreachable, delivery_unknown, rejected, accepted, successful, failed, timed_out, cancelled, other=<factory>, server_admitted=None, server_evidence_coverage=None, cohort_valid=True, issues=())[source]

Bases: object

A cohort’s requests by what happened to them.

offered = dropped + sent; sent = unreachable + delivery_unknown + rejected + accepted; accepted = successful + failed + timed_out + cancelled + sum(other). accepted is the client’s view: nothing refused it. server_admitted counts requests the server confirmed it saw, through a joined span or execution record; it is None when the run has no such evidence at all.

Parameters:

  • offered (int)

  • scheduled (int | None)

  • dropped (int)

  • sent (int)

  • unreachable (int)

  • delivery_unknown (int)

  • rejected (int)

  • accepted (int)

  • successful (int)

  • failed (int)

  • timed_out (int)

  • cancelled (int)

  • other (Mapping[str, int])

  • server_admitted (int | None)

  • server_evidence_coverage (float | None)

  • cohort_valid (bool)

  • issues (tuple[str, ...])

offered: int
scheduled: int | None
dropped: int
sent: int
unreachable: int
delivery_unknown: int
rejected: int
accepted: int
successful: int
failed: int
timed_out: int
cancelled: int
other: Mapping[str, int]
server_admitted: int | None = None
server_evidence_coverage: float | None = None
cohort_valid: bool = True
issues: tuple[str, ...] = ()
property censored: int

Requests whose latency is known only to exceed what was observed.

to_record()[source]
Return type:

dict[str, Any]

class stormlog.infer.populations.Segment(name, start_offset_ns, end_offset_ns)[source]

Bases: object

A slice of a case, by offsets from its measured phase’s start.

Parameters:

  • name (str)

  • start_offset_ns (int)

  • end_offset_ns (int)

name: str
start_offset_ns: int
end_offset_ns: int
class stormlog.infer.populations.SegmentPopulation(population, interval, membership)[source]

Bases: object

The requests that belong to one segment, and the segment’s interval.

Parameters:
population: Population
interval: MeasuredInterval
membership: Literal['arrival', 'overlap']
stormlog.infer.populations.case_populations(records, *, segments=(), membership='arrival', server_admitted_ids=None)[source]

Each measured case’s cohort, populations and intervals.

server_admitted_ids are the x_request_id values the server confirmed it saw. Segment membership is arrival (by intended arrival, falling back to the send time) or overlap (any request whose span meets the segment).

Parameters:

  • records (Sequence[Mapping[str, Any]])

  • segments (Sequence[Segment])

  • membership (Literal['arrival', 'overlap'])

  • server_admitted_ids (Collection[str] | None)

Return type:

dict[str, CasePopulation]

stormlog.infer.populations.count_population(requests, *, scheduled=None, server_admitted_ids=None, issues=(), cohort_valid=True)[source]

Count requests by status; the identities in Population always hold.

Parameters:

  • requests (Iterable[Mapping[str, Any]])

  • scheduled (int | None)

  • server_admitted_ids (Collection[str] | None)

  • issues (Sequence[str])

  • cohort_valid (bool)

Return type:

Population

stormlog.infer.populations.goodput(requests, spec, interval, *, spans=None, slo_source='flags', cohort=None)[source]

Judge a case’s offered requests against spec; rates per interval.

requests are the case’s measured requests, dropped ones included; spans are their joined vLLM spans, for server criteria; cohort is their population, whose validity the evaluation carries.

Parameters:
Return type:

SloEvaluation

stormlog.infer.populations.rate(count, interval)[source]

count per second of interval; None when it has no length.

Parameters:
Return type:

float | None