Skip to content

[manager] move EventReport cleanup into background GC - #281

Open
shaohuaxi wants to merge 1 commit into
mainfrom
rc/feat/event-report-gc-cleanup
Open

[manager] move EventReport cleanup into background GC#281
shaohuaxi wants to merge 1 commit into
mainfrom
rc/feat/event-report-gc-cleanup

Conversation

@shaohuaxi

@shaohuaxi shaohuaxi commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator

Background

EventReport currently schedules an instance-wide metadata scan after every successful Snapshot and HOST_DOWN/liveness cleanup. Repeated events can therefore multiply full scans and compete with deletion and migration work in the shared executor.

This PR builds on #244 and moves those cleanup paths into the resident background GC. EventReport events register or advance cleanup intents; GC merges compatible intents and reconciles them with bounded per-instance scans.

Changes

  • Add an EventReport intent lane for stale Snapshot generations, explicit HOST_DOWN, liveness cleanup, and post-recovery absent reporters.
  • Merge repeated intents by instance, storage type, and reporter/host, while scanning each instance keyspace once per pass.
  • Preserve Snapshot committed/in-flight generation, attempt epoch, reporter lifecycle generation, and backend incarnation fencing.
  • Perform metadata-only expected-value compare-delete; EventReport cleanup never issues a physical storage DELETE.
  • Add no-touch/no-backfill maintenance reads, cached-metadata recovery gating, exact hot/persistent accounting, and retry-safe usage/key-count settlement.
  • Bound metadata mutation impact to one key/shard at a time and expose scan, backlog, retry, action latency, and shard-lock wait/hold metrics.
  • Harden shutdown callbacks, intent cancellation, interrupted-pass completion, and recovery discovery behavior.
  • Document the architecture, failure semantics, observability, and rollout boundaries.

Correctness boundaries

  • Cleanup remains strictly instance-isolated.
  • Missing, malformed, unavailable, or changed metadata fails closed.
  • A re-registered reporter or a newer Snapshot/lifecycle invalidates older cleanup work.
  • Full expected Location values are checked again immediately before deletion.
  • Ordinary WRITING/SERVING GC and SchedulePlanExecutor physical deletion behavior are unchanged.

Dependency

This is the second layer of a stacked change and depends on #244.

Stack created with GitHub Stacks CLIGive Feedback 💬

@shaohuaxi shaohuaxi changed the title rc/feat/event report gc cleanup [manager] move EventReport cleanup into background GC Aug 10, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8770c29720

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/meta/meta_storage_backend_manager.cc Outdated
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated

@qoderai qoderai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Summary

Reviewed PR #281 (EventReport active cleanup integrated into background scan GC). The design document (docs/design/event_report_background_gc.md) is thorough and well-structured. The intent model, three-state lifecycle lease, per-instance cursor pass, fair scheduling, and maintenance metadata API contracts are clearly documented and faithfully implemented.

Key strengths

  • Intent merge/replace semantics correctly handle event storms (multiple Snapshots/HOST_DOWN collapse into per-Instance passes).
  • Maintenance no-touch reads (ApplyToEntryNoTouch, GetForOneKeyForMaintenance) prevent LRU/access-time pollution — the two-phase ScanLocationsForMaintenance refactor in meta_local_backend.cc is a clean fix for the prior shard-mutex-during-item-read concern.
  • Accounting safety: prior mutation flags are carried across Sync failures (meta_searcher.cc lines 2001-2007) to prevent double-counting, and CommitMaintenanceDeleteAccounting only runs after all hard errors converge.
  • Shutdown ordering (RequestStop → ClearCallbacks → Join → Reset) and fail-closed restart semantics (no persisted generation, intent/cursor discarded) are sound.
  • Test coverage is comprehensive across intent lifecycle, lease states, maintenance delete, metrics, and E2E.

Findings (3 inline comments)

  1. kBusy blocks entire batch (cache_garbage_collector.cc:1263): One busy reporter fails the whole action batch, preventing progress for unrelated reporters. Consider continue + out_revisit_required=true.
  2. kStale early return skips remaining targets (cache_garbage_collector.cc:1275): Inconsistent with BeginEventReportPass (line 973 uses continue). Remaining targets are deferred to a full pass rescan unnecessarily.
  3. String-based metric lookups on hot path (cache_garbage_collector.cc:1506): Event report metrics use GetCounter("cache_gc.event_report_*") per call, unlike the regular GC path which uses cached METRICS_ macros.

All findings are low-to-medium severity — the implementation is functionally correct and the issues are about efficiency and consistency.


🤖 Generated by Qoder

Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@github-actions github-actions Bot added the ai reviewed AI has reviewed this PR label Aug 10, 2026
Base automatically changed from rc/feat/cache-gc-v1 to main August 10, 2026 07:03
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch 2 times, most recently from e2d6708 to 8f48e72 Compare August 10, 2026 07:09

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8f48e72957

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/meta/meta_storage_backend_manager.cc
Comment thread kv_cache_manager/meta/meta_storage_backend_manager.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch 2 times, most recently from 5a0246e to 0939176 Compare August 14, 2026 06:22

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 09391763ac

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/manager/cache_manager.cc Outdated
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch 2 times, most recently from 9a20dbb to 67cfab2 Compare August 15, 2026 07:21

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67cfab2844

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch from 67cfab2 to 879020a Compare August 15, 2026 09:46

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 879020af84

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/meta/meta_storage_backend_manager.cc
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch from 879020a to 50fcbee Compare August 21, 2026 06:52

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50fcbeecd7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch from 50fcbee to 565e0ad Compare August 21, 2026 08:17

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 565e0ad5b0

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch 2 times, most recently from d46cd5e to 403a294 Compare August 21, 2026 08:28

@wangxiyu191 wangxiyu191 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

建议把这部分从事件触发清理改成 GC 按固定频率持续扫描。

Snapshot、HOST_DOWN 等事件只更新 DataStorage 的当前状态,不再向 GC 登记清理任务。GC 扫描到 Location 时,找到对应的 DataStorage,由 DataStorage 判断当前是否需要删除;暂时无法判断就跳过,下一轮再检查。EventReport 和普通 GC 可以在同一轮扫描里处理,不需要分别维护两套扫描流程。

这样可以删掉 Intent map 和 EventReport 专用的调度、扫描状态,整体逻辑会简单很多。后续 DataStorage 的 MightExist 定期检查、TTL 到期回收等需求,也可以直接复用这套扫描流程,只增加各自的判断逻辑,不需要每增加一种清理原因就再做一套事件触发和全表扫描。

@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch from 403a294 to a56b7cc Compare August 27, 2026 05:42

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a56b7cc7a3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/data_storage/event_report_backend.cc Outdated
Comment thread kv_cache_manager/manager/cache_garbage_collector.cc Outdated
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch 2 times, most recently from 8593875 to bf1cd1d Compare August 27, 2026 07:29

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf1cd1d7e4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread kv_cache_manager/meta/meta_indexer.cc
@shaohuaxi
shaohuaxi force-pushed the rc/feat/event-report-gc-cleanup branch from bf1cd1d to be0f937 Compare August 27, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai reviewed AI has reviewed this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants