Documentation
¶
Index ¶
- Constants
- func PrintConfiguration(appCfg *config.AppConfig, collections []config.CollectionDefinition, ...)
- func StableShapeID(operation, collection, shapeKey string) string
- type AccuracySnapshot
- type CollectionInsight
- type Collector
- func (c *Collector) AccuracyStats() AccuracySnapshot
- func (c *Collector) Add(opType string, count int64, duration time.Duration)
- func (c *Collector) CaptureLatencyInterval()
- func (c *Collector) CaptureLatencyIntervalEvery(minWindow time.Duration)
- func (c *Collector) ConcurrencySnapshot() (target, active int)
- func (c *Collector) ConfigureInsights(cfg *config.AppConfig)
- func (c *Collector) GetExplainSettings() (enabled bool, topN int, maxTimeMs int, verbosity string, severityMode string, ...)
- func (c *Collector) GetFinalInsights() InsightsReport
- func (c *Collector) GetUILatencyTimelineAndReset() map[string]map[string]float64
- func (c *Collector) LatencyHeatmap() []LatencyBucket
- func (c *Collector) MarkWorkloadStart()
- func (c *Collector) Monitor(done <-chan struct{}, refreshRateSec int, concurrency int, csvEnabled bool, ...)
- func (c *Collector) PrintFinalSummary(duration time.Duration, silent ...bool)
- func (c *Collector) RecordDeleteResult(deleted int64)
- func (c *Collector) RecordFindResult(returned int64)
- func (c *Collector) RecordOperationEvent(op, database, collection, shapeKey, shapeSummary string, filterFields []string, ...)
- func (c *Collector) RecordTargeting(usedExisting bool)
- func (c *Collector) RecordUpdateResult(matched, modified int64)
- func (c *Collector) ResetInsights()
- func (c *Collector) SetCollectionsForInsights(cols []config.CollectionDefinition)
- func (c *Collector) SetConcurrency(target, active int)
- func (c *Collector) SnapshotOperationEvents() []OperationEvent
- func (c *Collector) Track(opType string, duration time.Duration)
- func (c *Collector) WorkloadStart() (time.Time, bool)
- type ExplainDiagnostics
- type IndexIssue
- type InsightRecommendation
- type InsightsMetadata
- type InsightsReport
- type InsightsSummary
- type IterationInsight
- type LatencyBucket
- type LatencyHeatmap
- type LatencyHistogram
- func (h *LatencyHistogram) GetAverage() float64
- func (h *LatencyHistogram) GetPercentile(p float64) float64
- func (h *LatencyHistogram) GetStats() map[string]float64
- func (h *LatencyHistogram) GetStatsAndReset() map[string]float64
- func (h *LatencyHistogram) Record(ms float64)
- func (h *LatencyHistogram) RecordBatch(ms float64, count int64)
- func (h *LatencyHistogram) SnapshotAndReset() (count int64, p50, p95, p99, max float64)
- type OperationEvent
- type ShapeTrend
- type SlowQueryInsight
- type TimeSliceInsight
Constants ¶
const MaxLatencyBin = 10000
Variables ¶
This section is empty.
Functions ¶
func PrintConfiguration ¶
func PrintConfiguration(appCfg *config.AppConfig, collections []config.CollectionDefinition, version string)
func StableShapeID ¶
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) 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 ¶
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 ¶
ConcurrencySnapshot returns the most recent (target, active) worker counts.
func (*Collector) ConfigureInsights ¶
func (*Collector) GetExplainSettings ¶
func (*Collector) GetFinalInsights ¶
func (c *Collector) GetFinalInsights() InsightsReport
func (*Collector) GetUILatencyTimelineAndReset ¶
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) PrintFinalSummary ¶
func (*Collector) RecordDeleteResult ¶
RecordDeleteResult records the number of documents removed by a delete op.
func (*Collector) RecordFindResult ¶
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 ¶
RecordTargeting records whether an operation's filter was resolved from a known existing record (true) or from a random value (false).
func (*Collector) RecordUpdateResult ¶
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 ¶
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
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 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 IterationInsight ¶
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 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"`
}