nahiarhdlog 0.1.0__tar.gz

nahiarhdlog-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Raihan Hidayatullah Djunaedi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nahiarhdlog-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md
+global-exclude *.db *.db-shm *.db-wal
+global-exclude __pycache__ *.py[cod]

nahiarhdlog-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: nahiarhdlog
+Version: 0.1.0
+Summary: Embedded observability for FastAPI: searchable logs, error tracking, alerts, metrics, and tracing
+Author-email: Raihan Hidayatullah Djunaedi <raihanhd.dev@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nahiarhd/nahiarhdlog
+Project-URL: Documentation, https://github.com/nahiarhd/nahiarhdlog#readme
+Project-URL: Repository, https://github.com/nahiarhd/nahiarhdlog
+Project-URL: Issues, https://github.com/nahiarhd/nahiarhdlog/issues
+Keywords: fastapi,logging,observability,monitoring,error-tracking,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: uvicorn>=0.24.0; extra == "dev"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Dynamic: license-file
+
+# nahiarhdlog
+
+[![PyPI version](https://img.shields.io/pypi/v/nahiarhdlog.svg)](https://pypi.org/project/nahiarhdlog/)
+[![Python Version](https://img.shields.io/pypi/pyversions/nahiarhdlog.svg)](https://pypi.org/project/nahiarhdlog/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Embedded observability for FastAPI: searchable logs, error tracking, alerts, metrics, and tracing — with zero-config defaults.
+
+```python
+from fastapi import FastAPI
+from nahiarhdLOG import observe
+
+app = FastAPI()
+observe(app, dashboard_token="secret")  # logs + errors + metrics + dashboard
+```
+
+> **Status:** FastAPI is supported first. The core is framework-agnostic, so Flask/Django adapters can follow without changing it.
+
+## 2-minute install
+
+```bash
+pip install nahiarhdlog
+```
+
+Requires Python >= 3.10. No servers, no agents, no config files: events are stored in a local SQLite file (`nahiarhdlog.db`).
+
+## Quick start
+
+```python
+import logging
+from fastapi import FastAPI
+from nahiarhdLOG import observe
+
+app = FastAPI()
+observe(app, dashboard_token="secret")
+
+log = logging.getLogger(__name__)
+
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    log.info("fetching user %d", user_id)
+    return {"id": user_id}
+```
+
+That's it. Every request, every stdlib log record, and every uncaught exception is now captured. Open the dashboard at `/admin/logs` (enter the token on the lock screen).
+
+## Features
+
+| Area | What you get |
+| ---- | ------------ |
+| Logs | Auto-captured stdlib records + requests; full-text search (FTS5), level/type/time/trace filters, pagination |
+| Errors | Grouped by `ExcType@file.py:line`, full tracebacks, top-errors ranking |
+| Alerts | Threshold rules (N events in M seconds) + cooldown; webhook, Telegram, and SMTP sinks |
+| Metrics | RPS, error rate, latency p50/p95, time-bucketed series — computed from the same request events |
+| Tracing | One `trace_id` per request shared by logs and errors; timeline view; optional OpenTelemetry export |
+| Dashboard | Embedded at `/admin/logs`, token-locked, dark/light mode, mobile-friendly, live tail |
+
+Design limits (on purpose): bounded in-memory queue (full → drop + visible counter, requests are never blocked), batched async writes, paginated queries. Measured middleware overhead: p95 ~0.04 ms (see `scripts/probe_perf.py`).
+
+## Configuration
+
+```python
+from nahiarhdLOG.alerter import Rule, TelegramSink, WebhookSink
+
+observe(
+    app,
+    db_path="nahiarhdlog.db",   # local SQLite file (WAL mode)
+    retention_days=7,            # auto-purge older events
+    sample_rate=1.0,             # 1.0 = every request; 500s are always kept
+    level=logging.INFO,          # minimum stdlib level captured
+    rules=[Rule("errors", count=5, window_seconds=300, cooldown_seconds=3600)],
+    sinks=[TelegramSink(bot_token="...", chat_id="...")],
+    dashboard_prefix="/admin/logs",
+    dashboard_token="secret",    # omit to disable the dashboard entirely
+    skip_paths=["/healthz"],     # extra paths the middleware ignores
+)
+```
+
+The dashboard's own traffic is never logged, so live tail can't flood itself.
+
+### Alert sinks
+
+```python
+from nahiarhdLOG.alerter import Rule, SmtpSink, TelegramSink, WebhookSink
+
+rules = [Rule("api-errors", count=10, window_seconds=600, cooldown_seconds=1800)]
+sinks = [
+    WebhookSink("https://hooks.example/deploy"),          # POSTs {"subject","body"} as JSON
+    TelegramSink(bot_token="123:ABC", chat_id="-100..."),  # Bot API sendMessage
+    SmtpSink("smtp.example.com", ["ops@example.com"], username="bot", password="..."),
+]
+```
+
+Rules evaluate in a background thread; a failing sink never blocks the others.
+
+### OpenTelemetry export (optional)
+
+```bash
+pip install "nahiarhdlog[otel]"
+```
+
+```python
+from nahiarhdLOG.otel import export_trace
+from nahiarhdLOG.query import get_trace
+
+export_trace(get_trace(collector.storage, trace_id))  # keeps the original trace id
+```
+
+## Example app
+
+```bash
+# terminal 1: run the demo
+uv run python examples/basic_app.py serve
+
+# terminal 2: generate traffic
+uv run python examples/basic_app.py traffic --n 300
+```
+
+Open `http://127.0.0.1:8000/admin/logs` with token `demo-token`.
+
+## FAQ
+
+**Which Python versions?** 3.10+ (3.10, 3.11, 3.12 tested in CI).
+
+**Where is data stored?** One SQLite file (`db_path`), WAL mode, FTS5 index for search. Delete the file to wipe everything. Set `retention_days` for automatic purging.
+
+**Is the dashboard secure?** It is mounted only when `dashboard_token` is set, and every page + API call requires the token (query param or `Authorization: Bearer`). Without it you get a lock screen (401). Use a long random token and HTTPS in production.
+
+**Why don't I see the dashboard's own requests in the logs?** By design: the dashboard prefix is auto-excluded so its polling doesn't drown your signal. Add more with `skip_paths`.
+
+**What's the overhead?** Requests only enqueue a small dict; SQLite writes happen in batches on a background thread. Run `python scripts/probe_perf.py` to measure on your machine.
+
+**Flask / Django / plain scripts?** On the roadmap. The core (`collector`, `storage`, `query`, `alerter`, `metrics`) imports no web framework — only the thin `adapters/` layer does, enforced by an automated boundary test.
+
+**How do I disable the dashboard?** Omit `dashboard_token` (default): nothing is mounted.
+
+## Roadmap
+
+- [x] Core logging, SQLite+FTS5 storage, search API
+- [x] Error tracker + webhook alerts
+- [x] Metrics + tracing (+ optional OpenTelemetry export)
+- [x] Embedded dashboard UI
+- [ ] Flask/Django adapters
+- [ ] Postgres storage backend
+
+## Development
+
+```bash
+uv pip install -e ".[dev,otel]"
+uv run --no-sync python -m pytest   # run via python -m (see note below)
+uv run --no-sync python scripts/probe_perf.py --n 10000
+```
+
+> Note (macOS quirk, this machine): something on this Mac re-applies the Finder's `hidden` flag to dot-directory contents, which makes CPython silently skip `.pth` files and breaks console-script entry points in `.venv`. Running tests via `python -m` (imports from the source tree) is immune, as are regular installs and CI. If a console script ever reports `ModuleNotFoundError`, run `chflags -R nohidden .venv` and prefer `python -m`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+By [Raihan Hidayatullah Djunaedi](https://github.com/nahiarhd) · [nahiarhd.com](https://nahiarhd.com) · PyPI [@nahiarhd](https://pypi.org/user/nahiarhd/)

nahiarhdlog-0.1.0/README.md

@@ -0,0 +1,160 @@
+# nahiarhdlog
+
+[![PyPI version](https://img.shields.io/pypi/v/nahiarhdlog.svg)](https://pypi.org/project/nahiarhdlog/)
+[![Python Version](https://img.shields.io/pypi/pyversions/nahiarhdlog.svg)](https://pypi.org/project/nahiarhdlog/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Embedded observability for FastAPI: searchable logs, error tracking, alerts, metrics, and tracing — with zero-config defaults.
+
+```python
+from fastapi import FastAPI
+from nahiarhdLOG import observe
+
+app = FastAPI()
+observe(app, dashboard_token="secret")  # logs + errors + metrics + dashboard
+```
+
+> **Status:** FastAPI is supported first. The core is framework-agnostic, so Flask/Django adapters can follow without changing it.
+
+## 2-minute install
+
+```bash
+pip install nahiarhdlog
+```
+
+Requires Python >= 3.10. No servers, no agents, no config files: events are stored in a local SQLite file (`nahiarhdlog.db`).
+
+## Quick start
+
+```python
+import logging
+from fastapi import FastAPI
+from nahiarhdLOG import observe
+
+app = FastAPI()
+observe(app, dashboard_token="secret")
+
+log = logging.getLogger(__name__)
+
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    log.info("fetching user %d", user_id)
+    return {"id": user_id}
+```
+
+That's it. Every request, every stdlib log record, and every uncaught exception is now captured. Open the dashboard at `/admin/logs` (enter the token on the lock screen).
+
+## Features
+
+| Area | What you get |
+| ---- | ------------ |
+| Logs | Auto-captured stdlib records + requests; full-text search (FTS5), level/type/time/trace filters, pagination |
+| Errors | Grouped by `ExcType@file.py:line`, full tracebacks, top-errors ranking |
+| Alerts | Threshold rules (N events in M seconds) + cooldown; webhook, Telegram, and SMTP sinks |
+| Metrics | RPS, error rate, latency p50/p95, time-bucketed series — computed from the same request events |
+| Tracing | One `trace_id` per request shared by logs and errors; timeline view; optional OpenTelemetry export |
+| Dashboard | Embedded at `/admin/logs`, token-locked, dark/light mode, mobile-friendly, live tail |
+
+Design limits (on purpose): bounded in-memory queue (full → drop + visible counter, requests are never blocked), batched async writes, paginated queries. Measured middleware overhead: p95 ~0.04 ms (see `scripts/probe_perf.py`).
+
+## Configuration
+
+```python
+from nahiarhdLOG.alerter import Rule, TelegramSink, WebhookSink
+
+observe(
+    app,
+    db_path="nahiarhdlog.db",   # local SQLite file (WAL mode)
+    retention_days=7,            # auto-purge older events
+    sample_rate=1.0,             # 1.0 = every request; 500s are always kept
+    level=logging.INFO,          # minimum stdlib level captured
+    rules=[Rule("errors", count=5, window_seconds=300, cooldown_seconds=3600)],
+    sinks=[TelegramSink(bot_token="...", chat_id="...")],
+    dashboard_prefix="/admin/logs",
+    dashboard_token="secret",    # omit to disable the dashboard entirely
+    skip_paths=["/healthz"],     # extra paths the middleware ignores
+)
+```
+
+The dashboard's own traffic is never logged, so live tail can't flood itself.
+
+### Alert sinks
+
+```python
+from nahiarhdLOG.alerter import Rule, SmtpSink, TelegramSink, WebhookSink
+
+rules = [Rule("api-errors", count=10, window_seconds=600, cooldown_seconds=1800)]
+sinks = [
+    WebhookSink("https://hooks.example/deploy"),          # POSTs {"subject","body"} as JSON
+    TelegramSink(bot_token="123:ABC", chat_id="-100..."),  # Bot API sendMessage
+    SmtpSink("smtp.example.com", ["ops@example.com"], username="bot", password="..."),
+]
+```
+
+Rules evaluate in a background thread; a failing sink never blocks the others.
+
+### OpenTelemetry export (optional)
+
+```bash
+pip install "nahiarhdlog[otel]"
+```
+
+```python
+from nahiarhdLOG.otel import export_trace
+from nahiarhdLOG.query import get_trace
+
+export_trace(get_trace(collector.storage, trace_id))  # keeps the original trace id
+```
+
+## Example app
+
+```bash
+# terminal 1: run the demo
+uv run python examples/basic_app.py serve
+
+# terminal 2: generate traffic
+uv run python examples/basic_app.py traffic --n 300
+```
+
+Open `http://127.0.0.1:8000/admin/logs` with token `demo-token`.
+
+## FAQ
+
+**Which Python versions?** 3.10+ (3.10, 3.11, 3.12 tested in CI).
+
+**Where is data stored?** One SQLite file (`db_path`), WAL mode, FTS5 index for search. Delete the file to wipe everything. Set `retention_days` for automatic purging.
+
+**Is the dashboard secure?** It is mounted only when `dashboard_token` is set, and every page + API call requires the token (query param or `Authorization: Bearer`). Without it you get a lock screen (401). Use a long random token and HTTPS in production.
+
+**Why don't I see the dashboard's own requests in the logs?** By design: the dashboard prefix is auto-excluded so its polling doesn't drown your signal. Add more with `skip_paths`.
+
+**What's the overhead?** Requests only enqueue a small dict; SQLite writes happen in batches on a background thread. Run `python scripts/probe_perf.py` to measure on your machine.
+
+**Flask / Django / plain scripts?** On the roadmap. The core (`collector`, `storage`, `query`, `alerter`, `metrics`) imports no web framework — only the thin `adapters/` layer does, enforced by an automated boundary test.
+
+**How do I disable the dashboard?** Omit `dashboard_token` (default): nothing is mounted.
+
+## Roadmap
+
+- [x] Core logging, SQLite+FTS5 storage, search API
+- [x] Error tracker + webhook alerts
+- [x] Metrics + tracing (+ optional OpenTelemetry export)
+- [x] Embedded dashboard UI
+- [ ] Flask/Django adapters
+- [ ] Postgres storage backend
+
+## Development
+
+```bash
+uv pip install -e ".[dev,otel]"
+uv run --no-sync python -m pytest   # run via python -m (see note below)
+uv run --no-sync python scripts/probe_perf.py --n 10000
+```
+
+> Note (macOS quirk, this machine): something on this Mac re-applies the Finder's `hidden` flag to dot-directory contents, which makes CPython silently skip `.pth` files and breaks console-script entry points in `.venv`. Running tests via `python -m` (imports from the source tree) is immune, as are regular installs and CI. If a console script ever reports `ModuleNotFoundError`, run `chflags -R nohidden .venv` and prefer `python -m`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+By [Raihan Hidayatullah Djunaedi](https://github.com/nahiarhd) · [nahiarhd.com](https://nahiarhd.com) · PyPI [@nahiarhd](https://pypi.org/user/nahiarhd/)

nahiarhdlog-0.1.0/nahiarhdLOG/__init__.py

@@ -0,0 +1,20 @@
+"""nahiarhdlog: embedded observability for FastAPI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .collector import Collector
+
+__version__ = "0.1.0"
+__all__ = ["__version__", "Collector", "observe"]
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy so `import nahiarhdLOG` never requires FastAPI; only the
+    # framework adapter does.
+    if name == "observe":
+        from .adapters.fastapi import observe
+
+        return observe
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nahiarhdlog-0.1.0/nahiarhdLOG/adapters/fastapi.py

@@ -0,0 +1,75 @@
+"""FastAPI adapter: the only module (with the dashboard) allowed to
+import FastAPI/Starlette. One call wires middleware + handler + excepthook."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..alerter import Alerter, AlertSink, Rule
+from ..collector import Collector
+from ..handler import NahiarhdHandler, install_excepthook
+from ..middleware import LoggingMiddleware
+
+
+def _ensure_handler(collector: Collector, level: int) -> None:
+    root = logging.getLogger()
+    for h in root.handlers:
+        if isinstance(h, NahiarhdHandler) and h.collector is collector:
+            h.setLevel(level)
+            return
+    root.addHandler(NahiarhdHandler(collector, level=level))
+
+
+def observe(
+    app: Any,
+    db_path: str = "nahiarhdlog.db",
+    retention_days: int = 7,
+    sample_rate: float = 1.0,
+    level: int = logging.INFO,
+    rules: list[Rule] | None = None,
+    sinks: list[AlertSink] | None = None,
+    dashboard_prefix: str = "/admin/logs",
+    dashboard_token: str | None = None,
+    skip_paths: list[str] | None = None,
+) -> Collector:
+    """Attach nahiarhdlog to a FastAPI app. Returns the collector.
+
+    The dashboard is mounted only when `dashboard_token` is set: it must
+    never be reachable without a key. The dashboard's own traffic is never
+    logged, so live tail can't flood itself.
+    """
+    alerter = None
+    if rules and sinks:
+        alerter = Alerter(rules, sinks).start()
+    collector = Collector(
+        db_path, retention_days=retention_days, alerter=alerter
+    ).start()
+    prefix = (dashboard_prefix or "/admin/logs").rstrip("/") or "/admin/logs"
+    skips = list(skip_paths or [])
+    if dashboard_token and prefix not in skips:
+        skips.append(prefix)
+    app.add_middleware(
+        LoggingMiddleware,
+        collector=collector,
+        sample_rate=sample_rate,
+        skip_prefixes=tuple(skips),
+    )
+    _ensure_handler(collector, level)
+    install_excepthook(collector)
+    if dashboard_token:
+        from ..dashboard.router import create_dashboard_router
+
+        app.include_router(
+            create_dashboard_router(collector, dashboard_token), prefix=prefix
+        )
+
+    def _shutdown() -> None:
+        collector.stop()
+        if alerter is not None:
+            alerter.stop()
+
+    shutdown = getattr(getattr(app, "router", None), "on_shutdown", None)
+    if shutdown is not None:
+        shutdown.append(_shutdown)
+    return collector

nahiarhdlog-0.1.0/nahiarhdLOG/alerter.py

@@ -0,0 +1,196 @@
+"""Threshold alerting with cooldown.
+
+Framework-agnostic: this module must never import FastAPI/Starlette.
+Windows are in-memory; a restart resets counters (documented behavior).
+"""
+
+from __future__ import annotations
+
+import queue
+import smtplib
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from email.message import EmailMessage
+from typing import Any, Callable
+
+import httpx
+
+_TELEGRAM_API = "https://api.telegram.org"
+_HTTP_TIMEOUT = 10.0
+
+
+@dataclass(frozen=True)
+class Rule:
+    """Fire when `count` matching events arrive within `window_seconds`."""
+
+    name: str
+    count: int = 5
+    window_seconds: float = 300.0
+    cooldown_seconds: float = 3600.0
+    event_type: str = "error"
+
+
+class AlertSink:
+    def send(self, subject: str, body: str) -> None:
+        raise NotImplementedError
+
+
+class WebhookSink(AlertSink):
+    """POST `{"subject": ..., "body": ...}` as JSON to any URL."""
+
+    def __init__(self, url: str, headers: dict[str, str] | None = None) -> None:
+        self.url = url
+        self.headers = headers or {}
+
+    def send(self, subject: str, body: str) -> None:
+        resp = httpx.post(
+            self.url,
+            json={"subject": subject, "body": body},
+            headers=self.headers,
+            timeout=_HTTP_TIMEOUT,
+        )
+        resp.raise_for_status()
+
+
+class TelegramSink(AlertSink):
+    """Send via Telegram Bot API `sendMessage`."""
+
+    def __init__(self, bot_token: str, chat_id: str | int) -> None:
+        self.bot_token = bot_token
+        self.chat_id = chat_id
+
+    def send(self, subject: str, body: str) -> None:
+        text = f"{subject}\n{body}"[:4000]
+        resp = httpx.post(
+            f"{_TELEGRAM_API}/bot{self.bot_token}/sendMessage",
+            json={"chat_id": self.chat_id, "text": text},
+            timeout=_HTTP_TIMEOUT,
+        )
+        resp.raise_for_status()
+
+
+class SmtpSink(AlertSink):
+    """Send via SMTP (stdlib only)."""
+
+    def __init__(
+        self,
+        host: str,
+        to_addrs: list[str],
+        from_addr: str = "nahiarhdlog@localhost",
+        port: int = 587,
+        username: str | None = None,
+        password: str | None = None,
+        use_tls: bool = True,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.to_addrs = to_addrs
+        self.from_addr = from_addr
+        self.username = username
+        self.password = password
+        self.use_tls = use_tls
+
+    def send(self, subject: str, body: str) -> None:
+        msg = EmailMessage()
+        msg["Subject"] = subject
+        msg["From"] = self.from_addr
+        msg["To"] = ", ".join(self.to_addrs)
+        msg.set_content(body)
+        with smtplib.SMTP(self.host, self.port, timeout=_HTTP_TIMEOUT) as smtp:
+            if self.use_tls:
+                smtp.starttls()
+            if self.username:
+                smtp.login(self.username, self.password or "")
+            smtp.send_message(msg)
+
+
+@dataclass
+class _RuleState:
+    hits: deque[float] = field(default_factory=deque)
+    last_fired: float = 0.0
+
+
+class Alerter:
+    """Background evaluator: rules x sinks, never blocks the caller."""
+
+    def __init__(
+        self,
+        rules: list[Rule],
+        sinks: list[AlertSink],
+        queue_size: int = 1000,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        self.rules = list(rules)
+        self.sinks = list(sinks)
+        self._clock = clock or time.monotonic
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=queue_size)
+        self._states = {r.name: _RuleState() for r in self.rules}
+        self._stop = threading.Event()
+        self._started = False
+        self._thread = threading.Thread(
+            target=self._run, name="nahiarhdlog-alerter", daemon=True
+        )
+
+    def start(self) -> Alerter:
+        if self._started:
+            return self
+        self._started = True
+        self._thread.start()
+        return self
+
+    def notify(self, event: dict[str, Any]) -> None:
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            pass
+
+    def stop(self, timeout: float = 10.0) -> None:
+        if not self._started:
+            return
+        self._started = False
+        self._stop.set()
+        self._thread.join(timeout=timeout)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                event = self._queue.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            try:
+                self._process(event)
+            except Exception:
+                pass
+
+    def _process(self, event: dict[str, Any]) -> None:
+        now = self._clock()
+        for rule in self.rules:
+            if event.get("type") != rule.event_type:
+                continue
+            state = self._states[rule.name]
+            state.hits.append(now)
+            while state.hits and state.hits[0] <= now - rule.window_seconds:
+                state.hits.popleft()
+            if len(state.hits) < rule.count:
+                continue
+            if now - state.last_fired < rule.cooldown_seconds:
+                continue
+            state.last_fired = now
+            state.hits.clear()
+            self._fire(rule, event, now)
+
+    def _fire(self, rule: Rule, event: dict[str, Any], now: float) -> None:
+        data = event.get("data") or {}
+        sig = data.get("signature", "(unknown)")
+        subject = (
+            f"[nahiarhdlog] {rule.name}: "
+            f"{rule.count} errors in {rule.window_seconds:.0f}s"
+        )
+        body = f"Latest: {sig}\n{(event.get('message') or '')[:500]}"
+        for sink in self.sinks:
+            try:
+                sink.send(subject, body)
+            except Exception:
+                continue