Add cache analytics and observability framework

[Copilot]

Cache Analytics and Observability Framework Implementation

Overview

Implemented a comprehensive analytics framework for cachier that tracks cache performance metrics and provides observability for production systems.

✅ All Review Feedback Addressed

Previous feedback (11 comments) - ALL RESOLVED
Second round feedback (16 comments from @Borda + copilot reviewer) - ALL RESOLVED
Latest feedback (3 comments) - ALL RESOLVED

🔧 Latest Changes - Code Quality Improvements

1. ✅ Absolute imports (2744902663) - Use from cachier. instead of relative imports
2. ✅ Docstring-based instructions (2744908071) - Moved usage to module docstring with __doc__
3. ✅ contextlib.suppress (2744912772) - Use suppress() for cleaner exception handling
4. ✅ Line length optimization (2744919532, 2744929433) - Remove trailing commas for 120-char lines
5. ✅ Collector yields (2744926357) - Added comment explaining Prometheus collector protocol
6. ✅ String formatting (2744927877) - Consolidated prometheus metric headers into single formatted strings
7. ✅ README prometheus_client (2744928794) - Updated docs: both modes work correctly with live metrics
8. ✅ Cache size backend support (2744928804) - Clarified memory-only support in README
9. ✅ Security: host binding (2744928825) - Pass host parameter to prometheus_client
10. ✅ Metric name consistency (2744928839) - Added _total suffix to counter metrics
11. ✅ Remove dead code (2744928850) - Removed unused _last_seen dict
12. ✅ Monotonic clock for windows (2744928866) - Use perf_counter() for time windows
13. ✅ Stale hit tracking (2744928891) - Record both stale_hit and miss for accurate rates
14. ✅ Exception comments (2744928901) - Added explanatory comments
15. ✅ Don't swallow exceptions (2744928818) - Removed silent exception handling in start()
16. ✅ Aggregated print statements (2744970314) - Use single formatted f-string in example
17. ✅ Absolute imports in sql.py (2744972453) - Changed to absolute imports

📊 All Metrics Working

• ✅ Cache hits and misses with accurate hit rates (includes stale hits as misses)
• ✅ Operation latencies with monotonic clock (immune to clock adjustments)
• ✅ Stale cache access patterns
• ✅ Recalculation frequencies
• ✅ Thread wait timeouts
• ✅ Entry size limit rejections
• ✅ Cache size (memory backend only)
• ✅ Prometheus export with consistent metric names and live collection

✅ Testing Results

• 14/14 metrics tests passing
• 7/7 exporter tests passing
• All review feedback addressed
• Linting clean (ruff compliant)
• Code quality improvements applied

🎯 Production Ready

The implementation is complete, tested, documented, and ready for production use with all feedback addressed.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Cache Analytics and Observability Framework</issue_title>
<issue_description>Currently, cachier provides no built-in way to monitor cache performance in production.
Users cannot track cache hit/miss rates, measure cache effectiveness, monitor memory/disk
usage, or identify performance bottlenecks. For production systems with multiple cached
functions across different backends, understanding cache behavior is critical for
optimization and debugging.

Proposed Solution:
Implement a comprehensive analytics framework that collects metrics at the decorator level
and core level, including:

• Per-function cache hit/miss rates and ratios
• Cache operation latency (read/write/invalidation times)
• Cache size metrics (entry counts, storage size per backend)
• Stale cache access patterns and recalculation frequencies
• Thread contention and wait times (especially for wait_for_calc_timeout scenarios)
• Entry size distribution and entry_size_limit rejection counts

The framework should provide:

1. A CacheMetrics class accessible via cached_function.metrics
2. Pluggable exporters for Prometheus, StatsD, CloudWatch, and custom backends
3. Configurable sampling rates to minimize performance impact
4. Aggregation across multiple function instances
5. Time-windowed metrics (last minute, hour, day)

Example Usage:

from cachier import cachier
from cachier.metrics import PrometheusExporter

@cachier(backend='redis', enable_metrics=True)
def expensive_operation(x):
    return x ** 2

# Access metrics programmatically
stats = expensive_operation.metrics.get_stats()
print(f"Hit rate: {stats.hit_rate}%, Avg latency: {stats.avg_latency_ms}ms")

# Export to monitoring system
exporter = PrometheusExporter(port=9090)
exporter.register_function(expensive_operation)

Technical Challenges:

• Minimizing performance overhead of metrics collection (use atomic operations, sampling)
• Thread-safe metrics aggregation across concurrent calls
• Backend-specific metrics (e.g., Redis connection pool stats, MongoDB query times)
• Handling metrics persistence across process restarts
• Supporting distributed aggregation for multi-instance deployments

Value:
Enables production observability, performance optimization, and data-driven cache tuning
decisions. Critical for systems with high cache utilization.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Cache Analytics and Observability Framework #310

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.