sqlrows

type Collector struct {
	// contains filtered or unexported fields
}

type DBClock struct {
	BaselineBefore time.Time `json:"baseline_before"`
	BaselineAfter  time.Time `json:"baseline_after"`
	FinalBefore    time.Time `json:"final_before"`
	FinalAfter     time.Time `json:"final_after"`
	// Monotonic reports BaselineBefore <= BaselineAfter <= FinalBefore <=
	// FinalAfter, all four readings present. When false, consumers must not
	// judge freshness at all — neither fresh nor stale.
	Monotonic bool `json:"monotonic"`
	// Anomaly is the stable code of the first violated condition, empty when
	// Monotonic is true.
	Anomaly string `json:"anomaly,omitempty"`
}

type DigestRow struct {
	CountStar            uint64 `json:"count_star"`
	TimerWait            uint64 `json:"timer_wait"`
	RowsExamined         uint64 `json:"rows_examined"`
	RowsSent             uint64 `json:"rows_sent"`
	RowsAffected         uint64 `json:"rows_affected"`
	CreatedTmpDiskTables uint64 `json:"created_tmp_disk_tables"`
	SortMergePasses      uint64 `json:"sort_merge_passes"`
	NoIndexUsed          uint64 `json:"no_index_used"`
	NoGoodIndexUsed      uint64 `json:"no_good_index_used"`
}

type DigestStat struct {
	Digest string `json:"digest"`
	// Query is the truncated DIGEST_TEXT, or MissingQueryText.
	Query string        `json:"query"`
	Kind  StatementKind `json:"kind"`
	Count uint64        `json:"count"`
	// TimerWaitPicos is the raw SUM_TIMER_WAIT delta; TotalTime is the same
	// value as a duration, kept because picoseconds are unreadable and the
	// raw number is needed to reproduce the ordering.
	TimerWaitPicos uint64        `json:"timer_wait_picos"`
	TotalTime      time.Duration `json:"total_time"`
	RowsExamined   uint64        `json:"rows_examined"`
	RowsSent       uint64        `json:"rows_sent"`
	RowsAffected   uint64        `json:"rows_affected"`
	// ExaminedPerSent is only defined for SELECT statements that returned at
	// least one row. HasRatio distinguishes "not applicable" from "zero":
	// treating a SELECT that sent nothing as a ratio of RowsExamined would
	// invent the worst possible score for a query that simply found nothing.
	ExaminedPerSent float64 `json:"examined_per_sent,omitempty"`
	HasRatio        bool    `json:"has_ratio"`
	// Index and sort quality signals, all interval values.
	NoIndexUsed          uint64 `json:"no_index_used"`
	NoGoodIndexUsed      uint64 `json:"no_good_index_used"`
	CreatedTmpDiskTables uint64 `json:"created_tmp_disk_tables"`
	SortMergePasses      uint64 `json:"sort_merge_passes"`
}

type HealthNote struct {
	Key     string `json:"key"`
	Message string `json:"message"`
}

type InspectFunc func(ctx context.Context, id string, purpose sqlstats.Purpose, fn func(context.Context, sqlstats.Querier) error) error

type OverflowStat struct {
	Detected  bool   `json:"detected"`
	CountStar uint64 `json:"count_star,omitempty"`
	// ReportedBy names the target carrying this server's overflow when this
	// target is not the one reporting it.
	ReportedBy string `json:"reported_by,omitempty"`
}

type Sample struct {
	Targets map[string]*TargetSample `json:"targets"`
}

type Section struct {
	// Targets is ordered by TargetID so two snapshots diff cleanly.
	Targets []TargetSection `json:"targets"`
	// Health carries this section's degradation notes, already grouped by
	// key and reason.
	Health []HealthNote `json:"health,omitempty"`
	// Validity is the verdict this section contributes to the run. sqlrows is
	// an optional collector, so it degrades a run to partial and never
	// invalidates it: a database without performance_schema is a normal
	// deployment, not a broken measurement.
	Validity runctl.Validity `json:"validity"`
	// Limit is the number of rows a target may show, recorded so a reader can
	// tell a truncated table from a short one.
	Limit int `json:"limit"`
}

type StatementKind string

type TargetSample struct {
	TargetID string `json:"target_id"`
	// Schema is the value bound to WHERE SCHEMA_NAME = ?. It is recorded so a
	// snapshot shows which database the numbers describe.
	Schema string `json:"schema"`
	// ServerUUID and UptimeSec detect a server that restarted between the two
	// boundaries, which would make the counters incomparable.
	ServerUUID string `json:"server_uuid,omitempty"`
	UptimeSec  int64  `json:"uptime_sec,omitempty"`
	// UTCBefore and UTCAfter bracket the digest read with the database's own
	// clock. Plan 09 compares query-sample timestamps against this interval,
	// so both edges are needed, not just one.
	UTCBefore time.Time `json:"utc_before"`
	UTCAfter  time.Time `json:"utc_after"`
	// Digests holds the rows whose SCHEMA_NAME matched the bound schema, keyed
	// by hex DIGEST.
	Digests map[string]DigestRow `json:"digests,omitempty"`
	// Overflow is the row where SCHEMA_NAME and DIGEST are *both* NULL: the
	// bucket MySQL aggregates statements into once the digest table is full.
	// A NULL schema alone does not mean overflow — statements from any
	// connection without a default database, this collector's included, also
	// have a NULL schema but a real digest.
	Overflow    DigestRow `json:"overflow"`
	HasOverflow bool      `json:"has_overflow,omitempty"`
	// Texts maps DIGEST to its truncated DIGEST_TEXT. Only the closing
	// boundary fills it, and only for the digests that lead the interval.
	Texts map[string]string `json:"texts,omitempty"`
	// Captured reports that Digests is a real reading. When false, Code and
	// Err say why and the target contributes no numbers.
	Captured bool   `json:"captured"`
	Code     string `json:"code,omitempty"`
	Err      string `json:"err,omitempty"`
}

type TargetSection struct {
	TargetID string `json:"target_id"`
	Schema   string `json:"schema,omitempty"`
	// Usable reports that Digests holds real interval values. When false the
	// target contributes no numbers, and consumers that enrich rows — plan
	// 09's EXPLAIN capture in particular — must skip this target entirely.
	Usable bool `json:"usable"`
	// Code and Reason explain an unusable target: probe-skip, no-schema,
	// budget-exhausted, query-error, unpaired-boundary, db-restart or
	// counter-reset.
	Code   string `json:"code,omitempty"`
	Reason string `json:"reason,omitempty"`
	// Digests holds the leading rows of the interval, ordered by total time.
	Digests []DigestStat `json:"digests,omitempty"`
	// Shown, Total and Dropped make truncation explicit. Total counts every
	// digest that ran during the interval, not every digest in the table.
	Shown   int `json:"shown"`
	Total   int `json:"total"`
	Dropped int `json:"dropped"`
	// Overflow describes the digest table's overflow row for this target.
	Overflow OverflowStat `json:"overflow"`
	// DBClock carries the database-side interval. Consumers must not judge
	// freshness when Monotonic is false.
	DBClock DBClock `json:"db_clock"`
}