Skip to content

Expose precise cache-layer metrics for load_or_fetch #26

@blackopsrepl

Description

@blackopsrepl

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions