improved workload insights; ui redesign

Author: daniel-percona

INSIGHTS.md

@@ -95,6 +95,7 @@ Quick access:
 * Full guide: [`INSIGHTS.md`](./INSIGHTS.md)
 * Web UI path: `Advanced -> Insights Analysis`
 * Output: Dashboard insights panel + `Download Summary` JSON (`insights` section)
+* Includes explain support matrix, status/reason glossary, confidence model, troubleshooting, and limitations
 
 ## The Interactive UI
 

README.md

@@ -59,6 +59,25 @@ csv_export_enabled: false
 csv_export_append: false # If true, appends to the file. If false, overwrites it.
 csv_export_path: "/tmp/plgm_metrics_export.csv"
 
+# ==============================================================================
+# Post-Run Insights (Slow Query / Index Analysis)
+# ==============================================================================
+# Insights are generated after workload completion.
+# Explain mode is post-run only and does not execute during the measured workload window.
+insights_enabled: true
+insights_sampling_rate: 0.10
+insights_slow_threshold_ms: 200
+insights_max_events: 5000
+insights_max_groups: 300
+insights_explain_enabled: false
+insights_explain_top_n: 5
+insights_explain_max_time_ms: 1000
+# Modes: high_only (default), medium_only, critical_only, high_and_low
+insights_explain_severity_mode: "high_only"
+insights_explain_workers: 1
+insights_explain_retries: 1
+insights_explain_backoff_ms: 150
+
 # ==============================================================================
 # Workload Definition
 # ==============================================================================

config.yaml

@@ -54,14 +54,18 @@ type AppConfig struct {
 	CSVExportAppend  bool   `yaml:"csv_export_append"`
 	CSVExportPath    string `yaml:"csv_export_path"`
 
-	InsightsEnabled          bool    `yaml:"insights_enabled"`
-	InsightsSamplingRate     float64 `yaml:"insights_sampling_rate"`
-	InsightsSlowThresholdMs  int     `yaml:"insights_slow_threshold_ms"`
-	InsightsMaxEvents        int     `yaml:"insights_max_events"`
-	InsightsMaxGroups        int     `yaml:"insights_max_groups"`
-	InsightsExplainEnabled   bool    `yaml:"insights_explain_enabled"`
-	InsightsExplainTopN      int     `yaml:"insights_explain_top_n"`
-	InsightsExplainMaxTimeMS int     `yaml:"insights_explain_max_time_ms"`
+	InsightsEnabled             bool    `yaml:"insights_enabled"`
+	InsightsSamplingRate        float64 `yaml:"insights_sampling_rate"`
+	InsightsSlowThresholdMs     int     `yaml:"insights_slow_threshold_ms"`
+	InsightsMaxEvents           int     `yaml:"insights_max_events"`
+	InsightsMaxGroups           int     `yaml:"insights_max_groups"`
+	InsightsExplainEnabled      bool    `yaml:"insights_explain_enabled"`
+	InsightsExplainTopN         int     `yaml:"insights_explain_top_n"`
+	InsightsExplainMaxTimeMS    int     `yaml:"insights_explain_max_time_ms"`
+	InsightsExplainSeverityMode string  `yaml:"insights_explain_severity_mode"`
+	InsightsExplainWorkers      int     `yaml:"insights_explain_workers"`
+	InsightsExplainRetries      int     `yaml:"insights_explain_retries"`
+	InsightsExplainBackoffMS    int     `yaml:"insights_explain_backoff_ms"`
 }
 
 type WebUIConfig struct {
@@ -169,6 +173,10 @@ func applyUIDefaults(cfg *AppConfig) {
 	cfg.InsightsExplainEnabled = false
 	cfg.InsightsExplainTopN = 5
 	cfg.InsightsExplainMaxTimeMS = 1000
+	cfg.InsightsExplainSeverityMode = "high_only"
+	cfg.InsightsExplainWorkers = 1
+	cfg.InsightsExplainRetries = 1
+	cfg.InsightsExplainBackoffMS = 150
 }
 
 // applyBaseDefaults sets low-level engine safety limits & remaining UI limits
@@ -204,6 +212,20 @@ func applyBaseDefaults(cfg *AppConfig) {
 	if cfg.InsightsExplainMaxTimeMS <= 0 {
 		cfg.InsightsExplainMaxTimeMS = 1000
 	}
+	switch cfg.InsightsExplainSeverityMode {
+	case "high_and_low", "medium_only", "critical_only", "high_only":
+	default:
+		cfg.InsightsExplainSeverityMode = "high_only"
+	}
+	if cfg.InsightsExplainWorkers <= 0 {
+		cfg.InsightsExplainWorkers = 1
+	}
+	if cfg.InsightsExplainRetries < 0 {
+		cfg.InsightsExplainRetries = 0
+	}
+	if cfg.InsightsExplainBackoffMS < 0 {
+		cfg.InsightsExplainBackoffMS = 0
+	}
 
 	// Web UI Port
 	if cfg.WebUI.Port <= 0 {
@@ -567,6 +589,24 @@ func applyEnvOverrides(cfg *AppConfig) map[string]bool {
 			cfg.InsightsExplainMaxTimeMS = n
 		}
 	}
+	if v := os.Getenv("PLGM_INSIGHTS_EXPLAIN_SEVERITY_MODE"); v != "" {
+		cfg.InsightsExplainSeverityMode = v
+	}
+	if v := os.Getenv("PLGM_INSIGHTS_EXPLAIN_WORKERS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			cfg.InsightsExplainWorkers = n
+		}
+	}
+	if v := os.Getenv("PLGM_INSIGHTS_EXPLAIN_RETRIES"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			cfg.InsightsExplainRetries = n
+		}
+	}
+	if v := os.Getenv("PLGM_INSIGHTS_EXPLAIN_BACKOFF_MS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			cfg.InsightsExplainBackoffMS = n
+		}
+	}
 
 	return overrides
 }

internal/config/config.go

@@ -28,6 +28,9 @@ func TestLoadAppConfigWebUIDefaultsAndBaseDefaults(t *testing.T) {
 	if cfg.FindPercent+cfg.UpdatePercent+cfg.DeletePercent+cfg.InsertPercent+cfg.AggregatePercent+cfg.TransactionPercent+cfg.BulkInsertPercent != 100 {
 		t.Fatalf("expected normalized percentages to total 100")
 	}
+	if cfg.InsightsExplainWorkers != 1 || cfg.InsightsExplainRetries != 1 || cfg.InsightsExplainBackoffMS != 150 || cfg.InsightsExplainSeverityMode != "high_only" {
+		t.Fatalf("expected explain defaults workers=1 retries=1 backoff=150 mode=high_only, got workers=%d retries=%d backoff=%d mode=%q", cfg.InsightsExplainWorkers, cfg.InsightsExplainRetries, cfg.InsightsExplainBackoffMS, cfg.InsightsExplainSeverityMode)
+	}
 }
 
 func TestLoadAppConfigWithYAMLAndEnvOverrides(t *testing.T) {
@@ -133,3 +136,35 @@ func TestApplyBaseDefaultsPreservesExplicitValues(t *testing.T) {
 		t.Fatalf("expected csv path default when export enabled")
 	}
 }
+
+func TestApplyEnvOverridesInsightsExplainRuntimeSettings(t *testing.T) {
+	cfg := &AppConfig{}
+	t.Setenv("PLGM_INSIGHTS_EXPLAIN_WORKERS", "3")
+	t.Setenv("PLGM_INSIGHTS_EXPLAIN_RETRIES", "2")
+	t.Setenv("PLGM_INSIGHTS_EXPLAIN_BACKOFF_MS", "250")
+	t.Setenv("PLGM_INSIGHTS_EXPLAIN_SEVERITY_MODE", "medium_only")
+
+	_ = applyEnvOverrides(cfg)
+	applyBaseDefaults(cfg)
+
+	if cfg.InsightsExplainWorkers != 3 {
+		t.Fatalf("expected explain workers override 3, got %d", cfg.InsightsExplainWorkers)
+	}
+	if cfg.InsightsExplainRetries != 2 {
+		t.Fatalf("expected explain retries override 2, got %d", cfg.InsightsExplainRetries)
+	}
+	if cfg.InsightsExplainBackoffMS != 250 {
+		t.Fatalf("expected explain backoff override 250, got %d", cfg.InsightsExplainBackoffMS)
+	}
+	if cfg.InsightsExplainSeverityMode != "medium_only" {
+		t.Fatalf("expected explain severity mode override medium_only, got %q", cfg.InsightsExplainSeverityMode)
+	}
+}
+
+func TestApplyBaseDefaultsNormalizesUnknownExplainSeverityMode(t *testing.T) {
+	cfg := &AppConfig{InsightsExplainSeverityMode: "unexpected_mode"}
+	applyBaseDefaults(cfg)
+	if cfg.InsightsExplainSeverityMode != "high_only" {
+		t.Fatalf("expected invalid explain severity mode to normalize to high_only, got %q", cfg.InsightsExplainSeverityMode)
+	}
+}