Skip to content

hicache: restore per-tier hit/eviction/load-back bandwidth metrics + Grafana dashboards - #31879

Closed
TianDi101 wants to merge 6 commits into
sgl-project:mainfrom
TianDi101:feat/hicache-restore-observability
Closed

TianDi101 wants to merge 6 commits into
sgl-project:mainfrom
TianDi101:feat/hicache-restore-observability

Conversation

@TianDi101

@TianDi101 TianDi101 commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Re-adds HiCache observability that was reverted in feat/umbp-pr (001e9ce) and never carried forward, adapted to the current async write/load pipeline and reconciled with timing_enabled/make_timing_event_pair() (the portability guard main already added for backends without CUDA/HIP event-timing support):

  • Per-tier (L1/L2/L3) cache hit/miss token counters: PrefillAdder now tracks L1 (GPU device), L2 (host DRAM), and L3 (storage) hit tokens plus misses, exported as sglang:cache_hit_tokens_l{1,2,3}_total / cache_miss_tokens_total.
  • Eviction/load-back bandwidth + byte-level metrics: sglang:evicted_backuped_tokens_total / evicted_regular_tokens_total (split by whether the node was already backed up before eviction), sglang:gpu_kv_cache_occupancy (alias gauge for dashboards querying the old name), sglang:eviction_bandwidth_gb_s / load_back_bandwidth_gb_s (real per-batch PCIe bandwidth derived from HiCacheAck.num_tokens + CUDA/HIP event timing, gated on timing_enabled), and sglang:backuped_bytes_total / prefetched_bytes_total (byte-scaled counterparts of the existing token counters).
    • Extended the write/eviction path (cache_controller.py, hybrid_cache_controller.py) to also use make_timing_event_pair() instead of unguarded enable_timing=True, matching the load path's existing portability handling, and to carry timing_enabled through HiCacheAck so the new bandwidth metrics degrade gracefully on backends without event-timing support.
  • UMBP L3 get/put bandwidth: UMBPStore now populates prefetch_bandwidth/backup_bandwidth, drained by HiRadixCache under --enable-metrics and exported as sglang:prefetch_bandwidth / sglang:backup_bandwidth.
  • Grafana: restores per-tier Cache Hit Rate, HiCache Host Utilization/Capacity, L3 Prefetch/Writeback Rate, L1<->L2 Eviction/Load-back Rate, Cached Tokens Rate, GPU KV Cache Utilization, and L1<->L2 / L3 PCIe bandwidth panels; fixes an orphaned datasource UID + stale template vars, a stale datasource IP, and adds a UMBP dashboard provider.

Deliberately excludes the sglang:prefetch_wait_stall_ms histogram (separate concern, not included in this PR).

Test plan

  • Existing hicache/metrics unit tests pass
  • Manual: run with --enable-metrics --enable-hierarchical-cache and confirm the new Prometheus counters/histograms populate and the restored Grafana panels render

CI States

Latest PR Test (Base): ❌ Run #29799315685
Latest PR Test (Extra): ❌ Run #29799315587

TianDi101 and others added 6 commits July 21, 2026 03:32
Populate prefetch_bandwidth (batch_get) and backup_bandwidth (batch_set)
StorageMetrics from UMBPStore, drained by HiRadixCache under --enable-metrics,
so sglang exports sglang:prefetch_bandwidth / sglang:backup_bandwidth for the
leaderboard L3 get/put bandwidth cards. Aggregate-then-drain pattern (append
per-op, clear on get_stats) matches mooncake/hf3fs; guarded by
enable_storage_metrics so no overhead when metrics are off.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Re-adds the per-tier cache hit breakdown that was previously reverted
in feat/umbp-pr (commit 001e9ce): PrefillAdder tracks L1 (GPU device),
L2 (host DRAM), and L3 (storage) hit tokens plus cache misses, reported
via SchedulerStats and exported as sglang:cache_hit_tokens_l{1,2,3}_total
/ cache_miss_tokens_total Prometheus counters. Adapted to current code:
uses req.storage_hit_length directly (no getattr) and req.extend_range
instead of the since-removed req.extend_input_len.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds back the panels that were dropped in feat/umbp-pr (001e9ce) and
never carried forward: per-tier Cache Hit Rate (percentage view), HiCache
Host Utilization, HiCache Host Used/Total Capacity, L3 Prefetch/Writeback
Rate, L1<->L2 Eviction/Load-back Rate, Cached Tokens Rate, GPU KV Cache
Utilization, and the L1<->L2 / L3 PCIe bandwidth panels. Also fixes the
datasource.yaml URL, which was pinned to a stale host from a prior run.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Re-adds the HiCache observability that was reverted in feat/umbp-pr
(001e9ce) and never carried forward, now adapted to the current
async write/load pipeline:

- sglang:evicted_backuped_tokens_total / evicted_regular_tokens_total:
  split of evicted_tokens_total by whether the node had already been
  backed up to host (cheap detach) vs dropped with no host copy.
- sglang:gpu_kv_cache_occupancy: alias gauge of token_usage, kept for
  HiCache dashboards that query it under the old name.
- sglang:eviction_bandwidth_gb_s / load_back_bandwidth_gb_s: real
  per-batch PCIe bandwidth. HiCacheAck already carried CUDA start/finish
  events bracketing the D2H/H2D copy in cache_controller.py's
  start_writing()/start_loading(); they just weren't created with
  enable_timing=True and had no token count attached. Restored both
  (LayerLoadingEvent too, since load-back reuses its start/finish pair)
  and added a num_tokens field to HiCacheAck so writing_check()/
  loading_check() can derive GB/s from start_event.elapsed_time(finish_event)
  and mem_pool_host.get_size_per_token() at ack-drain time.
- sglang:backuped_bytes_total / prefetched_bytes_total: byte-scaled
  counterparts of the existing backuped_tokens_total/prefetched_tokens_total.

HiCacheAck gaining a 4th field required widening the ack-queue unpacking
in unified_radix_cache.py, hi_mamba_radix_cache.py, and
decode_kvcache_offload_manager.py, which share the same queue but don't
need the new metrics.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… template vars)

Same fix as pushed to fix/grafana-dashboard-datasource-and-vars — applying
directly on this branch since it's the shared checkout every deploy/bench
skill (deploy-1p1d-deepseek, bench-batch-direct-repro, etc.) mounts via
NFS_BASE=/apps/ditian12 for Grafana provisioning. Leaving this as an
uncommitted working-tree diff meant any git checkout/pull/reset on this
shared path would silently revert it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Point Prometheus datasource at the correct node IP and register a
separate UMBP dashboards provider so mori dashboards load alongside
the default sglang ones.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant