tikv / tikv/pd

scheduler: use KB-level approximate_size from region heartbeat to improve empty region detection

Open
#10,656 1 comment 0 reactions 0 assignees View on GitHub
contribution type/development
Dominant language
Go
Stars
1.2k
Forks
783
Avg merge
5d 21h
Merged PRs (30d)
36

Description

## Development Task

### Background

PD's `RegionFromHeartbeat` (`pkg/core/region.go:234`) converts `approximate_size` from bytes to MiB via integer division (`heartbeat.GetApproximateSize() / units.MiB`). The balance-region scheduler's `emptyFilter` then blocks any region whose size (in MiB) is `<= EmptyRegionApproximateSize` (which is `1`).

This means any region with less than ~2 MiB of data is considered "empty" and excluded from balancing. For TiKV/RocksDB this rarely matters due to MVCC multi-version inflation, but for CSE (Cloud Storage Engine) which stores data more compactly, legitimately non-empty regions can report sizes well under 1 MiB and be silently excluded from scheduling.

### Proposal

Add an `approximate_size_kb` field (uint64, in KiB) to the `RegionHeartbeatRequest` protobuf. This gives PD KB-level granularity instead of relying on the coarse MiB integer division.

**PD changes:**
1. In `RegionHeartbeatRequest` interface (`pkg/core/region.go`), add `GetApproximateSizeKB() uint64`.
2. In `RegionFromHeartbeat`, prefer `approximate_size_kb` when present:
```go
regionSize := heartbeat.GetApproximateSizeKB()
if regionSize == 0 {
// Fallback: convert bytes to MiB for backward compatibility.
regionSize = heartbeat.GetApproximateSize() / (units.MiB / units.KiB) // in KiB
}
```
3. Change `EmptyRegionApproximateSize` from `1` (MiB) to `1` (KiB), so a region with any real data is never considered empty.
4. Update downstream consumers that read `approximateSize` (API responses, metrics, etc.) to use KiB consistently or convert back to MiB for display.

**kvproto changes:**
- Add `optional uint64 approximate_size_kb = ` to `RegionHeartbeatRequest`.

**TiKV / CSE changes** (see [tidbcloud/cloud-storage-engine#5128](https://github.com/tidbcloud/cloud-storage-engine/issues/5128)):
- Set `approximate_size_kb` in the heartbeat.
- Remove the 2 MiB clamping workaround.

### Related

- CSE companion issue: https://github.com/tidbcloud/cloud-storage-engine/issues/5128
- Stopgap PR: https://github.com/tidbcloud/cloud-storage-engine/pull/4206

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.