executor, variable: support cop_mvcc_read_amplification to trigger printing slow log (#66064)

[ti-chi-bot]

This is an automated cherry-pick of #66064

What problem does this PR solve?

Issue Number: close #48947, related #62959

Problem Summary:
tidb_slow_log_rules supports multi-dimensional triggering, but it cannot trigger by MVCC read amplification (total_keys / processed_keys). This PR adds a dedicated rule item to support that use case.

What changed and how does it work?

Add new slow log rule field:

• cop_mvcc_read_amplification

Behavior:

• Parse as float64.
• Match condition: Total_keys / Process_keys >= threshold.
• For non-computable cases (ScanDetail == nil or ProcessedKeys <= 0), use stable scheme A:
  • only match when threshold == 0.

Code changes:

• Add new field constant and accessor in pkg/sessionctx/variable/slow_log.go.
• Keep existing slow-log matching pipeline unchanged (PrepareSlowLogItemsForRules / ShouldWriteSlowLog), new field works through existing accessor mechanism.

Check List

Tests

• Unit test
• Integration test
• Manual test (add detailed scripts or steps below)
• No need to test

  • I checked and no code files have been changed.

Side effects

• Performance regression: Consumes more CPU
• Performance regression: Consumes more Memory
• Breaking backward compatibility

Documentation

• Affects user behaviors
• Contains syntax changes
• Contains variable changes
• Contains experimental features
• Changes MySQL compatibility

Release note

Please refer to Release Notes Language Style Guide to write a quality release note.

Support `cop_mvcc_read_amplification` in `tidb_slow_log_rules`, allowing slow-log triggering by `Total_keys / Process_keys` (with `ProcessedKeys <= 0` only matching threshold `0`).

Summary by CodeRabbit

• New Features

  • Added a slow query log metric "cop_mvcc_read_amplification" to monitor MVCC read amplification.

• Improvements

  • Strengthened validation for slow-log threshold values (non-negative, finite) and safer handling when scan details are missing or zero.

• Tests

  • Expanded tests covering parsing, threshold edge cases, and behavior of the new metric.

[ti-chi-bot]

@zimulala This PR has conflicts, I have hold it.
Please resolve them or ask others to resolve them, then comment /unhold to remove the hold label.

[ti-chi-bot]

@ti-chi-bot: ## If you want to know how to resolve it, please read the guide in TiDB Dev Guide.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository.

[tiprow]

@ti-chi-bot: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
fast_test_tiprow_for_release	9dec7f6	link	true	/test fast_test_tiprow_for_release

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 095a2d6b-e950-4bc0-afef-95f29ff46945

📥 Commits

Reviewing files that changed from the base of the PR and between 373e060 and 8b8dbc9.

📒 Files selected for processing (2)

• pkg/sessionctx/variable/slow_log.go
• pkg/sessionctx/variable/slow_log_test.go

---

📝 Walkthrough

Walkthrough

Adds a new slow-log rule field cop_mvcc_read_amplification that computes TotalKeys/ProcessedKeys from ExecDetails.ScanDetail and integrates parsing, validation, and matching logic plus tests covering thresholds and edge cases.

Changes

Cohort / File(s)	Summary
Core implementation pkg/sessionctx/variable/slow_log.go	Add SlowLogCopMVCCReadAmplification constant; register a field accessor that parses float thresholds, validates finiteness/non-negativity, and computes TotalKeys/ProcessedKeys from ExecDetails.ScanDetail with guards for nil/zero.
Tests – executor adapter pkg/executor/adapter_test.go	Add assertions and a subtest to verify matching behavior for amplification thresholds around 0.49/0.5 and session rule scenarios using ScanDetail (TotalKeys/ProcessedKeys).
Tests – slow_log parsing/matching pkg/sessionctx/variable/slow_log_test.go	Extend tests to include the new field (accessors count increment), parsing validation for non-negative/finite values, matching scenarios with/without ExecDetails/ScanDetail, and edge cases (zero/invalid keys).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• *: parse and match slow log trigger rules for multi-dimensional triggering (#63132) #66582: Introduced the slow-log rule concept expansion to detect inefficient queries via TiKV scan/process ratios (related feature scope).
• *: add a variable for dynamic slow log trigger rules with global (supporting ConnID-specific) and session scope (#63779) #66630: Modifies slow-log field accessors and tests; directly related to adding field parsing/matching logic.
• *: add the Rewrite_time as a slow log rule (#65086) #66829: Adds a different slow-log field accessor and test updates in the same framework (similar integration pattern).

Suggested labels

size/M, approved, lgtm

Suggested reviewers

• XuHuaiyu
• yibin87
• yudongusa

Poem

🐰
I nibble through the scan and keys,
Counting echoes in the leaves,
When processed shrinks and scanned expands,
I twirl my whiskers, mark the lands,
Inefficiency—exposed by my hands.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding support for cop_mvcc_read_amplification to trigger slow log printing.
Description check	✅ Passed	The description follows the template structure with issue numbers, problem summary, changes explanation, test checkbox completion, and release notes provided.
Linked Issues check	✅ Passed	The PR successfully implements the objective from issue #48947 by adding cop_mvcc_read_amplification field to support inefficient query detection based on scanned/processed entry ratios.
Out of Scope Changes check	✅ Passed	All changes are within scope: new slow-log field constant, field accessor with parsing/matching logic, comprehensive unit tests, and supporting validation functions for float64 parsing.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

Error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions
The command is terminated due to an error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

pkg/sessionctx/variable/slow_log.go (1)

193-194: Document the zero-threshold fallback on the exported field.

cop_mvcc_read_amplification now has a non-obvious contract: missing ScanDetail or ProcessedKeys <= 0 only matches threshold 0. Please capture that on the exported comment so callers do not have to read the matcher to understand the SQL-visible behavior.

As per coding guidelines, "Comments SHOULD explain non-obvious intent, constraints, invariants, concurrency guarantees, SQL/compatibility contracts, or important performance trade-offs" and "Keep exported-symbol doc comments, and prefer semantic constraints over name restatement."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/sessionctx/variable/slow_log.go` around lines 193 - 194, Update the
exported doc comment for SlowLogCopMVCCReadAmplification to state its
non-obvious contract: when the ScanDetail is nil/missing or
ScanDetail.ProcessedKeys <= 0, the matcher treats the amplification as matching
only threshold 0 (i.e., there is a zero-threshold fallback), and otherwise it
computes total_keys/processed_keys; reference ScanDetail and ProcessedKeys in
the comment so callers understand the SQL-visible behavior without inspecting
the matcher implementation.

pkg/executor/adapter_test.go (1)

145-146: Add one case where this is the only effective field.

These assertions prove the matcher, but they still don't cover lazy preparation for the new accessor: the earlier prep test gets items.ExecDetail from Process_time, and this subtest pre-populates items.ExecDetail manually. A small case with only cop_mvcc_read_amplification in the effective field set would cover the actual integration point.

Also applies to: 341-357

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/executor/adapter_test.go` around lines 145 - 146, Add a subtest that
exercises lazy preparation by making cop_mvcc_read_amplification the only
effective field: use
variable.SlowLogRuleFieldAccessors[strings.ToLower(variable.SlowLogCopMVCCReadAmplification)]
and call Match with a items value whose ExecDetail is either nil or manually
populated, and with the effective field set containing only
"cop_mvcc_read_amplification"; assert True for value < 0.5 and False for >= 0.5
to prove the accessor works when it is the sole effective field and triggers the
lazy ExecDetail prep path. Ensure you reference Match,
SlowLogCopMVCCReadAmplification, variable.SlowLogRuleFieldAccessors and
items.ExecDetail in the test.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@pkg/executor/adapter_test.go`:
- Around line 145-146: Add a subtest that exercises lazy preparation by making
cop_mvcc_read_amplification the only effective field: use
variable.SlowLogRuleFieldAccessors[strings.ToLower(variable.SlowLogCopMVCCReadAmplification)]
and call Match with a items value whose ExecDetail is either nil or manually
populated, and with the effective field set containing only
"cop_mvcc_read_amplification"; assert True for value < 0.5 and False for >= 0.5
to prove the accessor works when it is the sole effective field and triggers the
lazy ExecDetail prep path. Ensure you reference Match,
SlowLogCopMVCCReadAmplification, variable.SlowLogRuleFieldAccessors and
items.ExecDetail in the test.

In `@pkg/sessionctx/variable/slow_log.go`:
- Around line 193-194: Update the exported doc comment for
SlowLogCopMVCCReadAmplification to state its non-obvious contract: when the
ScanDetail is nil/missing or ScanDetail.ProcessedKeys <= 0, the matcher treats
the amplification as matching only threshold 0 (i.e., there is a zero-threshold
fallback), and otherwise it computes total_keys/processed_keys; reference
ScanDetail and ProcessedKeys in the comment so callers understand the
SQL-visible behavior without inspecting the matcher implementation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5c836734-bf81-4572-b2a8-be64e7ff788b

📥 Commits

Reviewing files that changed from the base of the PR and between 489dac3 and 373e060.

📒 Files selected for processing (3)

• pkg/executor/adapter_test.go
• pkg/sessionctx/variable/slow_log.go
• pkg/sessionctx/variable/slow_log_test.go

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (release-8.5@489dac3). Learn more about missing BASE report.

Additional details and impacted files

@@               Coverage Diff                @@
##             release-8.5     #66232   +/-   ##
================================================
  Coverage               ?   55.2396%           
================================================
  Files                  ?       1821           
  Lines                  ?     654195           
  Branches               ?          0           
================================================
  Hits                   ?     361375           
  Misses                 ?     266220           
  Partials               ?      26600           

Flag	Coverage Δ
integration	38.4382% <0.0000%> (?)
unit	65.2627% <100.0000%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
dumpling	52.9954% <0.0000%> (?)
parser	∅ <0.0000%> (?)
br	55.6647% <0.0000%> (?)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yibin87]

LGTM

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: XuHuaiyu, yibin87

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [XuHuaiyu]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-03-12 06:40:37.353836117 +0000 UTC m=+505068.865893778: ☑️ agreed by yibin87.
• 2026-03-12 06:51:59.283416189 +0000 UTC m=+505750.795473840: ☑️ agreed by XuHuaiyu.

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/unhold

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest

[zimulala]

/retest