stats

package
v0.0.0-...-c935f95 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const MaxLatencyBin = 10000

Variables

This section is empty.

Functions

func PrintConfiguration

func PrintConfiguration(appCfg *config.AppConfig, collections []config.CollectionDefinition, version string)

func StableShapeID

func StableShapeID(operation, collection, shapeKey string) string

Types

type AccuracySnapshot

type AccuracySnapshot struct {
	FindOps        uint64
	FindReturned   uint64
	FindZero       uint64
	UpdateOps      uint64
	UpdateMatched  uint64
	UpdateModified uint64
	DeleteOps      uint64
	DeleteDeleted  uint64
	TargetExisting uint64
	TargetRandom   uint64
}

AccuracySnapshot exposes the accuracy counters for reporting/tests.

type CollectionInsight

type CollectionInsight struct {
	Collection string   `json:"collection"`
	Count      int      `json:"count"`
	SlowCount  int      `json:"slow_count"`
	SlowRatio  float64  `json:"slow_ratio"`
	AvgMs      float64  `json:"avg_ms"`
	P95Ms      float64  `json:"p95_ms"`
	P99Ms      float64  `json:"p99_ms"`
	MaxMs      float64  `json:"max_ms"`
	TopOps     []string `json:"top_ops,omitempty"`
}

type Collector

type Collector struct {
	FindOps   uint64
	InsertOps uint64
	UpsertOps uint64
	UpdateOps uint64
	DeleteOps uint64
	AggOps    uint64
	TransOps  uint64

	FindHist           *LatencyHistogram
	InsertHist         *LatencyHistogram
	UpsertHist         *LatencyHistogram
	UpdateHist         *LatencyHistogram
	DeleteHist         *LatencyHistogram
	AggHist            *LatencyHistogram
	TransHist          *LatencyHistogram
	TotalHist          *LatencyHistogram
	IntervalFindHist   *LatencyHistogram
	IntervalInsertHist *LatencyHistogram
	IntervalUpsertHist *LatencyHistogram
	IntervalUpdateHist *LatencyHistogram
	IntervalDeleteHist *LatencyHistogram
	IntervalAggHist    *LatencyHistogram
	IntervalTransHist  *LatencyHistogram
	IntervalTotalHist  *LatencyHistogram
	UIFindHist         *LatencyHistogram
	UIInsertHist       *LatencyHistogram
	UIUpsertHist       *LatencyHistogram
	UIUpdateHist       *LatencyHistogram
	UIDeleteHist       *LatencyHistogram
	UIAggHist          *LatencyHistogram
	UITransHist        *LatencyHistogram
	UITotalHist        *LatencyHistogram

	// HeatmapHist accumulates total latency for the current heatmap window and is
	// reset each time CaptureLatencyInterval snapshots it into the heatmap series.
	HeatmapHist *LatencyHistogram

	CurrentIteration int
	// contains filtered or unexported fields
}

func NewCollector

func NewCollector() *Collector

func (*Collector) AccuracyStats

func (c *Collector) AccuracyStats() AccuracySnapshot

AccuracyStats returns a snapshot of the current accuracy counters.

func (*Collector) Add

func (c *Collector) Add(opType string, count int64, duration time.Duration)

func (*Collector) CaptureLatencyInterval

func (c *Collector) CaptureLatencyInterval()

CaptureLatencyInterval snapshots the latency accumulated since the last call into a new heatmap bucket. Empty windows are skipped so the series only contains intervals where work happened. Callers invoke this on their polling cadence (e.g. the web UI stats poll), which defines the heatmap resolution.

func (*Collector) CaptureLatencyIntervalEvery

func (c *Collector) CaptureLatencyIntervalEvery(minWindow time.Duration)

CaptureLatencyIntervalEvery snapshots a heatmap bucket only when at least minWindow has elapsed since the previous capture. This decouples the heatmap window size from the UI polling cadence.

Without this gate the window equals the poll interval (500ms by default), so each window holds very few samples; with fewer than ~100 samples the 99th percentile collapses onto the single slowest operation in that window, which makes the heatmap look far worse than the cumulative p99 (a stray slow aggregate dominates a tiny window). A stable ~1s window gives each bucket a statistically meaningful sample count.

func (*Collector) ConcurrencySnapshot

func (c *Collector) ConcurrencySnapshot() (target, active int)

ConcurrencySnapshot returns the most recent (target, active) worker counts.

func (*Collector) ConfigureInsights

func (c *Collector) ConfigureInsights(cfg *config.AppConfig)

func (*Collector) GetExplainSettings

func (c *Collector) GetExplainSettings() (enabled bool, topN int, maxTimeMs int, verbosity string, severityMode string, workers int, retries int, backoffMs int)

func (*Collector) GetFinalInsights

func (c *Collector) GetFinalInsights() InsightsReport

func (*Collector) GetUILatencyTimelineAndReset

func (c *Collector) GetUILatencyTimelineAndReset() map[string]map[string]float64

func (*Collector) LatencyHeatmap

func (c *Collector) LatencyHeatmap() []LatencyBucket

LatencyHeatmap returns a copy of the captured latency-over-time series.

func (*Collector) MarkWorkloadStart

func (c *Collector) MarkWorkloadStart()

MarkWorkloadStart records the start of the measured workload window. Only the first call takes effect, so the elapsed timer reflects the true execution window and excludes preparation time.

func (*Collector) Monitor

func (c *Collector) Monitor(done <-chan struct{}, refreshRateSec int, concurrency int, csvEnabled bool, csvAppend bool, csvPath string, silent ...bool)

func (*Collector) PrintFinalSummary

func (c *Collector) PrintFinalSummary(duration time.Duration, silent ...bool)

func (*Collector) RecordDeleteResult

func (c *Collector) RecordDeleteResult(deleted int64)

RecordDeleteResult records the number of documents removed by a delete op.

func (*Collector) RecordFindResult

func (c *Collector) RecordFindResult(returned int64)

RecordFindResult records the number of documents returned by a find operation.

func (*Collector) RecordOperationEvent

func (c *Collector) RecordOperationEvent(op, database, collection, shapeKey, shapeSummary string, filterFields []string, duration time.Duration, success bool, iteration int, filterSample map[string]interface{}, pipelineSample []interface{}, queryLabel, querySource, workloadName, queryFile, queryDefID, querySummary, pipelineSummary string, queryDefIndex int)

func (*Collector) RecordTargeting

func (c *Collector) RecordTargeting(usedExisting bool)

RecordTargeting records whether an operation's filter was resolved from a known existing record (true) or from a random value (false).

func (*Collector) RecordUpdateResult

func (c *Collector) RecordUpdateResult(matched, modified int64)

RecordUpdateResult records matched/modified counts for an update operation.

func (*Collector) ResetInsights

func (c *Collector) ResetInsights()

func (*Collector) SetCollectionsForInsights

func (c *Collector) SetCollectionsForInsights(cols []config.CollectionDefinition)

func (*Collector) SetConcurrency

func (c *Collector) SetConcurrency(target, active int)

SetConcurrency records the live load-profile worker counts. target is what the schedule requests for the current elapsed time; active is how many workers are presently executing (un-parked) operations.

func (*Collector) SnapshotOperationEvents

func (c *Collector) SnapshotOperationEvents() []OperationEvent

func (*Collector) Track

func (c *Collector) Track(opType string, duration time.Duration)

func (*Collector) WorkloadStart

func (c *Collector) WorkloadStart() (time.Time, bool)

WorkloadStart returns the recorded workload start time and whether it is set.

type ExplainDiagnostics

type ExplainDiagnostics struct {
	ReplayDB                 string   `json:"replay_db,omitempty"`
	ReplayCollection         string   `json:"replay_collection,omitempty"`
	Verbosity                string   `json:"verbosity,omitempty"`
	ServerMaxTimeMS          int      `json:"server_max_time_ms,omitempty"`
	ClientTimeoutMS          int      `json:"client_timeout_ms,omitempty"`
	StageSummary             string   `json:"stage_summary,omitempty"`
	ElapsedMS                int      `json:"elapsed_ms,omitempty"`
	WinningPlanSummary       string   `json:"winning_plan_summary,omitempty"`
	PlanStages               []string `json:"plan_stages,omitempty"`
	IndexesUsed              []string `json:"indexes_used,omitempty"`
	CollectionScanDetected   bool     `json:"collection_scan_detected"`
	IndexScanDetected        bool     `json:"index_scan_detected"`
	FetchDetected            bool     `json:"fetch_detected"`
	GroupDetected            bool     `json:"group_detected"`
	SortDetected             bool     `json:"sort_detected"`
	LimitDetected            bool     `json:"limit_detected"`
	BlockingSortDetected     bool     `json:"blocking_sort_detected"`
	UsedDisk                 bool     `json:"used_disk"`
	DocsExamined             int64    `json:"docs_examined,omitempty"`
	KeysExamined             int64    `json:"keys_examined,omitempty"`
	NReturned                int64    `json:"n_returned,omitempty"`
	CollectionScans          int64    `json:"collection_scans,omitempty"`
	IndexSeeks               int64    `json:"index_seeks,omitempty"`
	ExecutionTimeMillis      int64    `json:"execution_time_millis,omitempty"`
	Spills                   int64    `json:"spills,omitempty"`
	ExaminedToReturnedRatio  float64  `json:"examined_to_returned_ratio,omitempty"`
	KeysToReturnedRatio      float64  `json:"keys_to_returned_ratio,omitempty"`
	ShardDetailsSummary      string   `json:"shard_details_summary,omitempty"`
	Interpretation           string   `json:"interpretation,omitempty"`
	Recommendation           string   `json:"recommendation,omitempty"`
	RecommendationConfidence string   `json:"recommendation_confidence,omitempty"`
	EvidenceSummary          string   `json:"evidence_summary,omitempty"`
}

type IndexIssue

type IndexIssue struct {
	Rank             int      `json:"rank"`
	ShapeID          string   `json:"shape_id"`
	Collection       string   `json:"collection"`
	Operation        string   `json:"operation"`
	ShapeKey         string   `json:"shape_key"`
	QueryLabel       string   `json:"query_label,omitempty"`
	QuerySource      string   `json:"query_source,omitempty"`
	WorkloadName     string   `json:"workload_name,omitempty"`
	QueryFile        string   `json:"query_file,omitempty"`
	QueryDefID       string   `json:"query_definition_id,omitempty"`
	QueryDefIndex    int      `json:"query_definition_index"`
	QuerySummary     string   `json:"representative_query_summary,omitempty"`
	PipelineSummary  string   `json:"representative_pipeline_summary,omitempty"`
	QueryRefVariants int      `json:"query_reference_variants,omitempty"`
	FilterFields     []string `json:"filter_fields,omitempty"`
	Count            int      `json:"count"`
	AvgMs            float64  `json:"avg_ms"`
	P95Ms            float64  `json:"p95_ms"`
	P99Ms            float64  `json:"p99_ms"`
	MaxMs            float64  `json:"max_ms"`
	EvidenceLevel    string   `json:"evidence_level"`
	Confidence       string   `json:"confidence"`
	ExplainStatus    string   `json:"explain_status,omitempty"`
	ExplainReason    string   `json:"explain_reason,omitempty"`
	Message          string   `json:"message"`
	Recommendation   string   `json:"recommendation"`
}

type InsightRecommendation

type InsightRecommendation struct {
	Rank       int    `json:"rank"`
	Priority   string `json:"priority"`
	Title      string `json:"title"`
	Details    string `json:"details"`
	Confidence string `json:"confidence"`
}

type InsightsMetadata

type InsightsMetadata struct {
	Status              string  `json:"status"`
	GeneratedAt         string  `json:"generated_at,omitempty"`
	SlowThresholdMs     float64 `json:"slow_threshold_ms"`
	SamplingRate        float64 `json:"sampling_rate"`
	RetainedEvents      int     `json:"retained_events"`
	EligibleEvents      uint64  `json:"eligible_events"`
	SampledInEvents     uint64  `json:"sampled_in_events"`
	DroppedGroupEntries int     `json:"dropped_group_entries"`
	FilteredByThreshold int     `json:"filtered_by_threshold"`
	FilteredBySeverity  int     `json:"filtered_by_severity"`
	EvidenceLevel       string  `json:"evidence_level"`
	ExplainEnabled      bool    `json:"explain_enabled"`
	ExplainMode         string  `json:"explain_mode"`
	ExplainVerbosity    string  `json:"explain_verbosity"`
	ExplainSeverityMode string  `json:"explain_severity_mode"`
	ExplainWorkers      int     `json:"explain_workers"`
	ExplainRetries      int     `json:"explain_retries"`
	ExplainBackoffMS    int     `json:"explain_backoff_ms"`
	ExplainImpact       string  `json:"explain_impact"`
}

type InsightsReport

type InsightsReport struct {
	Summary              InsightsSummary         `json:"summary"`
	SlowQueries          []SlowQueryInsight      `json:"slow_queries"`
	AffectedCollections  []CollectionInsight     `json:"affected_collections"`
	QueryShapes          []SlowQueryInsight      `json:"query_shapes"`
	PotentialIndexIssues []IndexIssue            `json:"potential_index_issues"`
	Recommendations      []InsightRecommendation `json:"recommendations"`
	PerIteration         []IterationInsight      `json:"per_iteration,omitempty"`
	TimeSlices           []TimeSliceInsight      `json:"time_slices,omitempty"`
	Metadata             InsightsMetadata        `json:"metadata"`
}

type InsightsSummary

type InsightsSummary struct {
	TotalSampledEvents int     `json:"total_sampled_events"`
	SlowSampledEvents  int     `json:"slow_sampled_events"`
	SlowSampledRatio   float64 `json:"slow_sampled_ratio"`
	TopSeverity        string  `json:"top_severity"`
}

type IterationInsight

type IterationInsight struct {
	Iteration int     `json:"iteration"`
	Count     int     `json:"count"`
	SlowCount int     `json:"slow_count"`
	SlowRatio float64 `json:"slow_ratio"`
	AvgMs     float64 `json:"avg_ms"`
	P95Ms     float64 `json:"p95_ms"`
	P99Ms     float64 `json:"p99_ms"`
}

type LatencyBucket

type LatencyBucket struct {
	ElapsedSec      float64 `json:"elapsedSec"`
	TimestampUnixMs int64   `json:"timestampUnixMs"`
	Count           int64   `json:"count"`
	P50             float64 `json:"p50"`
	P95             float64 `json:"p95"`
	P99             float64 `json:"p99"`
	Max             float64 `json:"max"`
}

LatencyBucket is one time-window of latency percentiles, used to render a latency-over-time heatmap and to surface tail-latency drift.

type LatencyHeatmap

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

LatencyHeatmap is an ordered, bounded series of LatencyBuckets. It is safe for concurrent append/read.

func NewLatencyHeatmap

func NewLatencyHeatmap(maxBuckets int) *LatencyHeatmap

NewLatencyHeatmap builds a heatmap series. A non-positive max uses the default.

func (*LatencyHeatmap) Append

func (lh *LatencyHeatmap) Append(b LatencyBucket)

Append adds a bucket, trimming the oldest if the cap is exceeded.

func (*LatencyHeatmap) Len

func (lh *LatencyHeatmap) Len() int

Len returns the number of buckets currently stored.

func (*LatencyHeatmap) Snapshot

func (lh *LatencyHeatmap) Snapshot() []LatencyBucket

Snapshot returns a copy of the current series.

type LatencyHistogram

type LatencyHistogram struct {
	Buckets  [MaxLatencyBin]int64
	Overflow int64
	Count    int64
	Sum      float64
	Min      float64
	Max      float64
	// contains filtered or unexported fields
}

func (*LatencyHistogram) GetAverage

func (h *LatencyHistogram) GetAverage() float64

func (*LatencyHistogram) GetPercentile

func (h *LatencyHistogram) GetPercentile(p float64) float64

func (*LatencyHistogram) GetStats

func (h *LatencyHistogram) GetStats() map[string]float64

func (*LatencyHistogram) GetStatsAndReset

func (h *LatencyHistogram) GetStatsAndReset() map[string]float64

func (*LatencyHistogram) Record

func (h *LatencyHistogram) Record(ms float64)

func (*LatencyHistogram) RecordBatch

func (h *LatencyHistogram) RecordBatch(ms float64, count int64)

func (*LatencyHistogram) SnapshotAndReset

func (h *LatencyHistogram) SnapshotAndReset() (count int64, p50, p95, p99, max float64)

SnapshotAndReset returns the count and p50/p95/p99/max for the current window and then clears the histogram, so callers can build a per-interval latency series (heatmap) without double-counting across windows.

type OperationEvent

type OperationEvent struct {
	Operation       string                 `json:"operation"`
	Database        string                 `json:"database,omitempty"`
	Collection      string                 `json:"collection"`
	ShapeKey        string                 `json:"shape_key"`
	ShapeSummary    string                 `json:"shape_summary"`
	QueryLabel      string                 `json:"query_label,omitempty"`
	QuerySource     string                 `json:"query_source,omitempty"`
	WorkloadName    string                 `json:"workload_name,omitempty"`
	QueryFile       string                 `json:"query_file,omitempty"`
	QueryDefID      string                 `json:"query_definition_id,omitempty"`
	QueryDefIndex   int                    `json:"query_definition_index"`
	QuerySummary    string                 `json:"representative_query_summary,omitempty"`
	PipelineSummary string                 `json:"representative_pipeline_summary,omitempty"`
	FilterFields    []string               `json:"filter_fields,omitempty"`
	DurationMs      float64                `json:"duration_ms"`
	Success         bool                   `json:"success"`
	Iteration       int                    `json:"iteration"`
	TimestampMs     int64                  `json:"timestamp_ms"`
	FilterSample    map[string]interface{} `json:"-"`
	PipelineSample  []interface{}          `json:"-"`
}

type ShapeTrend

type ShapeTrend struct {
	PreviousP95Ms float64 `json:"previous_p95_ms"`
	CurrentP95Ms  float64 `json:"current_p95_ms"`
	DeltaP95Ms    float64 `json:"delta_p95_ms"`
	Direction     string  `json:"direction"`
}

type SlowQueryInsight

type SlowQueryInsight struct {
	Rank             int                 `json:"rank"`
	ShapeID          string              `json:"shape_id"`
	Operation        string              `json:"operation"`
	Collection       string              `json:"collection"`
	ShapeKey         string              `json:"shape_key"`
	ShapeSummary     string              `json:"shape_summary"`
	QueryLabel       string              `json:"query_label,omitempty"`
	QuerySource      string              `json:"query_source,omitempty"`
	WorkloadName     string              `json:"workload_name,omitempty"`
	QueryFile        string              `json:"query_file,omitempty"`
	QueryDefID       string              `json:"query_definition_id,omitempty"`
	QueryDefIndex    int                 `json:"query_definition_index"`
	QuerySummary     string              `json:"representative_query_summary,omitempty"`
	PipelineSummary  string              `json:"representative_pipeline_summary,omitempty"`
	QueryRefVariants int                 `json:"query_reference_variants,omitempty"`
	FilterFields     []string            `json:"filter_fields,omitempty"`
	Count            int                 `json:"count"`
	ErrorCount       int                 `json:"error_count"`
	SlowCount        int                 `json:"slow_count"`
	SlowRatio        float64             `json:"slow_ratio"`
	AvgMs            float64             `json:"avg_ms"`
	P95Ms            float64             `json:"p95_ms"`
	P99Ms            float64             `json:"p99_ms"`
	MaxMs            float64             `json:"max_ms"`
	Severity         string              `json:"severity"`
	ExplainStatus    string              `json:"explain_status,omitempty"`
	ExplainReason    string              `json:"explain_reason,omitempty"`
	ExplainDiag      *ExplainDiagnostics `json:"explain_diagnostics,omitempty"`
	Trend            *ShapeTrend         `json:"trend,omitempty"`
}

type TimeSliceInsight

type TimeSliceInsight struct {
	BucketLabel string  `json:"bucket_label"`
	Count       int     `json:"count"`
	SlowCount   int     `json:"slow_count"`
	AvgMs       float64 `json:"avg_ms"`
	P95Ms       float64 `json:"p95_ms"`
	P99Ms       float64 `json:"p99_ms"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL