Help us shape the future of Go! Take the 2026 Go Developer Survey

stats

package
v0.316.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 9 Imported by: 306

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BuiltinStats 

type BuiltinStats struct {
	Timings queryTimings  `json:"timings,omitempty"`
	Samples *querySamples `json:"samples,omitempty"`
}

BuiltinStats holds the statistics that Prometheus's core gathers.

func (*BuiltinStats) Builtin 

func (s *BuiltinStats) Builtin() BuiltinStats

type QuerySamples 

type QuerySamples struct {
	// PeakSamples represent the highest count of samples considered
	// while evaluating a query. It corresponds to the peak value of
	// currentSamples, which is in turn compared against the MaxSamples
	// configured in the engine.
	PeakSamples int

	// TotalSamples represents logical underlying sample consumption while
	// evaluating a query, using the existing histogram size weighting.
	// Subqueries contribute their underlying consumption, not their materialized
	// results. Overlapping evaluation windows may count the same samples repeatedly;
	// this is not a count of unique samples or physical storage reads.
	TotalSamples int64

	// TotalSamplesPerStep represents logical underlying sample consumption
	// per step while evaluating a query. Each step should be identical to the
	// TotalSamples when a step is run as an instant query, which means
	// we intentionally do not account for optimizations that happen inside the
	// range query engine that reduce the actual work that happens.
	// For range-vector functions, each step counts the full window at that step.
	TotalSamplesPerStep []int64

	// SamplesRead counts evaluator input, reusing reads across overlapping
	// range-vector windows. Subquery reads are attributed to consumed windows,
	// unless query-cost is enabled, which includes all evaluated child steps.
	// This is not a count of physical storage I/O.
	SamplesRead int64

	// SamplesReadPerStep is the number of samples read per step. For
	// range-vector functions, step 0 counts the full window and later
	// steps count only the points not already covered by the previous
	// step's window.
	SamplesReadPerStep []int64

	// TotalSeries is the number of series touched while evaluating a query.
	// It is computed as a per-selector SUM: the sum of len(series) across all
	// selectors expanded during evaluation. Series shared between selectors may
	// be counted more than once, so this value is an upper bound on the number
	// of distinct series touched.
	TotalSeries int64

	EnablePerStepStats bool
	StartTimestamp     int64
	Interval           int64
}

func NewChildWithStepTracking added in v0.313.0 

func NewChildWithStepTracking(start, end, interval int64) *QuerySamples

NewChildWithStepTracking creates a child QuerySamples with per-step tracking enabled and initializes its per-step arrays via InitStepTracking.

func NewQuerySamples 

func NewQuerySamples(enablePerStepStats bool) *QuerySamples

func (*QuerySamples) IncrementSamplesAtStep 

func (qs *QuerySamples) IncrementSamplesAtStep(i int, samples int64)

IncrementSamplesAtStep increments the total samples count. Use this if you know the step index.

func (*QuerySamples) IncrementSamplesAtTimestamp 

func (qs *QuerySamples) IncrementSamplesAtTimestamp(t, samples int64)

IncrementSamplesAtTimestamp increments the total samples count. Use this if you only have the corresponding step timestamp.

func (*QuerySamples) IncrementSamplesReadAtStep added in v0.313.0 

func (qs *QuerySamples) IncrementSamplesReadAtStep(i int, n int64)

IncrementSamplesReadAtStep increments the samples-read count. Use this when you know the step index.

func (*QuerySamples) IncrementSamplesReadAtTimestamp added in v0.313.0 

func (qs *QuerySamples) IncrementSamplesReadAtTimestamp(t, n int64)

IncrementSamplesReadAtTimestamp increments the samples-read count. Use this when you only have the step timestamp.

func (*QuerySamples) IncrementSeries 

func (qs *QuerySamples) IncrementSeries(n int64)

IncrementSeries increments the count of series touched while evaluating a query. The total is a per-selector SUM and is therefore an upper bound on the number of distinct series touched.

func (*QuerySamples) InitStepTracking 

func (qs *QuerySamples) InitStepTracking(start, end, interval int64)

func (*QuerySamples) MergeSamplesReadFromSubquery added in v0.313.0 

func (qs *QuerySamples) MergeSamplesReadFromSubquery(child *QuerySamples, c SubqueryConsumer)

MergeSamplesReadFromSubquery merges the child's SamplesRead into the parent. Each consumed child step is counted once, at the earliest parent step that consumes it. The child must be created with NewChildWithStepTracking.

func (*QuerySamples) MergeSeriesFromSubquery 

func (qs *QuerySamples) MergeSeriesFromSubquery(child *QuerySamples)

MergeSeriesFromSubquery adds the series touched while evaluating a subquery to the parent query's total. As with TotalSeries itself, the result is a per-selector SUM and is an upper bound on the number of distinct series.

func (*QuerySamples) MergeTotalSamplesFromSubquery 

func (qs *QuerySamples) MergeTotalSamplesFromSubquery(child *QuerySamples, c SubqueryConsumer)

MergeTotalSamplesFromSubquery merges the child's TotalSamples into the parent. Like a range-vector function, each parent step counts every child step in its window, so overlapping windows count a child step more than once. The child must be created with NewChildWithStepTracking.

func (*QuerySamples) NewChild 

func (*QuerySamples) NewChild() *QuerySamples

func (*QuerySamples) SamplesReadPerStepMap added in v0.313.0 

func (qs *QuerySamples) SamplesReadPerStepMap() *TotalSamplesPerStep

SamplesReadPerStepMap returns the per-step samples read as a map (timestamp -> count), or nil if per-step stats are disabled.

func (*QuerySamples) StepTrackingEnabled added in v0.313.0 

func (qs *QuerySamples) StepTrackingEnabled() bool

func (*QuerySamples) TotalSamplesPerStepMap 

func (qs *QuerySamples) TotalSamplesPerStepMap() *TotalSamplesPerStep

func (*QuerySamples) UpdatePeak 

func (qs *QuerySamples) UpdatePeak(samples int)

UpdatePeak updates the peak number of samples considered in the evaluation of a query as used with the MaxSamples limit.

func (*QuerySamples) UpdatePeakFromSubquery 

func (qs *QuerySamples) UpdatePeakFromSubquery(other *QuerySamples)

UpdatePeakFromSubquery updates the peak number of samples considered in a query from its evaluation of a subquery.

type QueryStats 

type QueryStats interface {
	Builtin() BuiltinStats
}

QueryStats holds BuiltinStats and any other stats the particular implementation wants to collect.

func NewQueryStats 

func NewQueryStats(s *Statistics) QueryStats

NewQueryStats makes a QueryStats struct with all QueryTimings found in the given TimerGroup.

type QueryTimers 

type QueryTimers struct {
	*TimerGroup
}

func NewQueryTimers 

func NewQueryTimers() *QueryTimers

func (*QueryTimers) GetSpanTimer 

func (qs *QueryTimers) GetSpanTimer(ctx context.Context, qt QueryTiming, observers ...prometheus.Observer) (*SpanTimer, context.Context)

type QueryTiming 

type QueryTiming int

QueryTiming identifies the code area or functionality in which time is spent during a query. 

const (
	EvalTotalTime QueryTiming = iota
	ResultSortTime
	QueryPreparationTime
	InnerEvalTime
	ExecQueueTime
	ExecTotalTime
)

Query timings.

func (QueryTiming) SpanOperation 

func (s QueryTiming) SpanOperation() string

SpanOperation returns a string representation of a QueryTiming span operation.

func (QueryTiming) String 

func (s QueryTiming) String() string

Return a string representation of a QueryTiming identifier.

type SpanTimer 

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

SpanTimer unifies tracing and timing, to reduce repetition.

func NewSpanTimer 

func NewSpanTimer(ctx context.Context, operation string, timer *Timer, observers ...prometheus.Observer) (*SpanTimer, context.Context)

func (*SpanTimer) Finish 

func (s *SpanTimer) Finish()

type Statistics 

type Statistics struct {
	Timers  *QueryTimers
	Samples *QuerySamples
}

type Stats 

type Stats struct {
	TimerStats  *QueryTimers
	SampleStats *QuerySamples
}

type SubqueryConsumer 

type SubqueryConsumer struct {
	// Start, Interval and NumSteps describe the parent's step grid. NumSteps <= 1
	// folds the child's totals into the parent's first step.
	Start, Interval int64
	NumSteps        int
	// Offset is the subquery's original offset.
	Offset int64
	// Range is the window width consumed at each parent step. Range <= 0 disables
	// window filtering and attributes each child step to the earliest parent step
	// at or after it, clamped to the parent's grid.
	Range int64
	// AtTimestamp is the subquery's @ timestamp, if any. Every parent step then
	// consumes the fixed window (*AtTimestamp-Range, *AtTimestamp].
	AtTimestamp *int64
}

SubqueryConsumer describes how a parent evaluator consumes a subquery's output, so the subquery's sample stats can be attributed to parent steps. A parent step at parentTs consumes the child steps whose timestamps, shifted by Offset, fall in (parentTs-Range, parentTs]. Child steps outside every parent window are not counted.

type Timer 

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

A Timer that can be started and stopped and accumulates the total time it was running (the time between Start() and Stop()).

func (*Timer) Duration 

func (t *Timer) Duration() float64

Duration returns the duration value of the timer in seconds.

func (*Timer) ElapsedTime 

func (t *Timer) ElapsedTime() time.Duration

ElapsedTime returns the time that passed since starting the timer.

func (*Timer) Start 

func (t *Timer) Start() *Timer

Start the timer.

func (*Timer) Stop 

func (t *Timer) Stop()

Stop the timer.

func (*Timer) String 

func (t *Timer) String() string

Return a string representation of the Timer.

type TimerGroup 

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

A TimerGroup represents a group of timers relevant to a single query.

func NewTimerGroup 

func NewTimerGroup() *TimerGroup

NewTimerGroup constructs a new TimerGroup.

func (*TimerGroup) GetTimer 

func (t *TimerGroup) GetTimer(name fmt.Stringer) *Timer

GetTimer gets (and creates, if necessary) the Timer for a given code section.

func (*TimerGroup) String 

func (t *TimerGroup) String() string

Return a string representation of a TimerGroup.

type TotalSamplesPerStep 

type TotalSamplesPerStep map[int64]int

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.