Skip to content

[rocm, telemetry] fix: map visible ranks for SMI utilization - #88

Merged
Wangmerlyn merged 2 commits into
mainfrom
codex/rocm-visible-rank-telemetry
Jun 27, 2026
Merged

[rocm, telemetry] fix: map visible ranks for SMI utilization#88
Wangmerlyn merged 2 commits into
mainfrom
codex/rocm-visible-rank-telemetry

Conversation

@Wangmerlyn

@Wangmerlyn Wangmerlyn commented Jun 27, 2026

Copy link
Copy Markdown
Owner

Summary

  • Resolve ROCm visible GPU ranks through ROCR_VISIBLE_DEVICES plus one matching HIP/CUDA overlay before querying ROCm SMI utilization.
  • Keep id/visible_id as start-compatible visible ordinals and add physical_id only when the ROCm SMI index is known.
  • Document the ROCm visible-rank telemetry contract across CLI, Python, API/MCP, architecture, README, AGENTS, and the implementation plan.

Test Plan

  • RED: new no-hardware ROCm tests failed on current code because it queried visible indexes directly and omitted physical_id.
  • PYTHONPATH=$PWD/src pytest tests/rocm_controller tests/utilities/test_gpu_info.py -q (26 passed, 1 skipped)
  • PYTHONPATH=$PWD/src pytest tests -q (235 passed, 11 skipped)
  • PYTHONPATH=$PWD/src mkdocs build (passed with existing Material warning and unlisted plan-page notices)
  • pre-commit run --all-files
  • git diff --check && git diff --cached --check
  • Local subagent review: initial comments resolved; follow-up re-check returned no remaining must-fix findings.

Summary by CodeRabbit

  • New Features

    • Added clearer ROCm GPU visibility handling, including support for visible device ordinals across CUDA and ROCm environments.
    • GPU info now includes physical device IDs when they can be resolved.
  • Bug Fixes

    • Utilization data is now marked unavailable when GPU visibility mappings are ambiguous, invalid, or out of range.
    • GPU selection and telemetry now better match the device users actually see after visibility filtering.
  • Documentation

    • Expanded setup, CLI, API, and troubleshooting docs for CUDA/ROCm visibility masks and GPU ordinal behavior.

@coderabbitai

coderabbitai Bot commented Jun 27, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@Wangmerlyn, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 41 minutes and 2 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0632e811-fdc9-452c-b8b9-d36e9dc20199

📥 Commits

Reviewing files that changed from the base of the PR and between 9bea0d9 and 3c67ce3.

📒 Files selected for processing (3)
  • src/keep_gpu/utilities/gpu_info.py
  • src/keep_gpu/utilities/rocm_visibility.py
  • tests/utilities/test_gpu_info.py
📝 Walkthrough

Walkthrough

Adds rocm_visibility.py implementing resolve_rocm_visible_rank_to_smi_index and rocm_monitor_device_count, which parse ROCR_VISIBLE_DEVICES/HIP_VISIBLE_DEVICES/CUDA_VISIBLE_DEVICES to map visible GPU ranks to physical ROCm SMI indexes. RocmGPUController._query_utilization and gpu_info._query_rocm are updated to use this resolver, returning None/unavailable when mapping fails. Tests and docs are updated throughout.

Changes

ROCm Visible-Rank Telemetry Mapping

Layer / File(s) Summary
rocm_visibility resolver module
src/keep_gpu/utilities/rocm_visibility.py
New module with _parse_numeric_mask, rocm_monitor_device_count, _physical_ids_available, _effective_overlay_mask, and resolve_rocm_visible_rank_to_smi_index. Parses ROCR/HIP/CUDA env vars, validates uniqueness and bounds against monitor count, returns physical SMI index or None.
Wire resolver into controller and gpu_info
src/keep_gpu/single_gpu_controller/rocm_gpu_controller.py, src/keep_gpu/utilities/gpu_info.py
RocmGPUController._query_utilization resolves smi_index via the new helper and returns None when unresolvable. gpu_info._query_rocm resolves physical_id per device, queries utilization by physical index, and conditionally includes physical_id in device records.
Tests
tests/rocm_controller/test_rocm_utilization.py, tests/utilities/test_gpu_info.py
test_rocm_utilization.py rewritten with DummyRocmSMI and env-var mask scenarios covering correct index selection and None returns for invalid/conflicting/malformed masks. test_gpu_info.py adds ROCm mock infrastructure and three new mapping tests.
Docs and plan
docs/plans/rocm-visible-rank-telemetry.md, docs/concepts/architecture.md, docs/reference/api.md, docs/reference/cli.md, docs/guides/*, README.md, AGENTS.md
Plan doc added; architecture, API reference, CLI reference, guides, README, and AGENTS.md updated to describe ROCm visible-rank resolution, overlay semantics, and unavailable-utilization fallback.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • Wangmerlyn/KeepGPU#56: Initial ROCm controller and tests/rocm_controller/test_rocm_utilization.py scaffolding that this PR directly rewrites and extends.
  • Wangmerlyn/KeepGPU#59: Introduced ROCm info querying via rocm_smi in gpu_info.py, the same path this PR refines with visible-rank-to-SMI resolution.
  • Wangmerlyn/KeepGPU#75: Consumes the util is None telemetry signal in busy-threshold backoff logic, which this PR now explicitly produces for unresolvable ROCm mappings.

Poem

🐇 A hop through env vars, ROCR and HIP,
Mapping visible ranks with a numerical grip.
When masks are ambiguous, None is returned—
No guessing at indexes; precision is earned.
The SMI index found, telemetry rings true,
For every ROCm device, the rabbit sees you! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: mapping ROCm visible ranks for SMI utilization.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/rocm-visible-rank-telemetry

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

Comment @coderabbitai help to get the list of available commands.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Code Review

This pull request introduces a robust ROCm visible-rank telemetry resolution mechanism. It adds a new utility module rocm_visibility.py to parse and resolve ROCm visibility environment variables (ROCR_VISIBLE_DEVICES, HIP_VISIBLE_DEVICES, and CUDA_VISIBLE_DEVICES), mapping visible device ranks to physical ROCm SMI indexes. This ensures that keepalive backoff and GPU listing telemetry align correctly with the visible ordinals passed by users. Comprehensive mock-based unit tests have been added to verify various environment configurations, and documentation across the repository has been updated to reflect these changes. I have no feedback to provide as there are no review comments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🧹 Nitpick comments (1)
tests/utilities/test_gpu_info.py (1)

361-365: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert physical_id is omitted when unresolved.

gpu_info._query_rocm only adds physical_id when known, but info.get("physical_id") would also pass if the API started returning "physical_id": None.

Proposed stronger assertion
-    assert [info.get("physical_id") for info in infos] == [None, None]
+    assert all("physical_id" not in info for info in infos)
🤖 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/utilities/test_gpu_info.py` around lines 361 - 365, The ROCm GPU info
test is too weak because `info.get("physical_id")` passes even if `physical_id`
is present with a null value. Update the assertions in `test_gpu_info` for
`gpu_info._query_rocm` to verify that each entry does not contain the
`physical_id` key at all when it cannot be resolved, while keeping the existing
checks for `id`, `visible_id`, and `utilization`.
🤖 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 `@src/keep_gpu/utilities/gpu_info.py`:
- Around line 177-180: The busy-percent probe in gpu_info.py’s util query
currently catches Exception, which triggers Ruff BLE001; narrow the except in
the rocm_smi.rsmi_dev_busy_percent_get path to the specific expected failure
type if possible, or add an explicit inline suppression with a brief best-effort
telemetry rationale while keeping the logger.debug fallback behavior intact.

In `@src/keep_gpu/utilities/rocm_visibility.py`:
- Around line 28-31: The broad except in the hardware probe inside the count
parsing logic triggers Ruff BLE001; update the exception handling in the count
retrieval path to either catch only the expected failure types around count_fn()
/ int(...) or add a targeted noqa: BLE001 with a brief intent comment if this
fallback-to-None behavior is intentional. Use the existing count_fn-based probe
in the visibility utility to keep the change localized.

---

Nitpick comments:
In `@tests/utilities/test_gpu_info.py`:
- Around line 361-365: The ROCm GPU info test is too weak because
`info.get("physical_id")` passes even if `physical_id` is present with a null
value. Update the assertions in `test_gpu_info` for `gpu_info._query_rocm` to
verify that each entry does not contain the `physical_id` key at all when it
cannot be resolved, while keeping the existing checks for `id`, `visible_id`,
and `utilization`.
🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 959930da-6f16-439b-ae05-1ca103bcb991

📥 Commits

Reviewing files that changed from the base of the PR and between 12eabe1 and 9bea0d9.

📒 Files selected for processing (15)
  • AGENTS.md
  • README.md
  • docs/concepts/architecture.md
  • docs/getting-started.md
  • docs/guides/cli.md
  • docs/guides/mcp.md
  • docs/guides/python.md
  • docs/plans/rocm-visible-rank-telemetry.md
  • docs/reference/api.md
  • docs/reference/cli.md
  • src/keep_gpu/single_gpu_controller/rocm_gpu_controller.py
  • src/keep_gpu/utilities/gpu_info.py
  • src/keep_gpu/utilities/rocm_visibility.py
  • tests/rocm_controller/test_rocm_utilization.py
  • tests/utilities/test_gpu_info.py

Comment thread src/keep_gpu/utilities/gpu_info.py
Comment thread src/keep_gpu/utilities/rocm_visibility.py
@Wangmerlyn
Wangmerlyn merged commit 5fe2e83 into main Jun 27, 2026
5 checks passed
@Wangmerlyn
Wangmerlyn deleted the codex/rocm-visible-rank-telemetry branch June 27, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant