release-8.5: cherry-pick improments of statement summary coverage

pkg/executor/select.go

@@ -1213,7 +1213,9 @@ func ResetContextOfStmt(ctx sessionctx.Context, s ast.StmtNode) (err error) {
 		sc.PrevLastInsertID = vars.StmtCtx.PrevLastInsertID
 	}
 	sc.PrevAffectedRows = 0
-	if vars.StmtCtx.InUpdateStmt || vars.StmtCtx.InDeleteStmt || vars.StmtCtx.InInsertStmt || vars.StmtCtx.InSetSessionStatesStmt {
+	if vars.StmtCtx.InSetSessionStatesStmt {
+		sc.PrevAffectedRows = vars.StmtCtx.PrevAffectedRows
+	} else if vars.StmtCtx.InUpdateStmt || vars.StmtCtx.InDeleteStmt || vars.StmtCtx.InInsertStmt {
 		sc.PrevAffectedRows = int64(vars.StmtCtx.AffectedRows())
 	} else if vars.StmtCtx.InSelectStmt {
 		sc.PrevAffectedRows = -1

pkg/metrics/BUILD.bazel

@@ -23,6 +23,7 @@ go_library(
         "server.go",
         "session.go",
         "sli.go",
+        "stmtsummary.go",
         "stats.go",
         "telemetry.go",
         "topsql.go",
@@ -62,6 +63,8 @@ go_test(
         "//pkg/statistics/handle/cache",
         "//pkg/testkit/testsetup",
         "@com_github_pingcap_errors//:errors",
+        "@com_github_prometheus_client_golang//prometheus",
+        "@com_github_prometheus_client_model//go",
         "@com_github_stretchr_testify//require",
         "@org_uber_go_goleak//:goleak",
     ],

pkg/metrics/metrics.go

@@ -97,6 +97,7 @@ func InitMetrics() {
 	InitResourceGroupMetrics()
 	InitGlobalSortMetrics()
 	InitInfoSchemaV2Metrics()
+	InitStmtSummaryMetrics()
 	timermetrics.InitTimerMetrics()
 
 	// For now, those metrics are initialized but not registered.
@@ -319,6 +320,11 @@ func RegisterMetrics() {
 	prometheus.MustRegister(IndexLookRowsCounter)
 	prometheus.MustRegister(IndexLookUpExecutorRowNumber)
 	prometheus.MustRegister(IndexLookUpCopTaskCount)
+
+	// StmtSummary
+	prometheus.MustRegister(StmtSummaryWindowRecordCount)
+	prometheus.MustRegister(StmtSummaryWindowEvictedCount)
+	prometheus.MustRegister(StmtSummaryEvictedLogCounter)
 }
 
 var mode struct {

pkg/metrics/metrics_internal_test.go

@@ -18,10 +18,63 @@ import (
 	"testing"
 
 	"github.com/pingcap/errors"
+	"github.com/prometheus/client_golang/prometheus"
+	dto "github.com/prometheus/client_model/go"
 	"github.com/stretchr/testify/require"
 )
 
 func TestRetLabel(t *testing.T) {
 	require.Equal(t, opSucc, RetLabel(nil))
 	require.Equal(t, opFailed, RetLabel(errors.New("test error")))
 }
+
+func readGaugeValue(t *testing.T, gauge prometheus.Gauge) float64 {
+	t.Helper()
+	m := &dto.Metric{}
+	require.NoError(t, gauge.Write(m))
+	return m.GetGauge().GetValue()
+}
+
+func readCounterValue(t *testing.T, counter prometheus.Counter) float64 {
+	t.Helper()
+	m := &dto.Metric{}
+	require.NoError(t, counter.Write(m))
+	return m.GetCounter().GetValue()
+}
+
+func countCollectedMetrics(collector prometheus.Collector) int {
+	ch := make(chan prometheus.Metric, 16)
+	collector.Collect(ch)
+	close(ch)
+
+	count := 0
+	for range ch {
+		count++
+	}
+	return count
+}
+
+func TestStmtSummaryMetricLabels(t *testing.T) {
+	InitStmtSummaryMetrics()
+	require.Equal(t, 0, countCollectedMetrics(StmtSummaryWindowRecordCount))
+	require.Equal(t, 0, countCollectedMetrics(StmtSummaryWindowEvictedCount))
+	require.Equal(t, 0, countCollectedMetrics(StmtSummaryEvictedLogCounter))
+
+	SetStmtSummaryWindowMetrics(StmtSummaryTypeV1, 3, 1)
+	require.Equal(t, 1, countCollectedMetrics(StmtSummaryWindowRecordCount))
+	require.Equal(t, 1, countCollectedMetrics(StmtSummaryWindowEvictedCount))
+	require.Equal(t, 3.0, readGaugeValue(t, StmtSummaryWindowRecordCount.WithLabelValues(StmtSummaryTypeV1)))
+	require.Equal(t, 1.0, readGaugeValue(t, StmtSummaryWindowEvictedCount.WithLabelValues(StmtSummaryTypeV1)))
+
+	SetStmtSummaryWindowMetrics(StmtSummaryTypeV2, 5, 2)
+	require.Equal(t, 2, countCollectedMetrics(StmtSummaryWindowRecordCount))
+	require.Equal(t, 2, countCollectedMetrics(StmtSummaryWindowEvictedCount))
+	require.Equal(t, 5.0, readGaugeValue(t, StmtSummaryWindowRecordCount.WithLabelValues(StmtSummaryTypeV2)))
+	require.Equal(t, 2.0, readGaugeValue(t, StmtSummaryWindowEvictedCount.WithLabelValues(StmtSummaryTypeV2)))
+
+	StmtSummaryEvictedLogCounter.WithLabelValues(StmtSummaryTypeV2, StmtSummaryEvictedLogResultPersisted).Add(3)
+	StmtSummaryEvictedLogCounter.WithLabelValues(StmtSummaryTypeV2, StmtSummaryEvictedLogResultDropped).Inc()
+	require.Equal(t, 2, countCollectedMetrics(StmtSummaryEvictedLogCounter))
+	require.Equal(t, 3.0, readCounterValue(t, StmtSummaryEvictedLogCounter.WithLabelValues(StmtSummaryTypeV2, StmtSummaryEvictedLogResultPersisted)))
+	require.Equal(t, 1.0, readCounterValue(t, StmtSummaryEvictedLogCounter.WithLabelValues(StmtSummaryTypeV2, StmtSummaryEvictedLogResultDropped)))
+}

pkg/metrics/stmtsummary.go

@@ -0,0 +1,128 @@
+// Copyright 2026 PingCAP, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package metrics
+
+import (
+	"sync"
+
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+// Statement summary metrics.
+const (
+	// StmtSummaryTypeV1 marks metrics reported by the legacy statement summary implementation.
+	StmtSummaryTypeV1 = "v1"
+	// StmtSummaryTypeV2 marks metrics reported by the persistent statement summary implementation.
+	StmtSummaryTypeV2 = "v2"
+
+	// StmtSummaryEvictedLogResultPersisted marks evicted records submitted to the stmt log.
+	StmtSummaryEvictedLogResultPersisted = "persisted"
+	// StmtSummaryEvictedLogResultDropped marks evicted records dropped before reaching the stmt log.
+	StmtSummaryEvictedLogResultDropped = "dropped"
+)
+
+var (
+	// StmtSummaryWindowRecordCount is a gauge that tracks the number of statement
+	// summary records in the current statement summary window.
+	StmtSummaryWindowRecordCount *prometheus.GaugeVec
+
+	// StmtSummaryWindowEvictedCount is a gauge that tracks the number of LRU
+	// evictions that have occurred in the current statement summary window.
+	// This value resets to 0 when the window rotates.
+	StmtSummaryWindowEvictedCount *prometheus.GaugeVec
+
+	// StmtSummaryEvictedLogCounter counts v2 evicted-log persistence outcomes.
+	StmtSummaryEvictedLogCounter *prometheus.CounterVec
+
+	stmtSummaryWindowRecordCountV1  prometheus.Gauge
+	stmtSummaryWindowRecordCountV2  prometheus.Gauge
+	stmtSummaryWindowEvictedCountV1 prometheus.Gauge
+	stmtSummaryWindowEvictedCountV2 prometheus.Gauge
+
+	stmtSummaryWindowMetricsMu sync.Mutex
+)
+
+// InitStmtSummaryMetrics initializes statement summary metrics.
+func InitStmtSummaryMetrics() {
+	StmtSummaryWindowRecordCount = NewGaugeVec(
+		prometheus.GaugeOpts{
+			Namespace: "tidb",
+			Subsystem: "stmt_summary",
+			Name:      "window_record_count",
+			Help:      "The number of statement summary records currently tracked by statement summary.",
+		}, []string{LblType})
+
+	StmtSummaryWindowEvictedCount = NewGaugeVec(
+		prometheus.GaugeOpts{
+			Namespace: "tidb",
+			Subsystem: "stmt_summary",
+			Name:      "window_evicted_count",
+			Help:      "The number of LRU evictions in the current statement summary window.",
+		}, []string{LblType})
+
+	StmtSummaryEvictedLogCounter = NewCounterVec(
+		prometheus.CounterOpts{
+			Namespace: "tidb",
+			Subsystem: "stmt_summary",
+			Name:      "evicted_log_total",
+			Help:      "The number of v2 statement summary evicted-log records by result.",
+		}, []string{LblType, LblResult})
+
+	stmtSummaryWindowMetricsMu.Lock()
+	stmtSummaryWindowRecordCountV1 = nil
+	stmtSummaryWindowRecordCountV2 = nil
+	stmtSummaryWindowEvictedCountV1 = nil
+	stmtSummaryWindowEvictedCountV2 = nil
+	stmtSummaryWindowMetricsMu.Unlock()
+}
+
+// SetStmtSummaryWindowMetrics reports statement summary window metrics for a given implementation type.
+func SetStmtSummaryWindowMetrics(typ string, recordCount, evictedCount float64) {
+	switch typ {
+	case StmtSummaryTypeV1:
+		recordGauge, evictedGauge := getStmtSummaryWindowMetricsLocked(typ)
+		recordGauge.Set(recordCount)
+		evictedGauge.Set(evictedCount)
+	case StmtSummaryTypeV2:
+		recordGauge, evictedGauge := getStmtSummaryWindowMetricsLocked(typ)
+		recordGauge.Set(recordCount)
+		evictedGauge.Set(evictedCount)
+	default:
+		StmtSummaryWindowRecordCount.WithLabelValues(typ).Set(recordCount)
+		StmtSummaryWindowEvictedCount.WithLabelValues(typ).Set(evictedCount)
+	}
+}
+
+func getStmtSummaryWindowMetricsLocked(typ string) (prometheus.Gauge, prometheus.Gauge) {
+	stmtSummaryWindowMetricsMu.Lock()
+	defer stmtSummaryWindowMetricsMu.Unlock()
+
+	switch typ {
+	case StmtSummaryTypeV1:
+		if stmtSummaryWindowRecordCountV1 == nil {
+			stmtSummaryWindowRecordCountV1 = StmtSummaryWindowRecordCount.WithLabelValues(typ)
+			stmtSummaryWindowEvictedCountV1 = StmtSummaryWindowEvictedCount.WithLabelValues(typ)
+		}
+		return stmtSummaryWindowRecordCountV1, stmtSummaryWindowEvictedCountV1
+	case StmtSummaryTypeV2:
+		if stmtSummaryWindowRecordCountV2 == nil {
+			stmtSummaryWindowRecordCountV2 = StmtSummaryWindowRecordCount.WithLabelValues(typ)
+			stmtSummaryWindowEvictedCountV2 = StmtSummaryWindowEvictedCount.WithLabelValues(typ)
+		}
+		return stmtSummaryWindowRecordCountV2, stmtSummaryWindowEvictedCountV2
+	default:
+		return nil, nil
+	}
+}

pkg/sessionctx/sessionstates/session_states_test.go

@@ -684,6 +684,7 @@ func TestStatementCtx(t *testing.T) {
 				return nil
 			},
 			checkFunc: func(tk *testkit.TestKit, param any) {
+				require.Equal(t, uint64(0), tk.Session().AffectedRows())
 				tk.MustQuery("select row_count()").Check(testkit.Rows("-1"))
 			},
 		},

pkg/sessionctx/variable/session.go

@@ -3062,7 +3062,7 @@ func (s *SessionVars) DecodeSessionStates(_ context.Context, sessionStates *sess
 	s.HypoTiFlashReplicas = sessionStates.HypoTiFlashReplicas
 
 	// Decode StatementContext.
-	s.StmtCtx.SetAffectedRows(uint64(sessionStates.LastAffectedRows))
+	s.StmtCtx.PrevAffectedRows = sessionStates.LastAffectedRows
 	s.StmtCtx.PrevLastInsertID = sessionStates.LastInsertID
 	s.StmtCtx.SetWarnings(sessionStates.Warnings)
 	return

pkg/sessionctx/variable/sysvar.go

@@ -880,6 +880,14 @@ var defaultSysVars = []*SysVar{
 		SetGlobal: func(_ context.Context, s *SessionVars, val string) error {
 			return stmtsummaryv2.SetMaxSQLLength(TidbOptInt(val, DefTiDBStmtSummaryMaxSQLLength))
 		}},
+	{Scope: ScopeGlobal, Name: TiDBStmtSummaryPersistEvicted, Value: BoolToOnOff(DefTiDBStmtSummaryPersistEvicted), Type: TypeBool, AllowEmpty: true,
+		SetGlobal: func(_ context.Context, s *SessionVars, val string) error {
+			return stmtsummaryv2.SetPersistEvicted(TiDBOptOn(val))
+		}},
+	{Scope: ScopeGlobal, Name: TiDBStmtSummaryGroupByUser, Value: BoolToOnOff(DefTiDBStmtSummaryGroupByUser), Type: TypeBool, AllowEmpty: true,
+		SetGlobal: func(_ context.Context, s *SessionVars, val string) error {
+			return stmtsummaryv2.SetGroupByUser(TiDBOptOn(val))
+		}},
 	{Scope: ScopeGlobal, Name: TiDBCapturePlanBaseline, Value: DefTiDBCapturePlanBaseline, Type: TypeBool, AllowEmptyAll: true},
 	{Scope: ScopeGlobal, Name: TiDBEvolvePlanTaskMaxTime, Value: strconv.Itoa(DefTiDBEvolvePlanTaskMaxTime), Type: TypeInt, MinValue: -1, MaxValue: math.MaxInt64},
 	{Scope: ScopeGlobal, Name: TiDBEvolvePlanTaskStartTime, Value: DefTiDBEvolvePlanTaskStartTime, Type: TypeTime},

pkg/sessionctx/variable/tidb_vars.go

@@ -667,6 +667,12 @@ const (
 	// TiDBStmtSummaryMaxSQLLength indicates the max length of displayed normalized sql and sample sql.
 	TiDBStmtSummaryMaxSQLLength = "tidb_stmt_summary_max_sql_length"
 
+	// TiDBStmtSummaryPersistEvicted controls whether per-record LRU evictions are persisted to the statement summary log.
+	TiDBStmtSummaryPersistEvicted = "tidb_stmt_summary_persist_evicted"
+
+	// TiDBStmtSummaryGroupByUser indicates whether statement summaries are grouped by executing user.
+	TiDBStmtSummaryGroupByUser = "tidb_stmt_summary_group_by_user"
+
 	// TiDBIgnoreInlistPlanDigest enables TiDB to generate the same plan digest with SQL using different in-list arguments.
 	TiDBIgnoreInlistPlanDigest = "tidb_ignore_inlist_plan_digest"
 
@@ -1510,6 +1516,8 @@ const (
 	DefTiDBStmtSummaryHistorySize                     = 24
 	DefTiDBStmtSummaryMaxStmtCount                    = 3000
 	DefTiDBStmtSummaryMaxSQLLength                    = 4096
+	DefTiDBStmtSummaryPersistEvicted                  = false
+	DefTiDBStmtSummaryGroupByUser                     = false
 	DefTiDBCapturePlanBaseline                        = Off
 	DefTiDBIgnoreInlistPlanDigest                     = true
 	DefTiDBEnableIndexMerge                           = true

pkg/util/stmtsummary/BUILD.bazel

@@ -40,7 +40,7 @@ go_test(
     ],
     embed = [":stmtsummary"],
     flaky = True,
-    shard_count = 24,
+    shard_count = 26,
     deps = [
         "//pkg/meta/model",
         "//pkg/parser/auth",

pkg/util/stmtsummary/evicted_test.go

@@ -50,7 +50,7 @@ func newInduceSsbde(beginTime int64, endTime int64) *stmtSummaryByDigestElement
 // generate new StmtDigestKey and stmtSummaryByDigest
 func generateStmtSummaryByDigestKeyValue(schema string, beginTime int64, endTime int64) (*StmtDigestKey, *stmtSummaryByDigest) {
 	key := &StmtDigestKey{}
-	key.Init(schema, "", "", "", "")
+	key.Init(schema, "", "", "", "", "")
 	value := newInduceSsbd(beginTime, endTime)
 	return key, value
 }
@@ -189,7 +189,7 @@ func TestSimpleStmtSummaryByDigestEvicted(t *testing.T) {
 	require.Equal(t, "{begin: 8, end: 9, count: 1}, {begin: 5, end: 6, count: 1}, {begin: 2, end: 3, count: 1}", getAllEvicted(ssbde))
 
 	evictedKey = &StmtDigestKey{}
-	evictedKey.Init("b", "", "", "", "")
+	evictedKey.Init("b", "", "", "", "", "")
 	ssbde.AddEvicted(evictedKey, evictedValue, 4)
 	require.Equal(t, "{begin: 8, end: 9, count: 2}, {begin: 5, end: 6, count: 2}, {begin: 2, end: 3, count: 2}, {begin: 1, end: 2, count: 1}", getAllEvicted(ssbde))