support caching metrics

[agkloop]

This pull request adds a comprehensive, optional metrics and monitoring system to the advanced_caching library, including new documentation, example usage, and support for multiple exporters (InMemory, OpenTelemetry, GCP Cloud Monitoring, and custom). It introduces a metrics argument to cache decorators, enables per-function and shared metrics collection, and provides guides for custom exporters and performance best practices.

Metrics & Monitoring System:

• Added a new metrics argument to cache decorators (e.g., TTLCache.cached) to enable optional instrumentation via a MetricsCollector interface. If provided, cache operations are automatically instrumented for hits, misses, latency, errors, memory usage, and background refreshes. (src/advanced_caching/decorators.py) [1] [2] [3]
• Introduced built-in metrics collectors: InMemoryMetrics (zero dependencies, thread-safe), NullMetrics (zero overhead, default), and exporters for OpenTelemetry and GCP Cloud Monitoring, with installation instructions and extras in pyproject.toml. (README.md, pyproject.toml) [1] [2] [3]

Documentation & Examples:

• Added detailed documentation for metrics usage, configuration, and exporters, including a new docs/metrics.md and a guide for custom exporters (docs/custom-metrics-exporters.md). [1] [2]
• Provided new example scripts demonstrating metrics collection, shared collectors, and GCP client sharing: examples/metrics_example.py, examples/shared_metrics_example.py, examples/gcp_client_sharing_example.py. [1] [2] [3]

Custom Exporter Support:

• Documented how to implement custom metrics exporters by following the MetricsCollector protocol, with performance tips for high-throughput scenarios. (docs/custom-metrics-exporters.md)

Usability Improvements:

• Updated the README to highlight metrics features, installation options, and quick-start usage, including direct code samples and links to full documentation.

These changes make it easy to monitor cache performance in production, development, and testing environments, with minimal overhead and flexible exporter options.