columnar hub: share process-global ColumnarMetaCache across snaps

[JaySon-Huang]

What problem does this PR solve?

Issue Number: close #11021

Problem Summary:

On disagg columnar CN Hub, each snap historically constructed its own ColumnarMetaCache via ColumnarMetaCache::default() (mem_limit/500 per snap). Concurrent region snaps therefore held independent meta caches, amplifying TableMeta memory even when keys (file_id, table_id) overlap. This diverges from WN's process-global meta cache.

What is changed and how it works?

columnar hub: share ColumnarMetaCache at CloudHelper and size it at mem/500

• Keep one ColumnarMetaCache on CloudHelper and clone() it into each SnapCtx (same pattern as columnar_file_cache / other process-global caches).
• Size the shared cache at SysQuota::memory_limit_in_bytes() / 500 (~0.2% of process memory). Per-snap default() used mem/500 each.
• Does not include contrib/cloud-storage-engine weight/metrics changes; those can land separately.

Check List

Tests

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

Manual test (lab CN tiflash-5035 / 5036, table widecol.widecol_test_wide_500gb):

1. Case 1 (N=1 large range) and Case 6 (N=4 disjoint ranges) from CN Hub creates per-snap ColumnarMetaCache, amplifying TableMeta memory under disagg columnar #11021.
2. Per-snap baseline: Σ reported_size_bytes ≈ 1.2GB for ~5070 parses while last-instance weighted_size / entries only reflected one snap (~7MiB / ~30).
3. Shared + small cap (64MiB) experiment: process-level gauges (weighted≈cap, same entries on both CNs) and thrash (parse ≫ unique files).

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

columnar hub: share one process-global ColumnarMetaCache across snaps to avoid per-snap TableMeta memory amplification

Summary by CodeRabbit

Performance Improvements

• Improved columnar data access by sharing metadata caching across readers and snapshot operations.
• Cache capacity now adapts to the configured memory limit, reducing repeated metadata loading and supporting more efficient memory usage.

Observability

• Added clearer status information when heap profiling is activated or deactivated.
• Expanded Grafana monitoring with columnar storage metrics for cache usage, remote reads, prefetching, snapshots, memory waits, and read duration.
• Improved dashboard defaults for monitoring columnar storage activity.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

CloudHelper now owns one ColumnarMetaCache sized from the system memory limit and shares it across columnar snapshot operations. The dashboard adds columnar storage metrics and changes several display defaults. Runtime logging and build flags also change.

Changes

Columnar metadata cache sharing

Layer / File(s)	Summary
Cache initialization contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs, contrib/tiflash-columnar-hub/hub-runtime/src/run.rs	CloudHelper creates and stores a ColumnarMetaCache with capacity set to memory_limit / 500. The code documents process-lifetime reuse.
Snapshot cache propagation contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs	Columnar reader creation, shared-snapshot loading, leader snapshot requests, and SnapCtx use the shared cache.
Runtime logging and build support contrib/tiflash-columnar-hub/hub-runtime/src/status_server.rs, contrib/tiflash-proxy-cmake/CMakeLists.txt	Heap-profile activation and deactivation are logged. Next-generation columnar LLVM builds add -A deprecated to TIFLASH_RUSTFLAGS.
Columnar Storage dashboard metrics/grafana/tiflash_summary.json	The dashboard adds columnar storage panels, shifts existing rows and panels, disables automatic refresh, selects template options by default, and uses a fixed time range.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CloudHelper
  participant ColumnarReader
  participant SharedSnapshot
  participant SnapCtx
  CloudHelper->>ColumnarReader: provide shared ColumnarMetaCache
  ColumnarReader->>SharedSnapshot: pass shared ColumnarMetaCache
  SharedSnapshot->>SnapCtx: pass shared ColumnarMetaCache
  SharedSnapshot->>SnapCtx: pass shared cache to leader requests

Loading

Possibly related PRs

• pingcap/tiflash#10988: This PR also changes columnar metadata cache handling in cloud_helper.rs.

Suggested reviewers: yongman

Poem

A rabbit shares one cache today,
Snapshots follow the same clear way.
Heap status hops into the log,
Build warnings rest beneath the fog.
Columnar metrics line the way.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The Grafana dashboard adds broad panels and changes refresh, variables, and time settings beyond the linked cache objective.	Move the broad dashboard changes to a separate PR, or document their direct purpose and need for this cache fix.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: sharing a process-global ColumnarMetaCache across snapshots.
Description check	✅ Passed	The description covers the problem, implementation, issue number, manual testing, side effects, documentation, and release note.
Linked Issues check	✅ Passed	The changes implement the linked issue objective by sharing and sizing one process-global ColumnarMetaCache across snaps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs`:
- Around line 392-395: Update the process-global cache initialization using
SysQuota::memory_limit_in_bytes() so ColumnarMetaCache::new receives mem_limit
divided by 50 instead of 500, and revise the adjacent comment to document the
/50 capacity requirement.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3e7f74ff-b43f-4b84-8ac6-0353aa03ecd3

📥 Commits

Reviewing files that changed from the base of the PR and between fd0d7d3 and a55ae19.

📒 Files selected for processing (1)

• contrib/tiflash-columnar-hub/hub-runtime/src/cloud_helper.rs

[JaySon-Huang]

/cherry-pick release-nextgen-202603

[ti-chi-bot]

@JaySon-Huang: once the present PR merges, I will cherry-pick it on top of release-nextgen-202603 in the new PR and assign it to you.

Details

In response to this:

/cherry-pick release-nextgen-202603

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.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@metrics/grafana/tiflash_summary.json`:
- Around line 9147-9161: Update the legendFormat values for the cache-hit and
cache-miss queries in panel 381 to include the grouped {{type}} label alongside
{{$additional_groupby}}. Apply the same legend change to the corresponding
queries in panels 382, 386, and 387; alternatively, remove type from each by
(...) clause only if it is not meaningful for those metrics.
- Around line 9611-9638: Update the histogram_quantile expressions in the
cache-hit panel to query the registered COLUMNAR_PREFETCH_CACHE_HIT_HISTOGRAM
metric name, including its bucket suffix, instead of
tiflash_proxy_kv_engine_columnar_prefetch_cache_hit_bucket. Apply the corrected
metric name consistently to refs A, B, and C while preserving their existing
filters and quantiles.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b95622e9-05f9-455b-bb7a-aa52d8177457

📥 Commits

Reviewing files that changed from the base of the PR and between 3f47842 and 6ebc2ba.

📒 Files selected for processing (1)

• metrics/grafana/tiflash_summary.json

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: JinheLin, yongman

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 [JinheLin,yongman]

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-08-07 15:38:36.014846178 +0000 UTC m=+2801702.050941224: ☑️ agreed by yongman.
• 2026-08-08 13:03:18.157871888 +0000 UTC m=+2878784.193966945: ☑️ agreed by JinheLin.

[JaySon-Huang]

/test pull-integration-test

[JaySon-Huang]

/test pull-integration-test

[ti-chi-bot]

@JaySon-Huang: 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
pull-sanitizer-tsan	a83cdcd	link	false	/test pull-sanitizer-tsan

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.

[JaySon-Huang]

/test pull-integration-test

[JaySon-Huang]

/test pull-integration-test

[ti-chi-bot]

@JaySon-Huang: new pull request created to branch release-nextgen-202603: #11024.

Details

In response to this:

/cherry-pick release-nextgen-202603

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.