devalerts 0.1.5__tar.gz → 0.2.1__tar.gz

{devalerts-0.1.5 → devalerts-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devalerts
-Version: 0.1.5
+Version: 0.2.1
 Summary: Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token.
 Keywords: telegram,error-tracking,exception-monitoring,alerts,logging,monitoring,asgi
 Author: sslinNn
@@ -77,7 +77,13 @@ chat instead of a log file nobody's watching.
 2. Message your bot once (or add it to a group) so it's allowed to message you back.
 3. Get your chat id — message [@userinfobot](https://t.me/userinfobot), or call
    `https://api.telegram.org/bot<TOKEN>/getUpdates` after step 2 and read `message.chat.id`.
-4. In your app, as early as possible:
+4. Verify it's wired up correctly before touching any code:
+
+   ```
+   uv run devalerts test --bot-token 123456:ABC-DEF... --chat-id 123456789
+   ```
+
+5. In your app, as early as possible:
 
 ```python
 import devalerts
@@ -88,6 +94,10 @@ devalerts.init(bot_token="123456:ABC-DEF...", chat_id=123456789)
 That's it — any unhandled exception (including ones raised in threads) now
 also lands in your Telegram chat.
 
+The traceback itself arrives folded into a collapsed quote — the exception
+type, message, and host are visible right away, tap to expand the full
+traceback. Keeps a big stack trace from taking over the chat.
+
 ## Grouping, rate limiting, and the dashboard
 
 Exceptions are grouped by fingerprint (exception type + file + line where it
@@ -109,6 +119,48 @@ uv run devalerts dashboard
 
 ![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
+Pass `--json` for machine-readable output. Silence a noisy group without
+touching code — the `ID` column accepts any unique prefix:
+
+```
+uv run devalerts mute abc12345
+uv run devalerts unmute abc12345
+uv run devalerts clear abc12345   # or: devalerts clear --all
+```
+
+Unmuting resends the next occurrence with the accumulated skip count, same
+as a rate-limit window expiring.
+
+Error groups that keep piling up while suppressed are chronic: each such
+resend doubles the effective `rate_limit_seconds` for that group (capped at
+8x), so a crash loop backs itself off instead of paging you every window
+forever. A group that goes quiet and reappears once resets to the base rate
+immediately. The dashboard shows the active multiplier (`● sending ×4`).
+
+## Context: hostname and tags
+
+Every alert automatically includes the sending host, so you can tell which
+process/server it came from when one bot serves several:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789, tags={"env": "production"})
+```
+
+```
+🔴 ValueError: boom
+🖥️ prod-web-2 (env=production)
+```
+
+Add ad-hoc tags to a single call — they override `init()`'s tags on a key
+collision:
+
+```python
+devalerts.report(extra={"request_id": "abc123"})
+
+@devalerts.capture(extra={"job": "nightly-sync"})
+def run_job(): ...
+```
+
 ## Manually reporting a caught exception
 
 ```python
@@ -148,6 +200,24 @@ Only exceptions that actually escape as server errors get reported — routing
 404s and raised `HTTPException`s are already turned into responses by the
 framework before the middleware sees them.
 
+## Celery
+
+Same problem as ASGI apps: `init()`'s excepthook never sees exceptions raised
+inside a task, because Celery catches them itself to record the task's
+`FAILURE` state. Call `init_celery()` in addition to `init()`:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789)
+devalerts.init_celery()
+```
+
+This connects to Celery's `task_failure` signal (fired once a task has
+genuinely failed — retries exhausted or none configured, so retried tasks
+don't spam an alert per attempt) and reports through the same
+grouping/rate-limiting/redaction path as everything else, tagged with the
+task name and id automatically. Requires Celery to already be installed in
+the worker process — it's imported lazily, not a devalerts dependency.
+
 ## Why not Sentry?
 
 If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
@@ -178,8 +248,8 @@ you want dedup state to survive restarts — it self-recreates otherwise.
 Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
 
 **Works with Celery / background workers?**
-Yes, `init()` in the worker process the same way as in a web process. For
-tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+Yes — call [`init_celery()`](#celery) in addition to `init()` to catch
+exceptions raised inside tasks, which the excepthook alone won't see.
 
 **Works on Windows / Linux / macOS?**
 Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
@@ -196,6 +266,9 @@ paths.
 - Basic secret redaction only (a few common token/key patterns) — do not
   rely on this for sensitive production data; scrub what you can before it
   ever reaches an exception message.
+- If Telegram delivery fails after retrying, the alert (already redacted, if
+  `redact=True`) is appended to `~/.devalerts/failed.log` instead of being
+  dropped — clean it up like any other local log file.
 
 ## What this does NOT do (by design)
 

{devalerts-0.1.5 → devalerts-0.2.1}/README.md

@@ -50,7 +50,13 @@ chat instead of a log file nobody's watching.
 2. Message your bot once (or add it to a group) so it's allowed to message you back.
 3. Get your chat id — message [@userinfobot](https://t.me/userinfobot), or call
    `https://api.telegram.org/bot<TOKEN>/getUpdates` after step 2 and read `message.chat.id`.
-4. In your app, as early as possible:
+4. Verify it's wired up correctly before touching any code:
+
+   ```
+   uv run devalerts test --bot-token 123456:ABC-DEF... --chat-id 123456789
+   ```
+
+5. In your app, as early as possible:
 
 ```python
 import devalerts
@@ -61,6 +67,10 @@ devalerts.init(bot_token="123456:ABC-DEF...", chat_id=123456789)
 That's it — any unhandled exception (including ones raised in threads) now
 also lands in your Telegram chat.
 
+The traceback itself arrives folded into a collapsed quote — the exception
+type, message, and host are visible right away, tap to expand the full
+traceback. Keeps a big stack trace from taking over the chat.
+
 ## Grouping, rate limiting, and the dashboard
 
 Exceptions are grouped by fingerprint (exception type + file + line where it
@@ -82,6 +92,48 @@ uv run devalerts dashboard
 
 ![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
+Pass `--json` for machine-readable output. Silence a noisy group without
+touching code — the `ID` column accepts any unique prefix:
+
+```
+uv run devalerts mute abc12345
+uv run devalerts unmute abc12345
+uv run devalerts clear abc12345   # or: devalerts clear --all
+```
+
+Unmuting resends the next occurrence with the accumulated skip count, same
+as a rate-limit window expiring.
+
+Error groups that keep piling up while suppressed are chronic: each such
+resend doubles the effective `rate_limit_seconds` for that group (capped at
+8x), so a crash loop backs itself off instead of paging you every window
+forever. A group that goes quiet and reappears once resets to the base rate
+immediately. The dashboard shows the active multiplier (`● sending ×4`).
+
+## Context: hostname and tags
+
+Every alert automatically includes the sending host, so you can tell which
+process/server it came from when one bot serves several:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789, tags={"env": "production"})
+```
+
+```
+🔴 ValueError: boom
+🖥️ prod-web-2 (env=production)
+```
+
+Add ad-hoc tags to a single call — they override `init()`'s tags on a key
+collision:
+
+```python
+devalerts.report(extra={"request_id": "abc123"})
+
+@devalerts.capture(extra={"job": "nightly-sync"})
+def run_job(): ...
+```
+
 ## Manually reporting a caught exception
 
 ```python
@@ -121,6 +173,24 @@ Only exceptions that actually escape as server errors get reported — routing
 404s and raised `HTTPException`s are already turned into responses by the
 framework before the middleware sees them.
 
+## Celery
+
+Same problem as ASGI apps: `init()`'s excepthook never sees exceptions raised
+inside a task, because Celery catches them itself to record the task's
+`FAILURE` state. Call `init_celery()` in addition to `init()`:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789)
+devalerts.init_celery()
+```
+
+This connects to Celery's `task_failure` signal (fired once a task has
+genuinely failed — retries exhausted or none configured, so retried tasks
+don't spam an alert per attempt) and reports through the same
+grouping/rate-limiting/redaction path as everything else, tagged with the
+task name and id automatically. Requires Celery to already be installed in
+the worker process — it's imported lazily, not a devalerts dependency.
+
 ## Why not Sentry?
 
 If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
@@ -151,8 +221,8 @@ you want dedup state to survive restarts — it self-recreates otherwise.
 Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
 
 **Works with Celery / background workers?**
-Yes, `init()` in the worker process the same way as in a web process. For
-tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+Yes — call [`init_celery()`](#celery) in addition to `init()` to catch
+exceptions raised inside tasks, which the excepthook alone won't see.
 
 **Works on Windows / Linux / macOS?**
 Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
@@ -169,6 +239,9 @@ paths.
 - Basic secret redaction only (a few common token/key patterns) — do not
   rely on this for sensitive production data; scrub what you can before it
   ever reaches an exception message.
+- If Telegram delivery fails after retrying, the alert (already redacted, if
+  `redact=True`) is appended to `~/.devalerts/failed.log` instead of being
+  dropped — clean it up like any other local log file.
 
 ## What this does NOT do (by design)
 

{devalerts-0.1.5 → devalerts-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devalerts"
-version = "0.1.5"
+version = "0.2.1"
 description = "Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token."
 readme = "README.md"
 license = "MIT"
@@ -48,6 +48,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "celery>=5.3.0",
     "mypy>=1.19.1",
     "pre-commit>=4.3.0",
     "pytest>=8.4.2",

{devalerts-0.1.5 → devalerts-0.2.1}/src/devalerts/__init__.py

@@ -9,10 +9,11 @@ from types import TracebackType
 from typing import Callable, Literal, Optional, TypedDict
 
 from ._alert import _format_alert, _redact
+from ._celery import init_celery
 from ._store import _DEFAULT_RATE_LIMIT_SECONDS, _fingerprint, _should_send
 from ._telegram import _send_telegram_message
 
-__all__: list[str] = ["init", "report", "capture", "ASGIMiddleware"]
+__all__: list[str] = ["init", "report", "capture", "ASGIMiddleware", "init_celery"]
 
 _ExceptHook = Callable[
     [type[BaseException], BaseException, Optional[TracebackType]], object
@@ -25,6 +26,7 @@ class _State(TypedDict):
     chat_id: int | str | None
     redact: bool
     rate_limit_seconds: int
+    tags: dict[str, str]
     # Seeded with the real default hooks below (never None) -- _excepthook/
     # _threading_excepthook can only ever fire after init() has replaced
     # sys.excepthook/threading.excepthook, by which point these are always
@@ -38,12 +40,15 @@ _state: _State = {
     "chat_id": None,
     "redact": True,
     "rate_limit_seconds": _DEFAULT_RATE_LIMIT_SECONDS,
+    "tags": {},
     "prev_excepthook": sys.excepthook,
     "prev_threading_excepthook": threading.excepthook,
 }
 
 
-def _send_exception(exc_type, exc_value, tb) -> None:
+def _send_exception(
+    exc_type, exc_value, tb, extra: dict[str, str] | None = None
+) -> None:
     if _state["bot_token"] is None or _state["chat_id"] is None:
         print("devalerts: init() was not called, dropping alert", file=sys.stderr)
         return
@@ -53,7 +58,8 @@ def _send_exception(exc_type, exc_value, tb) -> None:
     )
     if not send:
         return
-    message = _format_alert(exc_type, exc_value, tb, skipped=skipped)
+    tags = {**_state["tags"], **(extra or {})}
+    message = _format_alert(exc_type, exc_value, tb, skipped=skipped, tags=tags)
     if _state["redact"]:
         message = _redact(message)
     _send_telegram_message(_state["bot_token"], _state["chat_id"], message)
@@ -87,12 +93,14 @@ def init(
     *,
     redact: bool = True,
     rate_limit_seconds: int = _DEFAULT_RATE_LIMIT_SECONDS,
+    tags: dict[str, str] | None = None,
 ) -> None:
     """Install a global exception hook that sends unhandled exceptions to Telegram."""
     _state["bot_token"] = bot_token
     _state["chat_id"] = chat_id
     _state["redact"] = redact
     _state["rate_limit_seconds"] = rate_limit_seconds
+    _state["tags"] = tags or {}
     # ponytail: guard against calling init() twice capturing our own hook as
     # "previous" -- that would make _excepthook chain to itself and recurse
     # forever on the next crash, violating "must never raise".
@@ -104,7 +112,9 @@ def init(
     threading.excepthook = _threading_excepthook
 
 
-def report(exc: BaseException | None = None) -> None:
+def report(
+    exc: BaseException | None = None, *, extra: dict[str, str] | None = None
+) -> None:
     """Manually send a caught exception to Telegram."""
     if exc is None:
         exc_type, exc_value, tb = sys.exc_info()
@@ -114,7 +124,7 @@ def report(exc: BaseException | None = None) -> None:
             )
     else:
         exc_type, exc_value, tb = type(exc), exc, exc.__traceback__
-    _send_exception(exc_type, exc_value, tb)
+    _send_exception(exc_type, exc_value, tb, extra=extra)
 
 
 class capture(contextlib.ContextDecorator):
@@ -122,12 +132,15 @@ class capture(contextlib.ContextDecorator):
     function, then re-raise it. Use ``@capture()`` on a function instead of wrapping
     its body in a manual ``try/except`` or ``with`` block."""
 
+    def __init__(self, *, extra: dict[str, str] | None = None) -> None:
+        self._extra = extra
+
     def __enter__(self) -> "capture":
         return self
 
     def __exit__(self, exc_type, exc_value, tb) -> Literal[False]:
         if exc_type is not None:
-            _send_exception(exc_type, exc_value, tb)
+            _send_exception(exc_type, exc_value, tb, extra=self._extra)
         return False
 
 

devalerts-0.2.1/src/devalerts/_alert.py

@@ -0,0 +1,71 @@
+"""Alert message formatting and secret redaction."""
+
+from __future__ import annotations
+
+import re
+import socket
+import traceback
+
+_MAX_MESSAGE_LENGTH = 4096
+
+
+def _escape_html(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _format_context(tags: dict[str, str] | None) -> str:
+    try:
+        hostname = socket.gethostname()
+    except OSError:
+        hostname = "unknown-host"
+    line = f"🖥️ {hostname}"
+    if tags:
+        line += " (" + ", ".join(f"{key}={value}" for key, value in tags.items()) + ")"
+    return line
+
+
+def _format_alert(
+    exc_type, exc_value, tb, skipped: int = 0, tags: dict[str, str] | None = None
+) -> str:
+    header = f"\U0001f534 {exc_type.__name__}: {exc_value}\n{_format_context(tags)}"
+    if skipped:
+        header += f"\n⚠️ Повторилась ещё {skipped} раз(а) с последнего алерта"
+    body = "".join(traceback.format_exception(exc_type, exc_value, tb))
+
+    if len(header) + 2 + len(body) > _MAX_MESSAGE_LENGTH:
+        marker = "\n\n...(truncated)...\n"
+        # ponytail: header itself can exceed the limit if exc_value's str() is huge
+        # (e.g. a validation error echoing a large payload) — keep can go negative,
+        # so clamp it; the header itself gets hard-truncated as a backstop. The "2"
+        # accounts for the "\n\n" separator joined in below.
+        keep = max(_MAX_MESSAGE_LENGTH - len(header) - 2 - len(marker), 0)
+        body = f"{marker}{body[-keep:]}" if keep else ""
+        header = header[:_MAX_MESSAGE_LENGTH]
+
+    # Budgeted above against the plain text -- Telegram's 4096-char limit
+    # applies to the parsed (tag-stripped) text, not the raw HTML we send.
+    escaped_header = _escape_html(header)
+    if not body:
+        return escaped_header
+    return (
+        f"{escaped_header}\n\n<blockquote expandable>{_escape_html(body)}</blockquote>"
+    )
+
+
+# ponytail: fixed pattern list, not exhaustive — catches common
+# token/key shapes only. Upgrade to entropy-based detection if
+# real users report leaked secrets slipping through.
+_REDACT_PATTERNS = [
+    (re.compile(r"AKIA[0-9A-Z]{16}"), "[REDACTED]"),
+    (re.compile(r"Bearer\s+[A-Za-z0-9\-_.]+", re.IGNORECASE), "Bearer [REDACTED]"),
+    (
+        re.compile(r"(?i)(api[_-]?key|secret|token|password)\s*[=:]\s*\S+"),
+        r"\1=[REDACTED]",
+    ),
+]
+
+
+def _redact(text: str) -> str:
+    for pattern, replacement in _REDACT_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text

devalerts-0.2.1/src/devalerts/_celery.py

@@ -0,0 +1,45 @@
+"""Optional Celery integration: report task failures that Celery's own trace
+machinery swallows before they ever reach sys.excepthook -- the same problem
+ASGIMiddleware solves for FastAPI/Starlette request errors."""
+
+from __future__ import annotations
+
+_connected = False
+
+
+def init_celery() -> None:
+    """Report Celery task failures to Telegram. Call in addition to init(),
+    which never sees exceptions raised inside a task -- Celery catches those
+    itself to record the task's FAILURE state.
+
+    Usage::
+
+        devalerts.init(bot_token="...", chat_id=123456789)
+        devalerts.init_celery()
+
+    Requires Celery to already be installed in the worker process (not a
+    devalerts dependency -- imported lazily here).
+    """
+    global _connected
+    if _connected:
+        return
+    from celery.signals import task_failure  # type: ignore[import-untyped]
+
+    task_failure.connect(_on_task_failure, weak=False)
+    _connected = True
+
+
+def _on_task_failure(
+    sender=None, task_id=None, exception=None, traceback=None, **_kwargs
+) -> None:
+    from . import _send_exception
+
+    if exception is None:
+        return
+    tags: dict[str, str] = {}
+    if task_id is not None:
+        tags["task_id"] = str(task_id)
+    if sender is not None:
+        tags["task"] = getattr(sender, "name", type(sender).__name__)
+    exc = exception.with_traceback(traceback) if traceback is not None else exception
+    _send_exception(type(exc), exc, exc.__traceback__, extra=tags)

devalerts-0.2.1/src/devalerts/_store.py

@@ -0,0 +1,191 @@
+"""Local SQLite state: fingerprint-based grouping, dedup, and rate limiting."""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import sys
+import time
+import traceback
+from pathlib import Path
+
+_DB_PATH = Path.home() / ".devalerts" / "state.db"
+_RETENTION_SECONDS = 7 * 24 * 3600
+_DEFAULT_RATE_LIMIT_SECONDS = 300
+# ponytail: fixed cap, not configurable -- upgrade to an init() param if
+# users report the ceiling being wrong for their crash-loop cadence.
+_MAX_BACKOFF_MULTIPLIER = 8
+
+
+def _fingerprint(exc_type, tb) -> tuple[str, str]:
+    frames = traceback.extract_tb(tb)
+    location = f"{frames[-1].filename}:{frames[-1].lineno}" if frames else "unknown"
+    raw = f"{exc_type.__name__}:{location}"
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16], location
+
+
+def _get_connection() -> sqlite3.Connection:
+    _DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(_DB_PATH, timeout=5)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS error_groups (
+            fingerprint TEXT PRIMARY KEY,
+            exc_type TEXT NOT NULL,
+            location TEXT NOT NULL,
+            first_seen REAL NOT NULL,
+            last_seen REAL NOT NULL,
+            last_sent REAL,
+            count_since_last_sent INTEGER NOT NULL DEFAULT 0,
+            total_count INTEGER NOT NULL DEFAULT 0,
+            rate_limit_seconds INTEGER,
+            muted INTEGER NOT NULL DEFAULT 0,
+            backoff_multiplier INTEGER NOT NULL DEFAULT 1
+        )
+        """
+    )
+    # ponytail: lazy migration for DBs created before these columns existed --
+    # ADD COLUMN has no "IF NOT EXISTS", so swallow the duplicate-column error
+    # on every subsequent call instead of tracking schema version.
+    for ddl in (
+        "ALTER TABLE error_groups ADD COLUMN rate_limit_seconds INTEGER",
+        "ALTER TABLE error_groups ADD COLUMN muted INTEGER NOT NULL DEFAULT 0",
+        "ALTER TABLE error_groups ADD COLUMN backoff_multiplier INTEGER NOT NULL DEFAULT 1",
+    ):
+        try:
+            conn.execute(ddl)
+        except sqlite3.OperationalError:
+            pass
+    return conn
+
+
+def _should_send(
+    fingerprint: str, exc_type_name: str, location: str, rate_limit_seconds: int
+) -> tuple[bool, int]:
+    now = time.time()
+    try:
+        conn = _get_connection()
+        try:
+            with conn:
+                row = conn.execute(
+                    "SELECT last_sent, count_since_last_sent, muted, backoff_multiplier "
+                    "FROM error_groups WHERE fingerprint = ?",
+                    (fingerprint,),
+                ).fetchone()
+                muted = bool(row[2]) if row else False
+                multiplier = row[3] if row else 1
+                effective_window = rate_limit_seconds * multiplier
+                if not muted and (
+                    row is None or row[0] is None or now - row[0] >= effective_window
+                ):
+                    send, skipped = True, (row[1] if row else 0)
+                    # Chronic (occurrences piled up while suppressed) doubles the
+                    # backoff, capped at _MAX_BACKOFF_MULTIPLIER; a single fresh
+                    # occurrence after a genuine quiet spell resets it to 1.
+                    new_multiplier = (
+                        min(multiplier * 2, _MAX_BACKOFF_MULTIPLIER) if skipped else 1
+                    )
+                    conn.execute(
+                        """
+                        INSERT INTO error_groups
+                            (fingerprint, exc_type, location, first_seen, last_seen,
+                             last_sent, count_since_last_sent, total_count,
+                             rate_limit_seconds, backoff_multiplier)
+                        VALUES (?, ?, ?, ?, ?, ?, 0, 1, ?, ?)
+                        ON CONFLICT(fingerprint) DO UPDATE SET
+                            last_seen = excluded.last_seen,
+                            last_sent = excluded.last_sent,
+                            count_since_last_sent = 0,
+                            total_count = total_count + 1,
+                            rate_limit_seconds = excluded.rate_limit_seconds,
+                            backoff_multiplier = excluded.backoff_multiplier
+                        """,
+                        (
+                            fingerprint,
+                            exc_type_name,
+                            location,
+                            now,
+                            now,
+                            now,
+                            rate_limit_seconds,
+                            new_multiplier,
+                        ),
+                    )
+                else:
+                    # Covers both "still rate-limited" and "muted" -- neither sends,
+                    # both keep counting so an eventual unmute/window-expiry reports
+                    # the accumulated skip count via count_since_last_sent.
+                    send, skipped = False, 0
+                    conn.execute(
+                        """
+                        UPDATE error_groups
+                        SET last_seen = ?, count_since_last_sent = count_since_last_sent + 1,
+                            total_count = total_count + 1, rate_limit_seconds = ?
+                        WHERE fingerprint = ?
+                        """,
+                        (now, rate_limit_seconds, fingerprint),
+                    )
+                conn.execute(
+                    "DELETE FROM error_groups WHERE last_seen < ?",
+                    (now - _RETENTION_SECONDS,),
+                )
+            return send, skipped
+        finally:
+            conn.close()
+    except (sqlite3.Error, OSError) as error:
+        # ponytail: dedup/rate-limit state must never block an alert -- fail
+        # open (send, as if this were the first occurrence) on any DB error.
+        print(
+            f"devalerts: dedup/rate-limit state error, sending anyway: {error}",
+            file=sys.stderr,
+        )
+        return True, 0
+
+
+def _match_fingerprints(prefix: str) -> list[str]:
+    """Fingerprints starting with prefix, for CLI mute/unmute/clear commands."""
+    conn = _get_connection()
+    try:
+        rows = conn.execute(
+            "SELECT fingerprint FROM error_groups WHERE fingerprint LIKE ? ESCAPE '\\'",
+            (
+                prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+                + "%",
+            ),
+        ).fetchall()
+    finally:
+        conn.close()
+    return [row[0] for row in rows]
+
+
+def _set_muted(fingerprint: str, muted: bool) -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute(
+                "UPDATE error_groups SET muted = ? WHERE fingerprint = ?",
+                (int(muted), fingerprint),
+            )
+    finally:
+        conn.close()
+
+
+def _clear(fingerprint: str) -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute(
+                "DELETE FROM error_groups WHERE fingerprint = ?", (fingerprint,)
+            )
+    finally:
+        conn.close()
+
+
+def _clear_all() -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute("DELETE FROM error_groups")
+    finally:
+        conn.close()