brakit 0.1.0__tar.gz

brakit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.mcp.json
+*.egg-info/
+dist/
+build/

brakit-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: brakit
+Version: 0.1.0
+Summary: Zero-config observability for Python web frameworks
+License-Expression: MIT
+Keywords: debugging,fastapi,flask,observability,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn[standard]>=0.20; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/plain
+
+Zero-config observability for Python web frameworks.

brakit-0.1.0/brakit/__init__.py

@@ -0,0 +1,5 @@
+"""brakit — zero-config observability for Python web frameworks."""
+
+from brakit._setup import _auto_setup
+
+_auto_setup()

brakit-0.1.0/brakit/_setup.py

@@ -0,0 +1,162 @@
+"""Brakit SDK initialization. Wires stores, hooks, adapters, transport, and frameworks."""
+from __future__ import annotations
+
+import dataclasses
+import logging
+import threading
+import time
+
+from brakit.constants.events import (
+    CHANNEL_REQUEST_COMPLETED,
+    CHANNEL_TELEMETRY_ERROR,
+    CHANNEL_TELEMETRY_FETCH,
+    CHANNEL_TELEMETRY_LOG,
+    CHANNEL_TELEMETRY_QUERY,
+    EVENT_TYPE_ERROR,
+    EVENT_TYPE_FETCH,
+    EVENT_TYPE_LOG,
+    EVENT_TYPE_QUERY,
+    EVENT_TYPE_REQUEST,
+)
+from brakit.constants.logger import LOGGER_NAME
+from brakit.constants.transport import PORT_RETRY_COUNT, PORT_RETRY_INTERVAL_S
+from brakit.core.guards import should_activate
+from brakit.types.events import EventType, SDKEvent
+from brakit.types.http import TracedRequest
+from brakit.types.telemetry import TelemetryEntry
+
+logger = logging.getLogger(LOGGER_NAME)
+
+_init_lock = threading.Lock()
+_initialized = False
+
+
+def _auto_setup() -> None:
+    global _initialized
+    with _init_lock:
+        if _initialized:
+            return
+        _initialized = True
+
+    if not should_activate():
+        logger.debug("skipped (production/CI/cloud/disabled)")
+        return
+
+    registry = _create_registry()
+    _install_hooks(registry)
+    adapters = _install_adapters(registry)
+    logger.debug("adapters: %s", adapters)
+    _start_transport(registry)
+    _install_frameworks(registry)
+
+    logger.debug("initialized")
+
+
+def _create_registry() -> "ServiceRegistry":
+    from brakit.core.event_bus import EventBus
+    from brakit.core.registry import ServiceRegistry
+    from brakit.store.error_store import ErrorStore
+    from brakit.store.fetch_store import FetchStore
+    from brakit.store.log_store import LogStore
+    from brakit.store.query_store import QueryStore
+    from brakit.store.request_store import RequestStore
+
+    return ServiceRegistry(
+        bus=EventBus(),
+        request_store=RequestStore(),
+        query_store=QueryStore(),
+        fetch_store=FetchStore(),
+        log_store=LogStore(),
+        error_store=ErrorStore(),
+    )
+
+
+def _install_hooks(registry: "ServiceRegistry") -> None:
+    from brakit.hooks import patch_all
+
+    patch_all(registry.log_store, registry.fetch_store, registry.error_store, registry.bus)
+
+
+def _install_adapters(registry: "ServiceRegistry") -> list[str]:
+    from brakit.adapters import detect_and_patch as detect_db_adapters
+
+    return detect_db_adapters(registry.query_store, registry.bus)
+
+
+def _start_transport(registry: "ServiceRegistry") -> None:
+    from brakit.transport.discovery import discover_port
+    from brakit.transport.port_file import cleanup_stale_port_file, enable_port_writing
+
+    cleanup_stale_port_file()
+    port = discover_port()
+
+    if port is not None:
+        _setup_forwarder(registry, port)
+        return
+
+    # Port file not found — the Node.js server may not have received its first
+    # request yet (the port file is written on first request, not on startup).
+    # Retry discovery in a background thread so we don't block import.
+    def _retry() -> None:
+        for _ in range(PORT_RETRY_COUNT):
+            time.sleep(PORT_RETRY_INTERVAL_S)
+            found = discover_port()
+            if found is not None:
+                _setup_forwarder(registry, found)
+                return
+        logger.debug("no port found after retries, standalone mode")
+        enable_port_writing()
+
+    threading.Thread(
+        target=_retry, daemon=True, name="brakit-port-discovery",
+    ).start()
+
+
+def _setup_forwarder(registry: "ServiceRegistry", port: int) -> None:
+    from brakit.transport.forwarder import Forwarder
+
+    forwarder = Forwarder(port=port)
+    forwarder.start()
+
+    registry.bus.on(CHANNEL_REQUEST_COMPLETED, lambda r: _forward_request(forwarder, r))
+    registry.bus.on(CHANNEL_TELEMETRY_FETCH, lambda e: _forward_telemetry(forwarder, EVENT_TYPE_FETCH, e))
+    registry.bus.on(CHANNEL_TELEMETRY_LOG, lambda e: _forward_telemetry(forwarder, EVENT_TYPE_LOG, e))
+    registry.bus.on(CHANNEL_TELEMETRY_ERROR, lambda e: _forward_telemetry(forwarder, EVENT_TYPE_ERROR, e))
+    registry.bus.on(CHANNEL_TELEMETRY_QUERY, lambda e: _forward_telemetry(forwarder, EVENT_TYPE_QUERY, e))
+
+    logger.debug("transport ready on port %d", port)
+
+
+def _install_frameworks(registry: "ServiceRegistry") -> None:
+    from brakit.frameworks import detect_and_patch as detect_frameworks
+
+    detect_frameworks(registry)
+
+
+def _forward_request(forwarder: "Forwarder", request: TracedRequest) -> None:
+    raw = dataclasses.asdict(request)
+    data = {_to_camel(k): v for k, v in raw.items()}
+    event = SDKEvent(
+        type=EVENT_TYPE_REQUEST,
+        request_id=raw.get("id"),
+        timestamp=time.time() * 1_000,
+        data=data,
+    )
+    forwarder.send(event)
+
+
+def _to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def _forward_telemetry(forwarder: "Forwarder", event_type: EventType, entry: TelemetryEntry) -> None:
+    raw = dataclasses.asdict(entry)
+    data = {_to_camel(k): v for k, v in raw.items()}
+    event = SDKEvent(
+        type=event_type,
+        request_id=raw.get("parent_request_id"),
+        timestamp=time.time() * 1_000,
+        data=data,
+    )
+    forwarder.send(event)

brakit-0.1.0/brakit/adapters/__init__.py

@@ -0,0 +1,46 @@
+"""Detect and patch database adapters (SQLAlchemy, etc.)."""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from brakit.constants.logger import LOGGER_NAME
+
+if TYPE_CHECKING:
+    from brakit.adapters._protocol import DBAdapter
+    from brakit.core.event_bus import EventBus
+    from brakit.store import QueryStore
+
+logger = logging.getLogger(LOGGER_NAME)
+
+
+def detect_and_patch(
+    query_store: QueryStore,
+    bus: EventBus,
+) -> list[str]:
+    from brakit.adapters.asyncpg import AsyncpgAdapter
+    from brakit.adapters.sqlalchemy import SQLAlchemyAdapter
+
+    active: list[str] = []
+
+    # SQLAlchemy hooks into engine events and captures all queries including
+    # those routed through asyncpg.  If both are present, only use SQLAlchemy
+    # to avoid double-capturing.
+    sa = SQLAlchemyAdapter()
+    if sa.detect():
+        try:
+            sa.patch(query_store, bus)
+            active.append(sa.name)
+        except Exception:
+            logger.debug("failed to patch %s adapter", sa.name, exc_info=True)
+    else:
+        # No SQLAlchemy — try raw asyncpg.
+        apg = AsyncpgAdapter()
+        if apg.detect():
+            try:
+                apg.patch(query_store, bus)
+                active.append(apg.name)
+            except Exception:
+                logger.debug("failed to patch %s adapter", apg.name, exc_info=True)
+
+    return active

brakit-0.1.0/brakit/adapters/_normalize.py

@@ -0,0 +1,82 @@
+"""SQL normalization: operation detection, table extraction, noise filtering."""
+from __future__ import annotations
+
+import re
+
+from brakit.types.telemetry import NormalizedOp
+
+_OP_PATTERN = re.compile(
+    r"^\s*(SELECT|INSERT|UPDATE|DELETE)\b",
+    re.IGNORECASE,
+)
+
+_TABLE_PATTERN = re.compile(
+    r"(?:FROM|INTO|UPDATE|JOIN)\s+[\"'`]?(?:\w+\.)?[\"'`]?(\w+)",
+    re.IGNORECASE,
+)
+
+_VALID_OPS: dict[str, NormalizedOp] = {
+    "SELECT": "SELECT",
+    "INSERT": "INSERT",
+    "UPDATE": "UPDATE",
+    "DELETE": "DELETE",
+}
+
+# Transaction-management statements emitted by ORMs / drivers, not user queries.
+_TRANSACTION_PREFIXES: tuple[str, ...] = (
+    "BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "RELEASE SAVEPOINT",
+)
+
+# Substrings that identify asyncpg/psycopg driver-internal type introspection.
+_INTERNAL_QUERY_MARKERS: tuple[str, ...] = ("pg_catalog",)
+
+# Exact prefixes for driver probe/setup queries (e.g. asyncpg search_path probe).
+_INTERNAL_EXACT_PREFIXES: tuple[str, ...] = ("set ",)
+
+# Exact strings for driver probe queries (e.g. asyncpg "select public" search_path check).
+_INTERNAL_EXACT_QUERIES: tuple[str, ...] = ("select public",)
+
+
+def normalize_sql(sql: str) -> tuple[NormalizedOp, str]:
+    op: NormalizedOp = "OTHER"
+    table = ""
+
+    op_match = _OP_PATTERN.match(sql)
+    if op_match:
+        op = _VALID_OPS.get(op_match.group(1).upper(), "OTHER")
+
+    table_match = _TABLE_PATTERN.search(sql)
+    if table_match:
+        table = table_match.group(1)
+
+    return op, table
+
+
+def is_noise_query(sql: str) -> bool:
+    """Return True for transaction management, driver-internal, and setup queries.
+
+    Centralises noise filtering so all database adapters share a single
+    definition of what constitutes a non-application query.
+    """
+    stripped = sql.strip()
+    upper = stripped.rstrip(";").upper()
+
+    for prefix in _TRANSACTION_PREFIXES:
+        if upper == prefix or upper.startswith(prefix + " "):
+            return True
+
+    low = stripped.lower()
+
+    if low.startswith("select") and any(m in low for m in _INTERNAL_QUERY_MARKERS):
+        return True
+
+    for prefix in _INTERNAL_EXACT_PREFIXES:
+        if low.startswith(prefix):
+            return True
+
+    # Strip trailing semicolons before exact comparison.
+    bare = low.rstrip(";").rstrip()
+    if bare in _INTERNAL_EXACT_QUERIES:
+        return True
+
+    return False

brakit-0.1.0/brakit/adapters/_protocol.py

@@ -0,0 +1,16 @@
+"""Protocol definition for database adapters."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from brakit.core.event_bus import EventBus
+from brakit.store.query_store import QueryStore
+
+
+@runtime_checkable
+class DBAdapter(Protocol):
+    name: str
+
+    def detect(self) -> bool: ...
+    def patch(self, query_store: QueryStore, bus: EventBus) -> None: ...
+    def unpatch(self) -> None: ...

brakit-0.1.0/brakit/adapters/asyncpg.py

@@ -0,0 +1,131 @@
+"""asyncpg adapter: monkey-patches Pool methods to capture query telemetry."""
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from brakit.adapters._normalize import is_noise_query, normalize_sql
+from brakit.constants.events import CHANNEL_TELEMETRY_QUERY
+from brakit.constants.limits import MAX_SQL_LENGTH
+from brakit.constants.logger import LOGGER_NAME
+from brakit.core.context import get_fetch_id, get_request_id
+from brakit.core.event_bus import EventBus
+from brakit.store.query_store import QueryStore
+from brakit.types.telemetry import TracedQuery
+
+logger = logging.getLogger(LOGGER_NAME)
+
+# All asyncpg methods that accept a SQL string as their first positional
+# argument. Connection.prepare() is excluded because it does not execute
+# immediately.
+_POOL_METHODS = ("fetch", "fetchrow", "fetchval", "execute")
+_CONN_METHODS = ("fetch", "fetchrow", "fetchval", "execute")
+
+
+class AsyncpgAdapter:
+    name = "asyncpg"
+
+    _patched = False
+    _originals_pool: dict[str, Any] = {}
+    _originals_conn: dict[str, Any] = {}
+
+    def detect(self) -> bool:
+        try:
+            import asyncpg  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def patch(self, query_store: QueryStore, bus: EventBus) -> None:
+        if AsyncpgAdapter._patched:
+            return
+
+        try:
+            import asyncpg.pool
+            import asyncpg.connection
+        except ImportError:
+            return
+
+        pool_cls = asyncpg.pool.Pool
+        conn_cls = asyncpg.connection.Connection
+
+        for method_name in _POOL_METHODS:
+            original = getattr(pool_cls, method_name, None)
+            if original is None:
+                continue
+            AsyncpgAdapter._originals_pool[method_name] = original
+            wrapped = _make_wrapper(original, query_store, bus)
+            setattr(pool_cls, method_name, wrapped)
+
+        for method_name in _CONN_METHODS:
+            original = getattr(conn_cls, method_name, None)
+            if original is None:
+                continue
+            AsyncpgAdapter._originals_conn[method_name] = original
+            wrapped = _make_wrapper(original, query_store, bus)
+            setattr(conn_cls, method_name, wrapped)
+
+        AsyncpgAdapter._patched = True
+
+    def unpatch(self) -> None:
+        if not AsyncpgAdapter._patched:
+            return
+
+        try:
+            import asyncpg.pool
+            import asyncpg.connection
+
+            for method_name, original in AsyncpgAdapter._originals_pool.items():
+                setattr(asyncpg.pool.Pool, method_name, original)
+            for method_name, original in AsyncpgAdapter._originals_conn.items():
+                setattr(asyncpg.connection.Connection, method_name, original)
+            AsyncpgAdapter._originals_pool.clear()
+            AsyncpgAdapter._originals_conn.clear()
+        except Exception:
+            logger.debug("asyncpg unpatch failed", exc_info=True)
+
+        AsyncpgAdapter._patched = False
+
+
+def _make_wrapper(
+    original: Callable[..., Coroutine[Any, Any, Any]],
+    query_store: QueryStore,
+    bus: EventBus,
+) -> Callable[..., Coroutine[Any, Any, Any]]:
+    async def wrapper(self: Any, query: str, *args: Any, **kwargs: Any) -> Any:
+        # Skip telemetry for queries outside a request context (connection setup)
+        # or known asyncpg internal queries.
+        request_id = get_request_id()
+        should_capture = request_id is not None and not is_noise_query(query)
+
+        if not should_capture:
+            return await original(self, query, *args, **kwargs)
+
+        start = time.perf_counter()
+        try:
+            result = await original(self, query, *args, **kwargs)
+            return result
+        finally:
+            duration_ms = (time.perf_counter() - start) * 1_000
+            try:
+                operation, table = normalize_sql(query)
+                entry = TracedQuery(
+                    id=uuid.uuid4().hex,
+                    parent_request_id=request_id,
+                    timestamp=time.time() * 1_000,
+                    driver="asyncpg",
+                    sql=query[:MAX_SQL_LENGTH] if query else None,
+                    operation=operation,
+                    table=table,
+                    duration_ms=round(duration_ms, 2),
+                    parent_fetch_id=get_fetch_id(),
+                )
+                query_store.add(entry)
+                bus.emit(CHANNEL_TELEMETRY_QUERY, entry)
+            except Exception:
+                logger.debug("asyncpg telemetry capture failed", exc_info=True)
+
+    return wrapper

brakit-0.1.0/brakit/adapters/sqlalchemy.py

@@ -0,0 +1,121 @@
+"""SQLAlchemy adapter: hooks into engine events to capture queries."""
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import Any
+
+from brakit.adapters._normalize import is_noise_query, normalize_sql
+from brakit.constants.events import CHANNEL_TELEMETRY_QUERY
+from brakit.constants.limits import MAX_SQL_LENGTH
+from brakit.constants.logger import LOGGER_NAME
+from brakit.core.context import get_fetch_id, get_request_id
+from brakit.core.event_bus import EventBus
+from brakit.store.query_store import QueryStore
+from brakit.types.telemetry import TracedQuery
+
+logger = logging.getLogger(LOGGER_NAME)
+
+_SA_INFO_START_TIME = "_brakit_start"
+_SA_INFO_SQL = "_brakit_sql"
+
+
+class SQLAlchemyAdapter:
+    name = "sqlalchemy"
+
+    _patched = False
+    _on_before_listener: Any = None
+    _on_after_listener: Any = None
+
+    def detect(self) -> bool:
+        try:
+            import sqlalchemy  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def patch(self, query_store: QueryStore, bus: EventBus) -> None:
+        if SQLAlchemyAdapter._patched:
+            return
+
+        try:
+            from sqlalchemy import event
+            from sqlalchemy.engine import Engine
+        except ImportError:
+            return
+
+        @event.listens_for(Engine, "before_cursor_execute")
+        def _on_before_execute(
+            conn: Any,
+            cursor: Any,
+            statement: str,
+            parameters: Any,
+            context: Any,
+            executemany: bool,
+        ) -> None:
+            conn.info[_SA_INFO_START_TIME] = time.perf_counter()
+            conn.info[_SA_INFO_SQL] = statement
+
+        @event.listens_for(Engine, "after_cursor_execute")
+        def _on_after_execute(
+            conn: Any,
+            cursor: Any,
+            statement: str,
+            parameters: Any,
+            context: Any,
+            executemany: bool,
+        ) -> None:
+            start: float | None = conn.info.pop(_SA_INFO_START_TIME, None)
+            sql: str = conn.info.pop(_SA_INFO_SQL, "")
+
+            if start is None:
+                return
+
+            request_id = get_request_id()
+            if request_id is None:
+                return
+
+            if is_noise_query(sql):
+                return
+
+            duration_ms = (time.perf_counter() - start) * 1_000
+            operation, table = normalize_sql(sql)
+
+            entry = TracedQuery(
+                id=uuid.uuid4().hex,
+                parent_request_id=request_id,
+                timestamp=time.time() * 1_000,
+                driver="sqlalchemy",
+                sql=sql[:MAX_SQL_LENGTH] if sql else None,
+                operation=operation,
+                table=table,
+                duration_ms=round(duration_ms, 2),
+                parent_fetch_id=get_fetch_id(),
+            )
+
+            query_store.add(entry)
+            bus.emit(CHANNEL_TELEMETRY_QUERY, entry)
+
+        SQLAlchemyAdapter._on_before_listener = _on_before_execute
+        SQLAlchemyAdapter._on_after_listener = _on_after_execute
+        SQLAlchemyAdapter._patched = True
+
+    def unpatch(self) -> None:
+        if not SQLAlchemyAdapter._patched:
+            return
+
+        try:
+            from sqlalchemy import event
+            from sqlalchemy.engine import Engine
+
+            if SQLAlchemyAdapter._on_before_listener is not None:
+                event.remove(Engine, "before_cursor_execute", SQLAlchemyAdapter._on_before_listener)
+            if SQLAlchemyAdapter._on_after_listener is not None:
+                event.remove(Engine, "after_cursor_execute", SQLAlchemyAdapter._on_after_listener)
+            SQLAlchemyAdapter._on_before_listener = None
+            SQLAlchemyAdapter._on_after_listener = None
+        except Exception:
+            logger.debug("sqlalchemy unpatch failed", exc_info=True)
+
+        SQLAlchemyAdapter._patched = False