DOC-226: Document per-entity client quota metrics (26.2)

[Feediver1]

Description

Documents the new per-entity client quota metrics shipping in v26.2 (ENG-37 "Metrics: Throughput Quota Utilization", implemented in redpanda#30832, merged to dev 2026-06-24). This answers the customer ask behind the epic: track how much of an enforced quota each client is actually using.

Resolves https://redpandadata.atlassian.net/browse/DOC-226
Review deadline:

What's new

One subsection, Track quota use per entity, added to the existing "Monitor client throughput" section of manage-throughput.adoc:

• Intro contextualizing the change: aggregate metrics show that throttling happens per rule; per-entity metrics show who is being throttled and how close each client is to its limit (identify noisy clients by name, alert before quota saturation)
• kafka_per_entity_quota_metrics cluster property (opt-in, default false, no restart)
• The two new counters on /public_metrics and /metrics
• Label scheme (redpanda_quota_type + user/client-id/group labels) and the cardinality-bounding behavior (series exist only while an entity is throttled; cleaned up after idle)
• Utilization guidance: PromQL rate query + compare against rpk cluster quotas describe

Deliberately NOT in this PR (anti-duplication)

The v24.2 client quota changes from the eng context doc (KIP-546/rpk cluster quotas, prefix quotas, per-broker semantics, deprecated cluster configs, the two aggregate histograms, and the kafka_quotas logger) are already documented — verified on beta in manage-throughput.adoc, about-throughput-quotas.adoc, both metrics references, and upgrade/deprecated. This PR only adds the 26.2 delta.

Generated-content notes

• Metrics references: the new metrics will appear in public/internal metrics reference via /gen-metrics at 26.2 release — plain code spans used for now, with a DRAFT-VERIFY to convert to xrefs after regeneration (anchors don't exist yet)
• Property reference: kafka_per_entity_quota_metrics arrives via /gen-props at release — not hand-added
• API doc updates: none needed (feature is metrics-only; no admin API or rpk changes per source)

⚠️ Verify before merge (DRAFT-VERIFY comments in source)

• Internal (/metrics) exposed names for the two counters against a 26.2 build
• redpanda_quota_group_name = client-ID-prefix quotas (agent-inferred; confirm with @mnajda-redpanda)
• Whether Redpanda Cloud exposes kafka_per_entity_quota_metrics — subsection is ifndef::env-cloud gated until confirmed
• Combined-quota label behavior (multiple labels on one series)

Page previews

• https://deploy-preview-1779--redpanda-docs-preview.netlify.app/streaming/26.2/manage/cluster-maintenance/manage-throughput/#track-quota-use-per-entity

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	c5373b0
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a596958b03ad70008bf9c1c
😎 Deploy Preview	https://deploy-preview-1779--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fcf0a0ca-97fc-4b62-b0c2-4dd1e02939eb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-226-per-entity-quota-metrics

---

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

[Feediver1]

@pgellert Fix is in. Looking for approval. Thx

[micheleRP]

@Feediver1 reminder to add to the what's new.

[micheleRP]

Suggested change

	To enable them:
	To enable them, run:

[micheleRP]

Reviewed against docs-team standards — content is clean and reads well. One optional suggestion and a note on the Cloud rendering.

Suggestion (optional): pod label portability in the PromQL example

The example aggregates by pod:

sum by (redpanda_quota_client_id, pod) (
  rate(redpanda_kafka_quotas_client_quota_throughput_by_entity{redpanda_quota_type="produce_quota"}[5m])
)

pod is the per-broker label in Kubernetes/Cloud deployments (consistent with our Cloud monitoring examples), so it's correct there. On non-Kubernetes Self-Managed deployments (bare metal, Docker), a standard Prometheus scrape typically exposes the per-broker label as instance instead, so this query wouldn't group as intended for those users. Since the section renders for both Self-Managed and Cloud, consider a short clause noting that pod is the per-broker label in Kubernetes and users on other deployments should substitute their broker label (for example, instance). Non-blocking.

Note on Cloud rendering (no action needed)

The new subsection doesn't appear in the Cloud deploy preview, but that's expected: this PR targets the beta branch (streaming 26.2, prerelease: true), and the Cloud stub single-sources the streaming component without a version qualifier, so Antora resolves it to the latest released version (currently 26.1), which doesn't have this content. Once 26.2 goes GA and becomes the latest released version, the Cloud include will pick up the section automatically, and the env-cloud conditionals will render the correct Cloud variant. Nothing to change here.

[micheleRP]

please see my comment about the What's new!