Refine FlushRegion reasons and propagate through the request path

[WenyXu]

What type of enhancement is this?

Tech debt reduction, Refactor

What does the enhancement do?

Currently, flush requests triggered via FlushRegion end up as a generic Manual reason on the datanode side. This makes it impossible to distinguish the source of a flush.
Examples:

• Flush triggered by metasrv WAL prune
• Flush triggered by region migration (pre-flush before downgrade leader)
• Flush triggered by repartition path

Relevant code today:

• src/store-api/src/region_request.rs: RegionFlushRequest has no reason field
• src/mito2/src/worker/handle_flush.rs: defaults to FlushReason::Manual for requests

Problem

• Logs/metrics cannot identify the actual flush source
• Future optimizations (timeouts, retry policy, priority) lack semantic input

Desired outcome

Introduce more granular flush reasons and carry them through the request pipeline:

• Flush triggered by metasrv WAL prune
• Flush triggered by region migration pre-flush (downgrade leader)
• Flush triggered by repartition path
• Preserve manual/user-triggered flush

Proposed approach

1. Add a reason field to flush requests:
   • api::v1::region::FlushRequest
   • store_api::region_request::RegionFlushRequest
2. Extend or map to a richer flush reason enum (reuse mito2::FlushReason or add a mapping layer)
3. Set the reason at metasrv or caller when sending flush:
   • region migration pre-flush (src/meta-srv/src/procedure/region_migration/flush_leader_region.rs)
   • metasrv WAL prune (entry point TBD)
   • repartition flow (entry point TBD)
4. Use the incoming reason in datanode handling (src/mito2/src/worker/handle_flush.rs)
5. Update logs/metrics/tests accordingly

Acceptance criteria

• Flush logs show distinct reasons (not all Manual)
• region migration pre-flush, metasrv WAL prune, and repartition are distinguishable
• Manual/user-triggered flush behavior remains unchanged
• Relevant tests updated and passing

Implementation challenges

No response

[swaploard]

Hi @WenyXu, I have located the triggers for flush, and I am working on implementation. Can you assign me the issue?

[WenyXu]

Hi @WenyXu, I have located the triggers for flush, and I am working on implementation. Can you assign me the issue?

have fun

[QuakeWang]

@WenyXu Hi, I’d like to work on this issue.

After reading the current flush paths, my understanding is that the main gap is that meta-triggered FlushRegions instructions lose their source on the datanode side and become plain RegionFlushRequests, so mito2 usually falls back to Manual.

My planned scope is to add a flush source/reason to FlushRegions, propagate it through the datanode heartbeat flush handler into RegionFlushRequest, and map it to mito2::FlushReason. I’ll cover region migration pre-flush, repartition-triggered flushes, and remote-WAL/replay-size triggered async flushes, while keeping manual/user flush unchanged.

Before I start, could you confirm:

1. Should this PR also update api::v1::region::FlushRequest in greptime-proto, or is focusing on the FlushRegions instruction path enough?
2. What name do you prefer for the remote-WAL related async flush reason: WalPrune, RemoteWalPrune, or something else?

[WenyXu]

Hi @QuakeWang,

1. I think we can now focus on the FlushRegions instruction path.
2. RemoteWalPrune looks good to me.