Skip to content

serve: add /metrics endpoint for instance and cache size info#418

Merged
tinder-maxwellelliott merged 2 commits into
masterfrom
claude/serve-metrics-endpoint
Jul 9, 2026
Merged

serve: add /metrics endpoint for instance and cache size info#418
tinder-maxwellelliott merged 2 commits into
masterfrom
claude/serve-metrics-endpoint

Conversation

@tinder-maxwellelliott

Copy link
Copy Markdown
Collaborator

What

Adds GET /metrics to the serve query service so callers and monitoring can see a running instance's identity, liveness, and cache size usage without scraping logs.

Example:

curl 'http://localhost:8080/metrics'
{
  "version": "31.4.0",
  "uptimeSeconds": 3600,
  "ready": true,
  "gitEngine": "jgit",
  "trackDeps": false,
  "cache": {"directory": "/var/cache/bazel-diff", "entries": 128, "sizeBytes": 4823913, "sizeHuman": "4.6 MB"},
  "jvm": {"usedBytes": 123456789, "maxBytes": 2147483648}
}

How

  • MetricsService assembles the snapshot from the instance's config, its readiness flag, live JVM state, and — when the backing store supports it — the on-disk cache footprint. Read on demand per request (metrics are polled at a low rate, so walking the cache dir each call is fine).
  • MeasurableHashCacheStorage capability interface (mirrors the existing pluggable-storage design). LocalDiskHashCacheStorage reports entry count + total bytes by summing its *.json entries. A backend that can't cheaply report size (a future S3 store) simply doesn't implement it, and the cache size fields are null.
  • Wired into BazelDiffServer as an always-on endpoint. Deliberately not gated on readiness — a scrape of an un-ready or lame-ducked instance still returns data, with the current state in the ready field.
  • No new CLI flags.

Notes for reviewers

Testing

  • Unit: MetricsService snapshot assembly (injected clock for deterministic uptime; null cache for a non-measurable backend), and LocalDiskHashCacheStorage.stats().
  • HTTP: /metrics returns 200 + JSON, 405 on non-GET, 404 when no provider is wired, and is served even when not ready.
  • End-to-end: a ServeCommandTest case that stands up the real server via buildAndStartServer and curls /metrics over real HTTP, reading live on-disk cache stats parsed from JSON.
  • ktfmt/buildifier clean; docs in readme_template.md + regenerated README.md.

Note: a full real-binary smoke of serve requires a real Bazel workspace (its DI eagerly runs bazel info at startup, unrelated to metrics), which is what E2ETest#testServeEndToEnd covers; the endpoint here is exercised end-to-end via the in-process ServeCommandTest over real HTTP.

tinder-maxwellelliott and others added 2 commits July 9, 2026 11:48
Adds `GET /metrics` to the serve query service so callers and monitoring can
see an instance's identity, liveness, and cache size usage without scraping
logs.

- MetricsService assembles a JSON snapshot: version, uptime, readiness, git
  engine, trackDeps, cache footprint (directory / entries / bytes / human),
  and JVM heap use. Wired into BazelDiffServer as an always-on endpoint,
  intentionally NOT gated on readiness so an un-ready or lame-ducked instance
  is still scrapeable (readiness is reported as a field).
- MeasurableHashCacheStorage capability interface (mirrors the pluggable
  storage design); LocalDiskHashCacheStorage reports entry count + total bytes
  by summing its `*.json` entries. A backend that cannot cheaply report its
  size (e.g. a future S3 store) omits it and the size fields are null.
- No new CLI flags; the endpoint is always available.

Tests: MetricsService snapshot assembly (injected clock, null cache for a
non-measurable backend), LocalDisk stats, the /metrics HTTP endpoint
(200 / 405 / 404 / served-when-not-ready), and an end-to-end ServeCommand test
that curls /metrics over real HTTP and reads live on-disk cache stats. Docs
added to readme_template.md and the regenerated README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Resolves conflicts from #417 (serve cache pruning) landing on master:
- HashCacheStorage.kt: LocalDiskHashCacheStorage now implements BOTH
  MeasurableHashCacheStorage (stats(), this PR) and PrunableHashCacheStorage
  (prune(), #417), keeping both method bodies and the shared touch-on-get LRU.
- ServeCommand.buildAndStartServer wires the MetricsService alongside #417's
  CachePruner startup; imports for both features merged.
- cli/BUILD and LocalDiskHashCacheStorageTest keep both features' test
  targets and cases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tinder-maxwellelliott tinder-maxwellelliott marked this pull request as ready for review July 9, 2026 16:50
@tinder-maxwellelliott tinder-maxwellelliott merged commit e9ab129 into master Jul 9, 2026
35 of 44 checks passed
@tinder-maxwellelliott tinder-maxwellelliott deleted the claude/serve-metrics-endpoint branch July 9, 2026 17:55
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