feat: add vllm sidecar heartbeat and load metrics reporting.

[fdvty]

Description

Builds on the merged vLLM sidecar (#69). The sidecar now periodically scrapes
vLLM's Prometheus /metrics and POSTs LoadMetrics/LatencyMetrics to the master's
new internal heartbeat endpoint, so the scheduler sees live load/latency for
vLLM-backed instances.

• vllm_sidecar/metrics.py — scrape vLLM /metrics into the heartbeat schema
  (waiting requests, gpu cache usage, TTFT/TBT interval averages).
• vllm_sidecar/sidecar.py — heartbeat loop on a cadence; re-registers on a 409.
• C++ Heartbeat HTTP endpoint (/v1/internal/heartbeat) with optional
  X-Internal-Token auth (--internal_api_token gflag); proto + master wiring.
• Reuses one requests.Session for the periodic metrics scrape and heartbeat POST.

Related Issues

Change Type

• New feature

Pull Request Checklist

• Commit/PR title follows <type>: <subject>.
• Rebased onto the latest main (on top of feat: add vllm sidecar auto-registration. #69).
• C++ clang-format clean; Python ruff-clean and unit-tested (26 tests pass).

Reviewer Notes

• The internal_api_token gflag lives here together with its only consumer
  (the Heartbeat endpoint), as discussed on feat: connect xllm-service http entrypoint to vllm backend. #68.
• ~⅓ of the diff is tests; suggest Squash and merge.

[gemini-code-assist]

Code Review

This pull request introduces a heartbeat mechanism to the vLLM sidecar, allowing it to scrape Prometheus metrics from vLLM and report load and latency metrics to the master service via a new /v1/internal/heartbeat HTTP endpoint. It also adds optional token-based authentication to secure this internal endpoint. The review feedback highlights two critical issues in the metrics parsing logic: first, the regular expression for parsing metrics fails to handle scientific notation with negative exponents (e.g., 1.23e-04), which can cause parsing failures; second, parsing NaN or Inf values can lead to application crashes when those values are subsequently cast to integers. Both comments provide actionable code suggestions to resolve these issues.

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.

[Kang-Meng]

LGTM