Stats and observability

Layeron Cache tracks runtime counters for each cache instance and can emit observability metrics when the app configures product observability.

Read Stats

Use stats() to read counters for one cache instance:

app.get("/internal/cache/stats", async () => {
  const stats = await apiCache.stats()

  return Response.json(stats)
})

Response shape:

{
  "hits": 1204,
  "misses": 97,
  "puts": 97,
  "deletes": 4,
  "purges": 12
}

Counter Meanings

Counter	Meaning
hits	match found an entry in Cloudflare Cache.
misses	match returned a miss.
puts	put wrote a response to Cloudflare Cache.
deletes	delete operations were attempted.
purges	Entries removed by purge.

Counters are stored through the internal Database product for the cache instance.

Product Metrics

When observability is enabled, the Cache runtime emits metrics such as:

Metric	Trigger
cache.hits	Successful match.
cache.misses	Missed match.
cache.puts	Written response.
cache.deletes	Delete result.
cache.purges	Purge result count.

Metrics include product attributes for the cache product name, namespace, and instance name.

Example Diagnostic Route

app.get("/internal/cache/health", async () => {
  const stats = await apiCache.stats()
  const totalReads = stats.hits + stats.misses
  const hitRate = totalReads === 0
    ? 0
    : stats.hits / totalReads

  return Response.json({
    ...stats,
    hitRate,
  })
})

This route is useful during load testing. For production, protect internal diagnostics with your Auth and Policy setup.

Operational Signals

Watch these signals during development:

• High misses with matching puts: keys or vary values may differ between match and put.
• High puts with low hits: TTL may be too short or the route may have too many unique query/header variants.
• High purges: invalidation may be broader than necessary.
• Delete returning false: the delete request may produce a different key from the original write.