Export kvcached metrics through SGLang's native endpoint

[shipiyouniao]

Summary

• compose kvcached metrics with the scheduler collector selected by SGLang 0.5.13+
• export runtime, KV pool, and operation snapshots through SGLang's native Prometheus /metrics endpoint
• preserve custom stat logger backends and isolate exporter initialization/update failures from serving

Design

This reuses ServerArgs.stat_loggers and resolve_collector_class instead of starting another HTTP endpoint, background thread, filesystem protocol, or IPC channel. The wrapper subclasses whichever scheduler collector SGLang (or another integration) already selected and uses the collector's configured metric classes.

The integration is active only when kvcached is enabled. SGLang remains responsible for enabling and serving metrics with --enable-metrics; kvcached remains responsible for producing the underlying read-only snapshots.

Depends on #385 and #410. This PR must not merge before both dependencies.

Related to #375.

Validation

• ruff, codespell, isort, clang-format, PyMarkdown, actionlint, and trailing-whitespace hooks
• strict mypy over all 45 Python source files for Python 3.9, 3.10, 3.11, 3.12, and 3.13
• 14 passed: observability and SGLang metrics tests
• SGLang 0.5.13.post1 native collector and multiprocess middleware smoke test: /metrics exported kvcached_runtime_* and kvcached_sglang_metrics_export_last_success_timestamp_seconds

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

Pull request overview

This PR adds a read-only observability surface (runtime state, KV pool state, and operation counters) and wires kvcached metrics into SGLang’s existing Prometheus /metrics endpoint by composing with SGLang’s selected scheduler metrics collector (instead of running a separate exporter endpoint).

Changes:

• Introduce a process-local weak registry for live KV pools and expose runtime/pool/operation snapshots via kvcached.observability.
• Add operation counters + error tracking to KVCacheManager, and register created managers from vLLM/SGLang integrations for snapshot enumeration.
• Add SGLang metrics composition: wrap SGLang’s scheduler collector to update kvcached Prometheus metrics and integrate the patch via SGLang autopatch/version gating.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_sglang_metrics.py	Adds tests for Prometheus exporter behavior and collector wrapping/error isolation.
tests/test_observability.py	Adds tests for runtime/pool/operation snapshots, registry behavior, and integration registration/cleanup.
kvcached/pool_registry.py	Implements a weakref-based process-local registry for live KV cache managers.
kvcached/observability.py	Adds snapshot dataclasses/builders plus helpers to enumerate snapshots from the registry.
kvcached/kv_cache_manager.py	Adds pool naming and operation counters/error metadata; exposes snapshot methods.
kvcached/integration/vllm/interfaces.py	Registers created managers, clears registry on shutdown, and exposes integration snapshot helpers.
kvcached/integration/sglang/patches.py	Adds the SGLang metrics patch and passes stable pool names when creating managers.
kvcached/integration/sglang/metrics.py	Implements Prometheus exporter + wrapper collector class composition.
kvcached/integration/sglang/interfaces.py	Registers created managers, clears registry on shutdown, and exposes integration snapshot helpers.
kvcached/integration/sglang/autopatch.py	Registers the new metrics patch behind an SGLang version gate.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.