Problem
RoadNetwork::cache_stats() currently exposes hits and misses, but those counters do not correspond to the three cache layers described in the docs. In the current implementation:
- hits are only recorded for in-memory cache lookups
- misses are recorded before the file-cache check
- a single cold load can increment
misses more than once
- a disk-cache hit is still counted as a miss
That makes the current counters unsuitable for operational guidance like "did this request hit memory, disk, or network?" or "how warm is the cache?"
Requested fix
Expose cache-layer metrics that match actual behavior, for example:
load_requests
memory_hits
disk_hits
network_fetches
- optionally
in_flight_waits or similar contention metrics
These should let callers distinguish:
- served directly from the in-memory cache
- loaded from the on-disk cache
- fetched from Overpass
Why this matters
The docs site is adding operational guidance around caching. Without precise metrics, the docs either overclaim what cache_stats() means or have to stay vague. Tightening the crate API would make the docs accurate and make the metrics genuinely useful in production.
Current references
src/routing/cache.rs
src/routing/fetch.rs
In particular, the current behavior is visible around record_hit() / record_miss() in load_or_fetch, load_or_insert, and get_cached_network.
Problem
RoadNetwork::cache_stats()currently exposeshitsandmisses, but those counters do not correspond to the three cache layers described in the docs. In the current implementation:missesmore than onceThat makes the current counters unsuitable for operational guidance like "did this request hit memory, disk, or network?" or "how warm is the cache?"
Requested fix
Expose cache-layer metrics that match actual behavior, for example:
load_requestsmemory_hitsdisk_hitsnetwork_fetchesin_flight_waitsor similar contention metricsThese should let callers distinguish:
Why this matters
The docs site is adding operational guidance around caching. Without precise metrics, the docs either overclaim what
cache_stats()means or have to stay vague. Tightening the crate API would make the docs accurate and make the metrics genuinely useful in production.Current references
src/routing/cache.rssrc/routing/fetch.rsIn particular, the current behavior is visible around
record_hit()/record_miss()inload_or_fetch,load_or_insert, andget_cached_network.