Update metrics tracking and enhance cache eviction strategies

- Added metrics for bytes saved from cache to improve performance insights.
- Updated cache eviction strategies in MemoryFS and DiskFS to include metrics tracking for hits and evictions.
- Enhanced README.md with updated garbage collection algorithm descriptions and recommendations for cache usage.
- Introduced new madviseSequential functionality for improved memory access hints on Unix systems.
- Adjusted validation configuration in examples to better reflect realistic usage scenarios.

steamcache/metrics/metrics.go

@@ -22,7 +22,9 @@ type Metrics struct {
 	// Performance metrics
 	TotalResponseTime int64 // in nanoseconds
 	TotalBytesServed  int64
-	TotalBytesCached  int64
+	TotalBytesSaved   int64 // bytes served from cache instead of being re-downloaded from upstream
+
+
 
 	// Cache metrics
 	MemoryCacheSize int64
@@ -98,9 +100,10 @@ func (m *Metrics) AddBytesServed(bytes int64) {
 	atomic.AddInt64(&m.TotalBytesServed, bytes)
 }
 
-// AddBytesCached adds bytes cached to the total
-func (m *Metrics) AddBytesCached(bytes int64) {
-	atomic.AddInt64(&m.TotalBytesCached, bytes)
+// AddBytesSaved records bytes that were served from the cache instead of being
+// fetched again from the upstream (the main value metric for a cache).
+func (m *Metrics) AddBytesSaved(bytes int64) {
+	atomic.AddInt64(&m.TotalBytesSaved, bytes)
 }
 
 // SetMemoryCacheSize sets the current memory cache size
@@ -191,8 +194,8 @@ func (m *Metrics) GetStats() *Stats {
 		RateLimited:        atomic.LoadInt64(&m.RateLimited),
 		HitRate:            hitRate,
 		AvgResponseTime:    avgResponseTime,
-		TotalBytesServed:   atomic.LoadInt64(&m.TotalBytesServed),
-		TotalBytesCached:   atomic.LoadInt64(&m.TotalBytesCached),
+		TotalBytesServed: atomic.LoadInt64(&m.TotalBytesServed),
+		TotalBytesSaved:  atomic.LoadInt64(&m.TotalBytesSaved),
 		MemoryCacheSize:    atomic.LoadInt64(&m.MemoryCacheSize),
 		DiskCacheSize:      atomic.LoadInt64(&m.DiskCacheSize),
 		MemoryCacheHits:    atomic.LoadInt64(&m.MemoryCacheHits),
@@ -218,7 +221,7 @@ func (m *Metrics) Reset() {
 	atomic.StoreInt64(&m.RateLimited, 0)
 	atomic.StoreInt64(&m.TotalResponseTime, 0)
 	atomic.StoreInt64(&m.TotalBytesServed, 0)
-	atomic.StoreInt64(&m.TotalBytesCached, 0)
+	atomic.StoreInt64(&m.TotalBytesSaved, 0)
 	atomic.StoreInt64(&m.MemoryCacheHits, 0)
 	atomic.StoreInt64(&m.DiskCacheHits, 0)
 	atomic.StoreInt64(&m.Promotions, 0)
@@ -247,9 +250,11 @@ type Stats struct {
 	RateLimited        int64
 	HitRate            float64
 	AvgResponseTime    time.Duration
-	TotalBytesServed   int64
-	TotalBytesCached   int64
-	MemoryCacheSize    int64
+	TotalBytesServed  int64
+	TotalBytesSaved   int64
+	MemoryCacheSize   int64
+
+
 	DiskCacheSize      int64
 	MemoryCacheHits    int64
 	DiskCacheHits      int64
@@ -291,7 +296,8 @@ func WriteText(w http.ResponseWriter, stats *Stats) {
 	_, _ = fmt.Fprintf(w, "hit_rate %.4f\n", stats.HitRate)
 	_, _ = fmt.Fprintf(w, "avg_response_time_ms %.2f\n", float64(stats.AvgResponseTime.Nanoseconds())/1e6)
 	_, _ = fmt.Fprintf(w, "total_bytes_served %d\n", stats.TotalBytesServed)
-	_, _ = fmt.Fprintf(w, "total_bytes_cached %d\n", stats.TotalBytesCached)
+	_, _ = fmt.Fprintf(w, "total_bytes_saved %d\n", stats.TotalBytesSaved)
+
 	_, _ = fmt.Fprintf(w, "memory_cache_size %d\n", stats.MemoryCacheSize)
 	_, _ = fmt.Fprintf(w, "disk_cache_size %d\n", stats.DiskCacheSize)
 	_, _ = fmt.Fprintf(w, "uptime_seconds %.2f\n", stats.Uptime.Seconds())