Documentation
¶
Overview ¶
Package lessonstats gathers lesson delivery statistics as typed data for `seamark lessons --stats` and the console. It only reads: it never appends a firing record, because viewing a lesson is not delivery.
Delivered means emitted through a recorded surface (the hook, change_set or check), not read, followed or effective, because the log records only the emission. The counts cover the retained firing log, and each Gather reads a new snapshot. The pin count of the lessons by source counts every entry of the pin file, also the pins that an apply wrote from proposals, so it does not mean hand-written.
Index ¶
Constants ¶
const DeliveryDays = 30
DeliveryDays is the number of days that Snapshot.Days covers. The console shows windows of 7, 14 and 30 days, so 30 covers them all.
const TopRegionCount = 5
TopRegionCount is the number of regions that LessonCounts.TopRegions keeps. The console shows one bar for each of them.
Variables ¶
var ErrNoIndex = errors.New("no readable index")
ErrNoIndex reports that a section needs the index and none is readable. The firing totals do not need the index, so they still render.
Functions ¶
func NewestFirst ¶
NewestFirst returns a copy of the proposals in descending ID order, the order of the store. `seamark lessons --stats` printed and measured the applied proposals in this order before it used Gather. It still prints in this order. Gather also measures in this order. The measurement stops at the first failed commit count and names that pin, so the command error names the same pin.
Types ¶
type DayCount ¶
type DayCount struct {
// Day is the local midnight that starts the day.
Day time.Time
// Delivered counts the delivered records on every surface.
Delivered int
// Hook counts the delivered edit-hook records, a subset of
// Delivered.
Hook int
}
DayCount holds the delivered records of one local day.
func DailyCounts ¶
DailyCounts counts the delivered records of each local day for the DeliveryDays days that end on the day of now. It applies the rule of reviews.Summarize: a record is delivered when it has no delivery status or when its status is "injected". A suppressed repeat is not a delivery. undated counts delivered records whose time does not parse.
type LessonCounts ¶
type LessonCounts struct {
// Mined is the number of active mined lessons.
Mined int
// Inactive is the number of mined lessons below the threshold or
// muted. They stay in the index but no surface shows them.
Inactive int
// Pins is the number of pin rules in lessons.yaml.
Pins int
// TopRegions holds the regions with the most active mined lessons,
// at most TopRegionCount, most lessons first. Ties break on the
// region, so a refresh keeps the order.
TopRegions []RegionCount
}
LessonCounts is the active lesson set by source. A mined lesson is active when it clears the surfacing bar: the recurrence threshold and the mute rules of lessons.yaml. Pins always surface.
func (LessonCounts) Active ¶
func (c LessonCounts) Active() int
Active returns the number of lessons that the surfaces can show.
type RegionCount ¶
RegionCount is the number of active mined lessons in one region. The region is the file or directory that the lesson names, unchanged.
type Snapshot ¶
type Snapshot struct {
// LogPath is the firing log path.
LogPath string
// LogExists is false when no firing log exists yet.
LogExists bool
// Records is the number of parsed firing records.
Records int
// Skipped is the number of log lines that the reader could not
// parse. A log of only corrupt lines is then not shown as empty.
Skipped int
// LogErr holds the log read failure; Summary is then empty.
LogErr error
// Summary is the existing delivery aggregation. Ranked has a stable
// order: ties break on region, then symptom.
Summary reviews.Summary
// Eligible is true when NeverFired covers the mined lessons. It is
// false without an index or with an unreadable lessons config.
Eligible bool
// EligibleErr explains why NeverFired is incomplete.
EligibleErr error
// Applied holds the applied proposals, in ascending ID order.
Applied []model.Proposal
// Readings holds the derived recurrence readings by proposal ID.
Readings map[int64]outcome.Reading
// OutcomeErr holds the reading failure.
OutcomeErr error
// Lessons counts the active lessons by source. It is nil when
// LessonsErr is set, and in a snapshot that no Gather filled.
Lessons *LessonCounts
// LessonsErr explains why Lessons is nil: no index, an unreadable
// lessons config, or a failed read of the mined lessons.
LessonsErr error
// Days holds the delivered records of each local day, oldest first.
// It covers DeliveryDays days and ends on the day of the read. It is
// nil when the log was not read.
Days []DayCount
// Undated counts the delivered records whose time does not parse.
// Days cannot place them, so the view says that they are missing.
Undated int
// contains filtered or unexported fields
}
Snapshot is one read of the delivery statistics. Each source keeps its own error, so a failed source never renders as zero.
func Gather ¶
Gather reads the statistics. st may be nil when no index exists; the firing totals still render and the eligibility sections say why they are incomplete.
func (Snapshot) Err ¶
Err returns the first failed source, or nil when every read worked. The order is the mined lessons, the applied proposals, the lessons config, the firing log, and the outcome measurement. `seamark lessons --stats` read its sources in this order before it used Gather, so its error text stays the same. Without an index, Err never returns nil, because the outcomes need the proposal ledger.
Source Files