Skip to content

feat: one-call enable_prometheus_metrics() helper + CACHEKIT_PROMETHEUS_ENABLED env var #146

Description

@27Bslash6

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_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)

  1. 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.

  2. 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.

  3. 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.
  • Docs updated (the docs: improve cache_info() discoverability for observability #42 docs PR currently tells users to wire exposition themselves; that guidance should be updated once this lands).

Related: #42

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions