bufferlog 0.1.0__py3-none-any.whl

bufferlog/control_plane/telemetry_reporter.py

@@ -0,0 +1,118 @@
+"""
+BufferLog — Telemetry Reporter
+
+Background thread that pushes SDK metrics to the control plane.
+Sends counters only — never log data.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+import platform
+
+
+class TelemetryReporter:
+    """Periodically sends metric snapshots to the BufferLog Control Plane."""
+
+    def __init__(
+        self,
+        url: str,
+        api_key: str,
+        interval_s: float = 60.0,
+        metrics_provider: Optional[Callable[[], Dict[str, Any]]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        base = url.rstrip("/")
+        self._url = f"{base}/api/v1/telemetry"
+        self._api_key = api_key
+        self._interval = interval_s
+        self._metrics_provider = metrics_provider
+        self._on_error = on_error
+
+        self._timer: Optional[threading.Timer] = None
+        self._running = False
+        self._send_count = 0
+        self._error_count = 0
+        self._lock = threading.Lock()
+
+    def start(self) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._schedule()
+
+    def stop(self) -> None:
+        self._running = False
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+
+    def send(self) -> bool:
+        """Send a single telemetry snapshot."""
+        return self._do_send()
+
+    def _schedule(self) -> None:
+        if not self._running:
+            return
+        self._timer = threading.Timer(self._interval, self._tick)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _tick(self) -> None:
+        self._do_send()
+        self._schedule()
+
+    def _do_send(self) -> bool:
+        if not self._metrics_provider:
+            return False
+
+        try:
+            metrics = self._metrics_provider()
+            payload = {
+                "sdkVersion": "0.1.0",
+                "runtime": "python",
+                "runtimeVersion": platform.python_version(),
+                "metrics": metrics,
+            }
+
+            data = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(
+                self._url,
+                data=data,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self._api_key}",
+                    "User-Agent": f"bufferlog-sdk-python/0.1.0 (python/{platform.python_version()})",
+                },
+                method="POST",
+            )
+
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+
+            with self._lock:
+                self._send_count += 1
+            return True
+        except Exception as e:
+            with self._lock:
+                self._error_count += 1
+            if self._on_error:
+                self._on_error(e)
+            return False
+
+    @property
+    def send_count(self) -> int:
+        with self._lock:
+            return self._send_count
+
+    @property
+    def error_count(self) -> int:
+        with self._lock:
+            return self._error_count
+
+    @property
+    def is_running(self) -> bool:
+        return self._running

bufferlog/flash_controller.py

@@ -0,0 +1,78 @@
+"""
+BufferLog — Flash Controller
+
+Triggers a non-blocking flush of the ring buffer when an error is detected.
+Dispatches log events to all configured adapters in a background thread
+to avoid blocking the request.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import List, Any
+
+from .ring_buffer import RingBuffer
+from .log_event import LogEvent
+
+
+class FlashController:
+    """Dispatches buffered log events to adapters on error."""
+
+    def __init__(self, adapters: List[Any], fail_open: bool = True) -> None:
+        self._adapters = adapters
+        self._fail_open = fail_open
+        self._flush_count = 0
+        self._events_flushed = 0
+        self._adapter_errors = 0
+        self._lock = threading.Lock()
+
+    def trigger(
+        self,
+        context_id: str,
+        buffer: RingBuffer[LogEvent],
+        error_event: LogEvent,
+    ) -> None:
+        """Flush the buffer contents + error event to all adapters."""
+        events = buffer.drain()
+        events.append(error_event)
+
+        with self._lock:
+            self._flush_count += 1
+            self._events_flushed += len(events)
+
+        # Dispatch in background thread to avoid blocking
+        t = threading.Thread(
+            target=self._dispatch,
+            args=(events, context_id),
+            daemon=True,
+        )
+        t.start()
+
+    def _dispatch(self, events: List[LogEvent], context_id: str) -> None:
+        for adapter in self._adapters:
+            try:
+                adapter.send(events, context_id)
+            except Exception as e:
+                with self._lock:
+                    self._adapter_errors += 1
+                if self._fail_open:
+                    print(
+                        f"[BufferLog] Adapter error: {e}",
+                        file=sys.stderr,
+                    )
+
+    @property
+    def flush_count(self) -> int:
+        with self._lock:
+            return self._flush_count
+
+    @property
+    def events_flushed(self) -> int:
+        with self._lock:
+            return self._events_flushed
+
+    @property
+    def adapter_errors(self) -> int:
+        with self._lock:
+            return self._adapter_errors

bufferlog/integrations/__init__.py

@@ -0,0 +1,82 @@
+"""
+BufferLog — Python logging.Handler integration
+
+Drop-in handler for Python's built-in logging module.
+Routes log records into the per-request ring buffer.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from ..log_event import LogEvent, LogLevel
+from ..flash_controller import FlashController
+from ..config import BufferLogConfig
+from .. import context as ctx
+
+
+# Map Python logging levels to BufferLog levels
+_LEVEL_MAP = {
+    logging.DEBUG: LogLevel.DEBUG,
+    logging.INFO: LogLevel.INFO,
+    logging.WARNING: LogLevel.WARNING,
+    logging.ERROR: LogLevel.ERROR,
+    logging.CRITICAL: LogLevel.CRITICAL,
+}
+
+
+class BufferLogHandler(logging.Handler):
+    """A logging.Handler that routes records into the BufferLog ring buffer.
+
+    Usage:
+        handler = BufferLogHandler(flash_controller=fc, config=config)
+        logger = logging.getLogger("myapp")
+        logger.addHandler(handler)
+    """
+
+    def __init__(
+        self,
+        flash_controller: FlashController,
+        config: BufferLogConfig,
+        level: int = logging.DEBUG,
+    ) -> None:
+        super().__init__(level)
+        self._flash = flash_controller
+        self._config = config
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            context_id = ctx.get_context_id()
+            buffer = ctx.get_buffer()
+
+            if context_id is None or buffer is None:
+                # Outside of a request context — pass through
+                return
+
+            bl_level = _LEVEL_MAP.get(record.levelno, LogLevel.INFO)
+            message = self.format(record) if self.formatter else record.getMessage()
+
+            metadata: Dict[str, Any] = {
+                "logger": record.name,
+                "pathname": record.pathname,
+                "lineno": record.lineno,
+            }
+
+            event = LogEvent(
+                level=bl_level,
+                message=message,
+                context_id=context_id,
+                metadata=metadata,
+            )
+
+            buffer.write(event)
+
+            # Check if this level triggers a flush
+            level_name = record.levelname.upper()
+            if level_name in self._config.flush_levels_set:
+                self._flash.trigger(context_id, buffer, event)
+
+        except Exception:
+            if self._config.fail_open:
+                self.handleError(record)

bufferlog/log_event.py

@@ -0,0 +1,50 @@
+"""
+BufferLog — Log Event
+
+Dataclass representing a single log event captured by the SDK.
+"""
+
+from __future__ import annotations
+
+import time
+import enum
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+class LogLevel(enum.IntEnum):
+    """Standard log levels, ordered by severity."""
+    DEBUG = 10
+    INFO = 20
+    WARNING = 30
+    ERROR = 40
+    CRITICAL = 50
+
+
+LOG_LEVEL_NAMES: Dict[int, str] = {
+    LogLevel.DEBUG: "DEBUG",
+    LogLevel.INFO: "INFO",
+    LogLevel.WARNING: "WARNING",
+    LogLevel.ERROR: "ERROR",
+    LogLevel.CRITICAL: "CRITICAL",
+}
+
+
+@dataclass(frozen=True)
+class LogEvent:
+    """An immutable log event stored in the ring buffer."""
+    level: LogLevel
+    message: str
+    context_id: str
+    timestamp: float = field(default_factory=time.time)
+    metadata: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize for adapter dispatch."""
+        return {
+            "level": LOG_LEVEL_NAMES.get(self.level, str(self.level)),
+            "message": self.message,
+            "context_id": self.context_id,
+            "timestamp": self.timestamp,
+            "metadata": self.metadata or {},
+        }

bufferlog/middleware/__init__.py

@@ -0,0 +1 @@
+"""BufferLog middleware package."""

bufferlog/middleware/django_mw.py

@@ -0,0 +1,85 @@
+"""
+BufferLog — Django Middleware
+
+Django-style middleware class that wraps each request in a BufferLog context.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Callable, Optional
+
+from ..buffer_manager import BufferManager
+from ..flash_controller import FlashController
+from ..log_event import LogEvent, LogLevel
+from ..config import BufferLogConfig
+from .. import context as ctx
+
+
+class BufferLogDjangoMiddleware:
+    """Django middleware for BufferLog.
+
+    Add to MIDDLEWARE in settings.py. Requires BufferLog.init_django() to be called
+    first to inject the BufferLog instance.
+    """
+
+    # Class-level references set by BufferLog.init_django()
+    _buffer_manager: Optional[BufferManager] = None
+    _flash_controller: Optional[FlashController] = None
+    _config: Optional[BufferLogConfig] = None
+
+    def __init__(self, get_response: Callable) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: Any) -> Any:
+        bm = self._buffer_manager
+        fc = self._flash_controller
+        config = self._config
+
+        if bm is None or fc is None or config is None or not config.enabled:
+            return self.get_response(request)
+
+        context_id = uuid.uuid4().hex
+        buffer = bm.create_buffer(context_id, config.buffer_capacity)
+        ctx.set_context(context_id, buffer)
+
+        try:
+            response = self.get_response(request)
+        except Exception as exc:
+            buf = ctx.get_buffer()
+            if buf is not None:
+                error_event = LogEvent(
+                    level=LogLevel.ERROR,
+                    message=f"Unhandled exception: {exc}",
+                    context_id=context_id,
+                    metadata={"exception": str(exc)},
+                )
+                fc.trigger(context_id, buf, error_event)
+            bm.discard_buffer(context_id)
+            ctx.clear_context()
+            raise
+        else:
+            status = getattr(response, "status_code", 200)
+            if status in config.flush_status_set:
+                buf = ctx.get_buffer()
+                if buf is not None:
+                    method = getattr(request, "method", "")
+                    path = getattr(request, "path", "")
+                    error_event = LogEvent(
+                        level=LogLevel.ERROR,
+                        message=f"HTTP {status} {method} {path}",
+                        context_id=context_id,
+                        metadata={
+                            "http_method": method,
+                            "http_path": path,
+                            "http_status": status,
+                        },
+                    )
+                    fc.trigger(context_id, buf, error_event)
+                bm.discard_buffer(context_id)
+            else:
+                bm.discard_buffer(context_id)
+        finally:
+            ctx.clear_context()
+
+        return response

bufferlog/middleware/fastapi_mw.py

@@ -0,0 +1,92 @@
+"""
+BufferLog — FastAPI / Starlette ASGI Middleware
+
+ASGI middleware that wraps each request in a BufferLog context.
+Works with both FastAPI and raw Starlette.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Callable, TYPE_CHECKING
+
+from ..buffer_manager import BufferManager
+from ..flash_controller import FlashController
+from ..log_event import LogEvent, LogLevel
+from ..config import BufferLogConfig
+from .. import context as ctx
+
+if TYPE_CHECKING:
+    pass
+
+
+class BufferLogMiddleware:
+    """ASGI middleware for FastAPI / Starlette."""
+
+    def __init__(
+        self,
+        app: Any,
+        buffer_manager: BufferManager,
+        flash_controller: FlashController,
+        config: BufferLogConfig,
+    ) -> None:
+        self.app = app
+        self._bm = buffer_manager
+        self._fc = flash_controller
+        self._config = config
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        if scope["type"] != "http" or not self._config.enabled:
+            await self.app(scope, receive, send)
+            return
+
+        context_id = uuid.uuid4().hex
+        buffer = self._bm.create_buffer(context_id, self._config.buffer_capacity)
+        ctx.set_context(context_id, buffer)
+
+        status_code = 200
+
+        async def send_wrapper(message: dict) -> None:
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = message.get("status", 200)
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        except Exception as exc:
+            # Unhandled exception — flush
+            buf = ctx.get_buffer()
+            if buf is not None:
+                error_event = LogEvent(
+                    level=LogLevel.ERROR,
+                    message=f"Unhandled exception: {exc}",
+                    context_id=context_id,
+                    metadata={"exception": str(exc)},
+                )
+                self._fc.trigger(context_id, buf, error_event)
+            self._bm.discard_buffer(context_id)
+            ctx.clear_context()
+            raise
+        else:
+            if status_code in self._config.flush_status_set:
+                buf = ctx.get_buffer()
+                if buf is not None:
+                    method = scope.get("method", "")
+                    path = scope.get("path", "")
+                    error_event = LogEvent(
+                        level=LogLevel.ERROR,
+                        message=f"HTTP {status_code} {method} {path}",
+                        context_id=context_id,
+                        metadata={
+                            "http_method": method,
+                            "http_path": path,
+                            "http_status": status_code,
+                        },
+                    )
+                    self._fc.trigger(context_id, buf, error_event)
+                self._bm.discard_buffer(context_id)
+            else:
+                self._bm.discard_buffer(context_id)
+        finally:
+            ctx.clear_context()

bufferlog/middleware/flask_mw.py

@@ -0,0 +1,71 @@
+"""
+BufferLog — Flask Middleware
+
+Uses Flask's before_request / after_request hooks to wrap each request
+in a BufferLog context. Buffers are discarded on success and flushed on error.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING
+
+from ..buffer_manager import BufferManager
+from ..flash_controller import FlashController
+from ..log_event import LogEvent, LogLevel
+from ..config import BufferLogConfig
+from .. import context as ctx
+
+if TYPE_CHECKING:
+    from flask import Flask
+
+
+def init_flask(
+    app: "Flask",
+    buffer_manager: BufferManager,
+    flash_controller: FlashController,
+    config: BufferLogConfig,
+) -> None:
+    """Register BufferLog hooks on a Flask app."""
+
+    @app.before_request
+    def _bufferlog_before() -> None:
+        if not config.enabled:
+            return
+        context_id = uuid.uuid4().hex
+        buffer = buffer_manager.create_buffer(context_id, config.buffer_capacity)
+        ctx.set_context(context_id, buffer)
+
+    @app.after_request
+    def _bufferlog_after(response):  # type: ignore[no-untyped-def]
+        context_id = ctx.get_context_id()
+        if context_id is None:
+            return response
+
+        if response.status_code in config.flush_status_set:
+            buffer = ctx.get_buffer()
+            if buffer is not None:
+                from flask import request
+
+                error_event = LogEvent(
+                    level=LogLevel.ERROR,
+                    message=f"HTTP {response.status_code} {request.method} {request.path}",
+                    context_id=context_id,
+                    metadata={
+                        "http_method": request.method,
+                        "http_path": request.path,
+                        "http_status": response.status_code,
+                    },
+                )
+                flash_controller.trigger(context_id, buffer, error_event)
+            buffer_manager.discard_buffer(context_id)
+        else:
+            buffer_manager.discard_buffer(context_id)
+
+        ctx.clear_context()
+        return response
+
+    @app.teardown_request
+    def _bufferlog_teardown(exc=None):  # type: ignore[no-untyped-def]
+        # Safety net: ensure context is always cleared
+        ctx.clear_context()

bufferlog/ring_buffer.py

@@ -0,0 +1,94 @@
+"""
+BufferLog — Ring Buffer
+
+Fixed-size circular buffer that overwrites the oldest entry when full.
+Used to store log events in memory per-request without growing unbounded.
+
+Design notes:
+- Uses a pre-allocated list for O(1) writes with zero allocation after init
+- Thread-safe via threading.Lock (needed for async frameworks)
+- Generic over T for reuse
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Generic, TypeVar, List, Optional
+
+T = TypeVar("T")
+
+
+class RingBuffer(Generic[T]):
+    """Fixed-size circular buffer.
+
+    When the buffer is full, new items overwrite the oldest entries.
+    This prevents unbounded memory growth while retaining the most
+    recent N log events for error context.
+    """
+
+    __slots__ = ("_capacity", "_buf", "_head", "_count", "_lock")
+
+    def __init__(self, capacity: int = 100) -> None:
+        if capacity < 1:
+            raise ValueError("capacity must be >= 1")
+        self._capacity = capacity
+        self._buf: List[Optional[T]] = [None] * capacity
+        self._head = 0  # Next write position
+        self._count = 0
+        self._lock = threading.Lock()
+
+    @property
+    def capacity(self) -> int:
+        return self._capacity
+
+    @property
+    def count(self) -> int:
+        with self._lock:
+            return self._count
+
+    @property
+    def is_full(self) -> bool:
+        with self._lock:
+            return self._count >= self._capacity
+
+    def write(self, item: T) -> None:
+        """Write an item. Overwrites the oldest if full."""
+        with self._lock:
+            self._buf[self._head] = item
+            self._head = (self._head + 1) % self._capacity
+            if self._count < self._capacity:
+                self._count += 1
+
+    def drain(self) -> List[T]:
+        """Remove and return all items in chronological order."""
+        with self._lock:
+            if self._count == 0:
+                return []
+
+            result: List[T] = []
+            if self._count < self._capacity:
+                # Buffer not yet wrapped
+                for i in range(self._count):
+                    item = self._buf[i]
+                    if item is not None:
+                        result.append(item)
+            else:
+                # Buffer has wrapped — read from head (oldest) forward
+                for i in range(self._capacity):
+                    idx = (self._head + i) % self._capacity
+                    item = self._buf[idx]
+                    if item is not None:
+                        result.append(item)
+
+            self._clear_unlocked()
+            return result
+
+    def clear(self) -> None:
+        """Clear all items."""
+        with self._lock:
+            self._clear_unlocked()
+
+    def _clear_unlocked(self) -> None:
+        self._buf = [None] * self._capacity
+        self._head = 0
+        self._count = 0