[None][feat] KVCacheManagerV2: suspend/resume observability stat + coverage#16710
Open
eopXD wants to merge 1 commit into
Open
[None][feat] KVCacheManagerV2: suspend/resume observability stat + coverage#16710eopXD wants to merge 1 commit into
eopXD wants to merge 1 commit into
Conversation
eopXD
requested review from
BowenFu,
QiJune,
VALLIS-NERIA,
ZhanruiSunCh,
asfiyab-nvidia,
crazydemo,
tburt-nv,
thorjohnsen,
tongyuantongyu and
yingguo-trt
July 22, 2026 05:16
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (9)
🚧 Files skipped from review as they are similar to previous changes (8)
WalkthroughKV cache manager v2 now records suspend/resume transitions as per-iteration counters, exposes them in iteration reports, serializes them as top-level statistics, and validates reporting, reset behavior, and contended KV-cache correctness. ChangesKV cache suspend/resume statistics
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant _KVCache
participant KVCacheManager
participant KVCacheManagerV2
participant BaseWorker
_KVCache->>KVCacheManager: record suspend/resume transition
KVCacheManagerV2->>KVCacheManager: get_and_reset_iteration_suspend_resume_stats()
KVCacheManager-->>KVCacheManagerV2: suspended and resumed counts
KVCacheManagerV2->>BaseWorker: serialize iteration counters
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py (1)
818-892: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winGood coverage of report/reset/disabled paths — consider adding a failed-resume case.
All three new tests use the default
max_util_for_resume=1.0, soresume()always succeeds. There's no test assertingresumed_requestsstays unincremented whenresume()is refused (e.g. by setting a lowmax_util_for_resumeand driving GPU utilization above it before resuming). Since this counter exists specifically to signal that the preemption state machine "genuinely fired" (per the integration test's own rationale), a silent regression that increments the counter on a failed resume would be exactly the kind of bug this feature is meant to catch, yet nothing here tests it.🤖 Prompt for 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. In `@tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py` around lines 818 - 892, Add a failed-resume test alongside test_suspend_resume_iteration_stats_are_reported using a manager configured with a low max_util_for_resume and GPU utilization above that threshold before calling resume. Assert resume is refused, the cache remains suspended, suspended_requests increments, and resumed_requests remains 0 in get_iteration_stats.
🤖 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 `@tests/integration/defs/accuracy/test_llm_api_pytorch.py`:
- Around line 5196-5369: Register TestGPTOSS::test_w4_1gpu_suspend_resume in the
appropriate inspected integration test-list files under the QA and test-db
configurations, following the existing syntax and placement conventions for
accuracy tests. Ensure the new test is included in the relevant GPU suites so it
is scheduled and counted for coverage.
---
Nitpick comments:
In `@tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py`:
- Around line 818-892: Add a failed-resume test alongside
test_suspend_resume_iteration_stats_are_reported using a manager configured with
a low max_util_for_resume and GPU utilization above that threshold before
calling resume. Assert resume is refused, the cache remains suspended,
suspended_requests increments, and resumed_requests remains 0 in
get_iteration_stats.
🪄 Autofix (Beta)
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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 1ce9b0bb-83d7-4c13-bc9b-5bcd1b1d66b9
📒 Files selected for processing (8)
tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.pytensorrt_llm/_torch/pyexecutor/kv_cache_stats.pytensorrt_llm/runtime/kv_cache_manager_v2/__init__.pyitensorrt_llm/runtime/kv_cache_manager_v2/_core/_kv_cache.pytensorrt_llm/runtime/kv_cache_manager_v2/_core/_kv_cache_manager.pytests/integration/defs/accuracy/test_llm_api_pytorch.pytests/unittest/executor/test_stats_serializer.pytests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py
eopXD
force-pushed
the
kvcv2-suspend-resume-stat
branch
2 times, most recently
from
July 22, 2026 05:30
62284ae to
01825e4
Compare
Contributor
There was a problem hiding this comment.
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 `@tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py`:
- Around line 818-837: Annotate all newly introduced functions: in
tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py:818-837,
add the precise existing type for resource_guard and annotate the test/helper
return types; in tests/unittest/executor/test_stats_serializer.py:429, add a ->
None return annotation; in
tests/integration/defs/accuracy/test_llm_api_pytorch.py:5196-5266, annotate the
test and both local helpers with parameter and return types.
🪄 Autofix (Beta)
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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 656700ec-6028-479e-9d31-7da1ff322988
📒 Files selected for processing (8)
tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.pytensorrt_llm/_torch/pyexecutor/kv_cache_stats.pytensorrt_llm/runtime/kv_cache_manager_v2/__init__.pyitensorrt_llm/runtime/kv_cache_manager_v2/_core/_kv_cache.pytensorrt_llm/runtime/kv_cache_manager_v2/_core/_kv_cache_manager.pytests/integration/defs/accuracy/test_llm_api_pytorch.pytests/unittest/executor/test_stats_serializer.pytests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py
🚧 Files skipped from review as they are similar to previous changes (3)
- tensorrt_llm/_torch/pyexecutor/kv_cache_stats.py
- tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py
- tensorrt_llm/runtime/kv_cache_manager_v2/_core/_kv_cache_manager.py
…verage Add a Python-only per-iteration suspend/resume (preemption) observability counter to KVCacheManagerV2 -- iterSuspendedRequests / iterResumedRequests, surfaced via get_stats() Signed-off-by: Yueh-Ting Chen <yuehtingc@nvidia.com>
eopXD
force-pushed
the
kvcv2-suspend-resume-stat
branch
from
July 22, 2026 05:41
01825e4 to
a83f909
Compare
Collaborator
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #60902 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #60902 [ run ] completed with state
|
BowenFu
approved these changes
Jul 23, 2026
BowenFu
left a comment
BowenFu
left a comment
There was a problem hiding this comment.
Purely additive suspend/resume observability: counters increment after the completed state transition, guarded by _should_record_stats() (default off), no change to logic/return values/hot path. LGTM.
Collaborator
|
[by Codex] @VALLIS-NERIA Could you please review this PR? Thank you! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Dev Engineer Review
KVCacheManagerV2(iterSuspendedRequests/iterResumedRequests) gated by_should_record_stats(), incremented onsuspend()/resume()transitions, and drained once per iteration.KVCacheV2IterationStatsReport+ serializer export so the counters surface as top-level keys inllm.get_stats()(not nested per pool-group).KVCacheManagerfor recording/reading iteration suspend/resume counters (record_suspended_request,record_resumed_request,get_and_reset_iteration_suspend_resume_stats) with matching typed stubs intensorrt_llm/runtime/kv_cache_manager_v2/__init__.pyi.kvCacheIterationStatsByPoolGroup).Potential review points
suspend()/resume()calls that don’t change the cache state).QA Engineer Review
Test changes (functions added/updated):
tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.pytest_suspend_resume_iteration_stats_are_reportedtests/unittest/executor/test_stats_serializer.pytest_serializer_emits_v2_suspend_resume_counterstests/integration/defs/accuracy/test_llm_api_pytorch.pytest_w4_1gpu_suspend_resume(TestGPTOSS)Coverage in CI test lists (tests/integration/test_lists):
tests/integration/test_lists/test-db/l0_b200.ymll0_b200: addedaccuracy/test_llm_api_pytorch.py::TestGPTOSS::test_w4_1gpu_suspend_resumeVerdict: needs follow-up
Description
Adds a Python-only per-iteration suspend/resume (preemption) observability counter to
KVCacheManagerV2—iterSuspendedRequests/iterResumedRequests, surfaced as top-level iteration keys viallm.get_stats()— together with the tests that exercise it.V2's active-request suspend/resume state machine (
ACTIVE → SUSPENDED → resume, with host page-index reconnect via_restore_page_index_bufs) previously had no statistic or log, so a black-box test could not confirm it fired. Offload/onboard bytes are the wrong proxy:suspend()keeps HELD pages on GPU and only lazily offloads under further pressure, soiterOffloadBytes/iterOnboardBytescan be0while suspend/resume still fired.Implementation mirrors the #15633 offload/onboard per-iteration counters — no C++/nanobind change:
_KVCache.suspend()and on a successfulresume(), gated on_should_record_stats().KVCacheV2IterationStatsReportand emitted as top-leveliterSuspendedRequests/iterResumedRequestsin the serialized stats (sibling tokvCacheIterationStats, not per pool group — suspend/resume is a whole-request event).Additive stats-dict key only;
tests/unittest/api_stabilityis unaffected (no public API signature change).Test Coverage
tests/unittest/kv_cache_manager_v2_tests/test_kv_cache_stats_behavior.py: the counters increment on suspend+resume, reset each iteration, and are suppressed when stats are disabled (model-free, deterministic).tests/unittest/executor/test_stats_serializer.pytests/integration/defs/accuracy/test_llm_api_pytorch.py::TestGPTOSS::test_w4_1gpu_suspend_resume— the V2-only round trip on GPT-OSS-120B (TP=1); gates oniterSuspendedRequests>0 and iterResumedRequests>0, no crash/deadlock (all requests complete non-empty), and a ≥3-token deterministic prefix vs the uncontended single-request reference.Verified on the rc21 build (main
ef6ebc2f2c+ #15633): unit 20/20; I-10suspended=31 / resumed=35, offload/onboard=0, common-prefix17/11/19/8;api_stability64/64. The unit tests are model-free and base-insensitive. Note: I-10's pool/generation sizing was tuned on rc21 and has not yet been re-run on current main — the resume-utilization change (#16484) can shift when suspension fires; aNOTEin the test documents the retune path if the gate-(2) counters come back0.PR Checklist
Please review the following before submitting your PR:
PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.
PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.
Test cases are provided for new code paths (see test instructions)
If PR introduces API changes, an appropriate PR label is added - either
api-compatibleorapi-breaking. Forapi-breaking, includeBREAKINGin the PR title.Any new dependencies have been scanned for license and vulnerabilities
CODEOWNERS updated if ownership changes
Documentation updated as needed
Update tava architecture diagram if there is a significant design change in PR.
The reviewers assigned automatically/manually are appropriate for the PR.
Please check this after reviewing the above items as appropriate for this PR.
GitHub Bot Help
To see a list of available CI bot commands, please comment
/bot help.