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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions