docs(monitoring): add PromQL recipes page for joining metrics

[imantaba]

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds a "Querying and joining metrics" page under userguide/monitoring (sidebar: "PromQL recipes"). The existing monitoring pages document each metrics endpoint separately; none show how to correlate them. This page fills that gap:

• Correlating the allocation and usage views — the scheduler and device-usage endpoints share the device_uuid label, so you can relate a device's allocation to its live usage. Covers the and on (device_uuid) filter and, because the host usage metrics carry no node label, a * on (device_uuid) group_left(node) join that actually carries node across.
• Useful queries — allocation-vs-capacity percent per node, containers over 80% of their vGPU memory limit, and shared-GPU count.
• A note that _ratio metrics use a 0-100 scale.

Registered in both the current and the v2.9.0 sidebars, with the page added under docs/ and versioned_docs/version-v2.9.0/.

Follow-up to Project-HAMi/HAMi#2374, which @archlitchi redirected here (main-repo docs/ is design-docs-only; user-guide content belongs on the website).

Which issue(s) this PR fixes:

Checklist:

• npm run lint / npm run format:check — not run locally; page written to .markdownlint.json / .prettierrc conventions (single-line prose, dash bullets, final newline). Please let CI verify.
• npm run build (en/zh) — not run locally.
• Chinese translation — not included; the new English page falls back to English under i18n. Happy to add a zh translation if you'd like it in this PR.
• Commits are signed off (git commit -s)

This change was prepared with AI assistance (per CONTRIBUTING.md); all changes were reviewed and verified by me.

Summary by CodeRabbit

• Documentation
  • Added a PromQL recipes guide for correlating allocation and usage metrics.
  • Included examples for node memory utilization, high-memory containers, shared GPUs, and label-based metric joins.
  • Clarified that ratio metrics use a 0–100 percentage scale.
  • Added the guide to the Monitoring section of the User Guide.

[hami-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: imantaba
Once this PR has been reviewed and has the lgtm label, please assign wawa0210 for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Deploy Preview for project-hami ready!

Name	Link
🔨 Latest commit	0d84230
🔍 Latest deploy log	https://app.netlify.com/projects/project-hami/deploys/6a8943af843d050007fb3119
😎 Deploy Preview	https://deploy-preview-730--project-hami.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[hami-robot]

Welcome @imantaba! It looks like this is your first PR to Project-HAMi/website 🎉

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fa68aa39-f7c0-472d-8fd1-bc23d9673a60

📥 Commits

Reviewing files that changed from the base of the PR and between a9b44ce and 6bff74f.

📒 Files selected for processing (4)

• docs/userguide/monitoring/promql-recipes.md
• sidebars.js
• versioned_docs/version-v2.9.0/userguide/monitoring/promql-recipes.md
• versioned_sidebars/version-v2.9.0-sidebars.json

---

📝 Walkthrough

Walkthrough

Added a PromQL recipes guide for HAMi monitoring queries. The guide covers device-label joins, node filtering, memory utilization, high-memory containers, shared GPUs, and 0–100 ratio metrics. Added the page to current and v2.9.0 Monitoring navigation.

Changes

PromQL monitoring documentation

Layer / File(s)	Summary
PromQL recipes content docs/userguide/monitoring/promql-recipes.md, versioned_docs/version-v2.9.0/userguide/monitoring/promql-recipes.md	Added PromQL examples for device correlation, node filtering, memory utilization, high-memory containers, shared GPUs, and ratio metric units.
Monitoring navigation wiring sidebars.js, versioned_sidebars/version-v2.9.0-sidebars.json	Added the recipes page to the Monitoring navigation for current and v2.9.0 documentation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Project-HAMi/website#498: Updates related HAMi monitoring metric names, labels, and ratio semantics.

Suggested reviewers: mesutoezdil

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a monitoring documentation page with PromQL recipes for joining metrics.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[rootsongjc]

@Shenhan11 can you take a look?

[mesutoezdil]

checked all metric names and labels against the monitoring pages, they match. checklist is unchecked and the docs health ci did not run, please rebase and run the checks.

[mesutoezdil]

this adds a brand new page to the frozen v2.9.0 snapshot. is that wanted, or current docs only?

[imantaba]

Current docs only. I'd originally added it to the v2.9.0 snapshot so it would show on the default docs version, but you are right that the versioned snapshot should stay frozen.
I've dropped the page and it.s sidebar entry from version-v2.9.0 the guide now lives only under current docs/ and will roll into the next version snapshot at release time.