psycache 26.1.0__py3-none-any.whl

psycache/instrumentation/_spans.py

@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Generic span helpers.
+"""
+
+from collections.abc import Iterator, Sequence
+from contextlib import ExitStack, contextmanager
+
+from psycache.typing import (
+    CacheCleanupSpan,
+    CacheFlushSpan,
+    CacheGetSpan,
+    CacheInstrumentation,
+    CachePutSpan,
+    CacheRemoveSpan,
+)
+
+
+class _AggregatingGetSpan:
+    def __init__(self, spans: Sequence[CacheGetSpan]) -> None:
+        self._spans = spans
+
+    def record_cache_hit(self, item_size: int) -> None:
+        for span in self._spans:
+            span.record_cache_hit(item_size)
+
+    def record_cache_miss(self) -> None:
+        for span in self._spans:
+            span.record_cache_miss()
+
+
+class _AggregatingPutSpan:
+    def __init__(self, spans: Sequence[CachePutSpan]) -> None:
+        self._spans = spans
+
+    def record_put(self, item_size: int) -> None:
+        for span in self._spans:
+            span.record_put(item_size)
+
+
+class _AggregatingRemoveSpan:
+    def __init__(self, spans: Sequence[CacheRemoveSpan]) -> None:
+        self._spans = spans
+
+    def record_removed(self) -> None:
+        for span in self._spans:
+            span.record_removed()
+
+
+class _AggregatingCleanupSpan:
+    def __init__(self, spans: Sequence[CacheCleanupSpan]) -> None:
+        self._spans = spans
+
+    def record_cleanup(self, num_deleted: int) -> None:
+        for span in self._spans:
+            span.record_cleanup(num_deleted)
+
+
+class _AggregatingFlushSpan:
+    def __init__(self, spans: Sequence[CacheFlushSpan]) -> None:
+        self._spans = spans
+
+    def record_flush(self, num_flushed: int) -> None:
+        for span in self._spans:
+            span.record_flush(num_flushed)
+
+
+class NoopAnySpan:
+    def record_cache_hit(self, item_size: int) -> None:
+        pass
+
+    def record_cache_miss(self) -> None:
+        pass
+
+    def record_put(self, item_size: int) -> None:
+        pass
+
+    def record_removed(self) -> None:
+        pass
+
+    def record_cleanup(self, num_deleted: int) -> None:
+        pass
+
+    def record_flush(self, num_flushed: int) -> None:
+        pass
+
+
+@contextmanager
+def _lookup_span(
+    instrumentations: Sequence[CacheInstrumentation],
+    key: str,
+    name: str | None,
+) -> Iterator[CacheGetSpan]:
+    if not instrumentations:
+        yield NoopAnySpan()
+        return
+
+    with ExitStack() as stack:
+        spans = [
+            stack.enter_context(inst.start_cache_get_span(key, name))
+            for inst in instrumentations
+        ]
+        yield _AggregatingGetSpan(spans)
+
+
+@contextmanager
+def _put_span(
+    instrumentations: Sequence[CacheInstrumentation],
+    key: str,
+    name: str | None,
+) -> Iterator[CachePutSpan]:
+    if not instrumentations:
+        yield NoopAnySpan()
+        return
+
+    with ExitStack() as stack:
+        spans = [
+            stack.enter_context(inst.start_cache_put_span(key, name))
+            for inst in instrumentations
+        ]
+        yield _AggregatingPutSpan(spans)
+
+
+@contextmanager
+def _remove_span(
+    instrumentations: Sequence[CacheInstrumentation],
+    key: str,
+) -> Iterator[CacheRemoveSpan]:
+    if not instrumentations:
+        yield NoopAnySpan()
+        return
+
+    with ExitStack() as stack:
+        spans = [
+            stack.enter_context(inst.start_cache_remove_span(key))
+            for inst in instrumentations
+        ]
+        yield _AggregatingRemoveSpan(spans)
+
+
+@contextmanager
+def _cleanup_span(
+    instrumentations: Sequence[CacheInstrumentation],
+) -> Iterator[CacheCleanupSpan]:
+    if not instrumentations:
+        yield NoopAnySpan()
+        return
+
+    with ExitStack() as stack:
+        spans = [
+            stack.enter_context(inst.start_cache_cleanup_span())
+            for inst in instrumentations
+        ]
+        yield _AggregatingCleanupSpan(spans)
+
+
+@contextmanager
+def _flush_span(
+    instrumentations: Sequence[CacheInstrumentation],
+) -> Iterator[CacheFlushSpan]:
+    if not instrumentations:
+        yield NoopAnySpan()
+        return
+
+    with ExitStack() as stack:
+        spans = [
+            stack.enter_context(inst.start_cache_flush_span())
+            for inst in instrumentations
+        ]
+        yield _AggregatingFlushSpan(spans)

psycache/instrumentation/prometheus.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Prometheus-backed cache instrumentation.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from prometheus_client import Counter, Gauge, Histogram
+
+from psycache.typing import (
+    CacheCleanupSpan,
+    CacheFlushSpan,
+    CacheGetSpan,
+    CachePutSpan,
+    CacheRemoveSpan,
+)
+
+
+_LABEL_NAMES = ["span_name"]
+
+CACHE_HITS = Counter(
+    "psycache_hits_total",
+    "Number of cache hits",
+    labelnames=_LABEL_NAMES,
+)
+
+CACHE_MISSES = Counter(
+    "psycache_misses_total",
+    "Number of cache misses",
+    labelnames=_LABEL_NAMES,
+)
+
+CACHE_GET_DURATION = Histogram(
+    "psycache_get_duration_seconds",
+    "Time taken for cache get operations",
+    labelnames=_LABEL_NAMES,
+)
+
+CACHE_PUT_DURATION = Histogram(
+    "psycache_put_duration_seconds",
+    "Time taken for cache put operations",
+    labelnames=_LABEL_NAMES,
+)
+
+CACHE_REMOVE_DURATION = Histogram(
+    "psycache_remove_duration_seconds",
+    "Time taken for cache remove operations",
+)
+
+CACHE_FLUSH_DURATION = Histogram(
+    "psycache_flush_duration_seconds",
+    "Time taken for cache flush operations",
+)
+
+CACHE_ITEM_SIZE = Histogram(
+    "psycache_item_size_bytes",
+    "Size of cache items in bytes",
+    labelnames=_LABEL_NAMES,
+    buckets=[64, 256, 1024, 4096, 16384, 65536, 262144, 1048576],
+)
+
+CACHE_FLUSHED_ENTRIES = Histogram(
+    "psycache_flushed_entries",
+    "Number of entries flushed per flush operation",
+    buckets=[0, 1, 5, 10, 25, 50, 100, 250, 500, 1000],
+)
+
+CACHE_CLEANUP_LAST_RUN = Gauge(
+    "psycache_cleanup_last_run_timestamp_seconds",
+    "Timestamp of the last expired-entry cleanup run",
+)
+
+CACHE_CLEANUP_DELETED = Gauge(
+    "psycache_cleanup_deleted_entries",
+    "Number of expired entries deleted in the last cleanup run",
+)
+
+
+class _PrometheusCacheGetSpan:
+    def __init__(self, span_name: str) -> None:
+        self._span_name = span_name
+
+    def record_cache_hit(self, item_size: int) -> None:
+        CACHE_HITS.labels(span_name=self._span_name).inc()
+        CACHE_ITEM_SIZE.labels(span_name=self._span_name).observe(item_size)
+
+    def record_cache_miss(self) -> None:
+        CACHE_MISSES.labels(span_name=self._span_name).inc()
+
+
+class _PrometheusCachePutSpan:
+    def __init__(self, span_name: str) -> None:
+        self._span_name = span_name
+
+    def record_put(self, item_size: int) -> None:
+        CACHE_ITEM_SIZE.labels(span_name=self._span_name).observe(item_size)
+
+
+class _PrometheusCacheRemoveSpan:
+    def record_removed(self) -> None:
+        pass
+
+
+class _PrometheusCacheCleanupSpan:
+    def record_cleanup(self, num_deleted: int) -> None:
+        CACHE_CLEANUP_LAST_RUN.set_to_current_time()
+        CACHE_CLEANUP_DELETED.set(num_deleted)
+
+
+class _PrometheusCacheFlushSpan:
+    def record_flush(self, num_flushed: int) -> None:
+        CACHE_FLUSHED_ENTRIES.observe(num_flushed)
+
+
+class PrometheusInstrumentation:
+    """
+    Prometheus-backed instrumentation for cache operations.
+    """
+
+    @contextmanager
+    def start_cache_get_span(
+        self, key: str, name: str | None
+    ) -> Iterator[CacheGetSpan]:
+        span_name = name or ""
+        with CACHE_GET_DURATION.labels(span_name=span_name).time():
+            yield _PrometheusCacheGetSpan(span_name)
+
+    @contextmanager
+    def start_cache_put_span(
+        self, key: str, name: str | None
+    ) -> Iterator[CachePutSpan]:
+        span_name = name or ""
+        with CACHE_PUT_DURATION.labels(span_name=span_name).time():
+            yield _PrometheusCachePutSpan(span_name)
+
+    @contextmanager
+    def start_cache_remove_span(self, key: str) -> Iterator[CacheRemoveSpan]:
+        with CACHE_REMOVE_DURATION.time():
+            yield _PrometheusCacheRemoveSpan()
+
+    @contextmanager
+    def start_cache_cleanup_span(
+        self,
+    ) -> Iterator[CacheCleanupSpan]:
+        yield _PrometheusCacheCleanupSpan()
+
+    @contextmanager
+    def start_cache_flush_span(
+        self,
+    ) -> Iterator[CacheFlushSpan]:
+        with CACHE_FLUSH_DURATION.time():
+            yield _PrometheusCacheFlushSpan()

psycache/instrumentation/sentry.py

@@ -0,0 +1,142 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Sentry-backed cache instrumentation.
+
+See also:
+
+  - <https://docs.sentry.io/platforms/python/tracing/instrumentation/custom-instrumentation/caches-module/>
+  - <https://develop.sentry.dev/sdk/telemetry/traces/modules/caches/>
+
+Span instances are not frozen because they're instantiated a lot so we go for
+performance.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import attrs
+import sentry_sdk
+
+from sentry_sdk.tracing import Span
+
+from psycache.instrumentation import NoopAnySpan
+from psycache.typing import (
+    CacheCleanupSpan,
+    CacheFlushSpan,
+    CacheGetSpan,
+    CachePutSpan,
+    CacheRemoveSpan,
+)
+
+
+@attrs.define
+class _SentryCacheGetSpan:
+    """
+    Sentry-backed span for cache get operations.
+    """
+
+    _key: str
+    _span: Span
+
+    def record_cache_hit(self, item_size: int) -> None:
+        self._span.set_data("cache.hit", True)
+        self._span.set_data("cache.item_size", item_size)
+        self._span.set_data("cache.success", True)
+
+    def record_cache_miss(self) -> None:
+        self._span.set_data("cache.hit", False)
+        self._span.set_data("cache.success", True)
+
+
+@attrs.define
+class _SentryCachePutSpan:
+    """
+    Sentry-backed span for cache put operations.
+    """
+
+    _key: str
+    _span: Span
+
+    def record_put(self, item_size: int) -> None:
+        self._span.set_data("cache.item_size", item_size)
+        self._span.set_data("cache.success", True)
+
+
+@attrs.define
+class _SentryCacheRemoveSpan:
+    """
+    Sentry-backed span for cache removal operations.
+    """
+
+    _key: str
+    _span: Span
+
+    def record_removed(self) -> None:
+        self._span.set_data("cache.success", True)
+
+
+@attrs.define
+class _SentryCacheFlushSpan:
+    """
+    Sentry-backed span for cache flush operations.
+    """
+
+    _span: Span
+
+    def record_flush(self, num_flushed: int) -> None:
+        self._span.set_data("cache.num_flushed", num_flushed)
+
+
+class SentryInstrumentation:
+    """
+    Sentry-backed instrumentation for cache operations.
+    """
+
+    @contextmanager
+    def start_cache_get_span(
+        self, key: str, name: str | None
+    ) -> Iterator[CacheGetSpan]:
+        with sentry_sdk.start_span(
+            op="cache.get", name=name or "psycache get"
+        ) as span:
+            span.set_data("cache.key", [key])
+
+            yield _SentryCacheGetSpan(key, span)
+
+    @contextmanager
+    def start_cache_put_span(
+        self, key: str, name: str | None
+    ) -> Iterator[CachePutSpan]:
+        with sentry_sdk.start_span(
+            op="cache.put", name=name or "psycache put"
+        ) as span:
+            span.set_data("cache.key", [key])
+
+            yield _SentryCachePutSpan(key, span)
+
+    @contextmanager
+    def start_cache_remove_span(self, key: str) -> Iterator[CacheRemoveSpan]:
+        with sentry_sdk.start_span(
+            op="cache.remove", name="psycache remove"
+        ) as span:
+            span.set_data("cache.key", [key])
+
+            yield _SentryCacheRemoveSpan(key, span)
+
+    @contextmanager
+    def start_cache_cleanup_span(
+        self,
+    ) -> Iterator[CacheCleanupSpan]:
+        yield NoopAnySpan()
+
+    @contextmanager
+    def start_cache_flush_span(
+        self,
+    ) -> Iterator[CacheFlushSpan]:
+        with sentry_sdk.start_span(
+            op="cache.flush", name="psycache flush"
+        ) as span:
+            yield _SentryCacheFlushSpan(span)

psycache/psycopg_pool.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Integration with `psycopg_pool`: <https://www.psycopg.org/psycopg3/docs/api/pool.html>
+"""
+
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any
+
+import attrs
+import psycopg
+
+from psycopg_pool import AsyncConnectionPool, ConnectionPool
+
+
+@attrs.frozen
+class PsycopgCachePool:
+    """
+    A cache pool based on `psycopg_pool.ConnectionPool`.
+    """
+
+    _pool: ConnectionPool[Any] = attrs.field(alias="pool")
+
+    @contextmanager
+    def connect(self) -> Iterator[psycopg.Connection]:
+        with self._pool.connection() as conn:
+            autocommit = conn.autocommit
+            conn.autocommit = True
+
+            try:
+                yield conn
+            finally:
+                conn.autocommit = autocommit
+
+
+@attrs.frozen
+class AsyncPsycopgCachePool:
+    """
+    A cache pool based on `psycopg_pool.AsyncConnectionPool`.
+    """
+
+    _pool: AsyncConnectionPool[Any] = attrs.field(alias="pool")
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator[psycopg.AsyncConnection]:
+        async with self._pool.connection() as conn:
+            autocommit = conn.autocommit
+            await conn.set_autocommit(True)
+
+            try:
+                yield conn
+            finally:
+                await conn.set_autocommit(autocommit)

psycache/sqlalchemy.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Hynek Schlawack <hs@ox.cx>
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Integration with SQLAlchemy.
+"""
+
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+
+import attrs
+import psycopg
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+
+@attrs.frozen
+class SQLAlchemyCachePool:
+    """
+    A cache pool based on a SQLAlchemy engine.
+    """
+
+    engine: Engine
+
+    @contextmanager
+    def connect(self) -> Iterator[psycopg.Connection]:
+        with self.engine.connect().execution_options(
+            isolation_level="AUTOCOMMIT"
+        ) as conn:
+            yield conn.connection  # type: ignore[misc]  # ty: ignore[invalid-yield]
+
+
+@attrs.frozen
+class AsyncSQLAlchemyCachePool:
+    """
+    A cache pool based on a SQLAlchemy async engine.
+    """
+
+    engine: AsyncEngine
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator[psycopg.AsyncConnection]:
+        async with self.engine.connect() as sa_conn:
+            conn = await sa_conn.execution_options(
+                isolation_level="AUTOCOMMIT"
+            )
+            raw = await conn.get_raw_connection()
+
+            yield raw.driver_connection  # type: ignore[misc]  # ty: ignore[invalid-yield]