You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Split out from #42. The original issue bundled a documentation-accuracy fix (handled separately in the docs PR for #42) with a request for a new one-call Prometheus exposition helper. This issue tracks the feature request only.
Request
Provide a single entrypoint that wires up Prometheus exposition for cachekit, so users don't have to hand-roll prometheus_client exposition (start_http_server / make_wsgi_app / make_asgi_app).
Proposed surface:
enable_prometheus_metrics(port: int = 8000, addr: str = "0.0.0.0") — a helper that starts/registers exposition for cachekit's metrics on the default registry.
CACHEKIT_PROMETHEUS_ENABLED env var — opt-in toggle so exposition can be turned on without code changes.
Why this is non-trivial (needs an API decision)
Today cachekit only records metrics; it never exposes them. The library writes series onto the default prometheus_client registry; starting an HTTP server is currently the application's job (now documented correctly under docs: improve cache_info() discoverability for observability #42). Adding a helper that starts a server is a behavior/scope change that needs a deliberate decision — especially around owning a socket/port inside a library.
The metric names overlap an already-shipped-but-renamed path. The real emitted series are cache_operations_total, redis_cache_operations_total, cache_operation_duration_ms, cache_operation_size_bytes, and circuit_breaker_state (no cachekit_ prefix). There are effectively two recording paths (load-control via load_control.py and async/sync via async_metrics.py) that emit overlapping operation counters. Any helper should expose a single, coherent view and we should decide whether to consolidate/alias these series — renaming the existing metrics would be a breaking change and is explicitly out of scope unless versioned deliberately.
Config flag naming.MonitoringConfig.enable_prometheus_metrics already exists and gates collection. A new CACHEKIT_PROMETHEUS_ENABLED env var that gates exposition must be clearly distinguished from the existing collection flag to avoid confusion.
Acceptance criteria (proposed)
Decide whether cachekit should own exposition (server/route) or only provide a thin wrapper over prometheus_client.
Decide the canonical metric surface (consolidate vs. document both recording paths) without breaking existing names.
enable_prometheus_metrics() helper with sensible defaults and docstrings.
CACHEKIT_PROMETHEUS_ENABLED env var wired through pydantic-settings, distinct from MonitoringConfig.enable_prometheus_metrics.
Summary
Split out from #42. The original issue bundled a documentation-accuracy fix (handled separately in the docs PR for #42) with a request for a new one-call Prometheus exposition helper. This issue tracks the feature request only.
Request
Provide a single entrypoint that wires up Prometheus exposition for cachekit, so users don't have to hand-roll
prometheus_clientexposition (start_http_server/make_wsgi_app/make_asgi_app).Proposed surface:
enable_prometheus_metrics(port: int = 8000, addr: str = "0.0.0.0")— a helper that starts/registers exposition for cachekit's metrics on the default registry.CACHEKIT_PROMETHEUS_ENABLEDenv var — opt-in toggle so exposition can be turned on without code changes.Why this is non-trivial (needs an API decision)
Today cachekit only records metrics; it never exposes them. The library writes series onto the default
prometheus_clientregistry; starting an HTTP server is currently the application's job (now documented correctly under docs: improve cache_info() discoverability for observability #42). Adding a helper that starts a server is a behavior/scope change that needs a deliberate decision — especially around owning a socket/port inside a library.The metric names overlap an already-shipped-but-renamed path. The real emitted series are
cache_operations_total,redis_cache_operations_total,cache_operation_duration_ms,cache_operation_size_bytes, andcircuit_breaker_state(nocachekit_prefix). There are effectively two recording paths (load-control viaload_control.pyand async/sync viaasync_metrics.py) that emit overlapping operation counters. Any helper should expose a single, coherent view and we should decide whether to consolidate/alias these series — renaming the existing metrics would be a breaking change and is explicitly out of scope unless versioned deliberately.Config flag naming.
MonitoringConfig.enable_prometheus_metricsalready exists and gates collection. A newCACHEKIT_PROMETHEUS_ENABLEDenv var that gates exposition must be clearly distinguished from the existing collection flag to avoid confusion.Acceptance criteria (proposed)
prometheus_client.enable_prometheus_metrics()helper with sensible defaults and docstrings.CACHEKIT_PROMETHEUS_ENABLEDenv var wired through pydantic-settings, distinct fromMonitoringConfig.enable_prometheus_metrics.Related: #42