docs: Document the PD Prefill admission metrics (per-worker inflight, queue depth, wait, rejections)

[github-actions]

What this PR does

Which Prometheus metrics expose the per-worker PD Prefill admission gate — how many prefill requests SMG has admitted per worker, how many requests are waiting for Prefill admission, how long they waited, and why they were rejected?

Why we need it

Source change: smg-project/smg@da9f4d0

Commit 6 (#1961, da9f4d06, 2026-09-29) added a per-worker PD Prefill admission gate with four new metrics, verified in current source: model_gateway/src/observability/metrics.rs:280-295 declares smg_pd_prefill_admission_inflight (gauge, 'Prefill requests admitted by SMG per worker'), smg_pd_prefill_admission_queued (gauge, router-wide queue depth), smg_pd_prefill_admission_wait_seconds (histogram, time waiting in the queue), and smg_pd_prefill_admission_rejections_total (counter, 'by reason'); metrics.rs:1222-1249 records them (inflight labeled worker=, rejections labeled reason). Reasons are exactly unavailable, queue_full, queue_timeout (model_gateway/src/worker/prefill_admission.rs:305-401); the queue gauge is set on every push/pop and the wait histogram is recorded whenever a request leaves the queue, admitted or timed out. The gate exists only when --prefill-max-inflight-requests-per-worker is positive (default -1, disabled; app_context.rs:390-400) with queue defaults 100 slots/60 s, and it gates the prefill leg on both the HTTP PD router (routers/http/pd_router.rs:100-113, 282-283) and the gRPC PD/EPD pipelines (routers/grpc/common/stages/worker_selection.rs:415-433); queue rejections answer 429 with codes pd_prefill_queue_full/pd_prefill_queue_timeout (routers/mod.rs:45-60). src/lib/content/reference/metrics.md's 'PD Disaggregation Metrics' section (lines 443-522) documents only the decode-side smg_pd_admission_waits_total/smg_pd_admission_sheds_total and no page mentions prefill admission (repo-wide grep finds nothing). Two same-page consistency notes belong to this one concern: the 'Removed workers' list (metrics.md line 61) omits that smg_pd_prefill_admission_inflight is reset to 0 when a worker is removed (metrics.rs:1752, test prefill_worker_removal_resets_admission_gauge at metrics.rs:1909), and the 'Histogram Buckets' section (metrics.md line 1245) says only smg_worker_retry_backoff_seconds and smg_scheduler_queue_wait_seconds render as Prometheus summaries, while smg_pd_prefill_admission_wait_seconds matches none of the bucket matchers (duration_seconds/ttft_seconds/tpot_seconds suffixes or the two full-name matchers, metrics.rs:554-596) and therefore also renders as a summary. The commit landed after the v1.11.0 bump (ID 23, 3be823a7, 2026-09-24), so the edit must present these series as on main (smg-project/smg#1961) without promising a release, keeping v1.11.0-scoped statements true. This is one independent concern: one commit introduced one observable mechanism whose metric family is enumerated on the one canonical metrics page; the gate's runtime behavior belongs to the routing-workers scan and its CLI flags to deploy-config.

Scope: observability / pd-prefill-admission-metrics. Other concerns are deferred.

How to test

• Passed the documentation path and size guard (under 1000 added plus deleted lines; no file-count limit).
• Passed an independent accuracy and single-concern review.
• Passed git diff --check and pnpm check and the production pnpm build.

Checklist

• Tests added/updated (if applicable)
• Docs updated (if applicable)
• Commit signed off by XinyueZhang369 zoeyzhang369@gmail.com

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: e16effed-9c32-4acc-b27b-71b5be065842

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

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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