insider-python 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

insider/__init__.py

@@ -6,6 +6,7 @@ Public API:
     insider.init(dsn=..., environment=..., release=..., ...)
     insider.capture_exception(exc, level="error", tags=..., extra=...)
     insider.capture_message("text", level="info", tags=..., extra=...)
+    insider.capture_perf("GET /api/users/", duration_ms=45, status_code=200)
     insider.flush(timeout=2.0)
     insider.close(timeout=2.0)
 
@@ -17,12 +18,15 @@ from ._version import __version__
 from .client import (
     Client,
     capture_exception,
+    capture_log,
     capture_message,
+    capture_perf,
     close,
     flush,
     init,
 )
 from .dsn import DSN, InvalidDSNError
+from .integrations.logging import LoggingIntegration
 
 __all__ = [
     "Client",
@@ -30,8 +34,11 @@ __all__ = [
     "InvalidDSNError",
     "__version__",
     "capture_exception",
+    "capture_log",
     "capture_message",
+    "capture_perf",
     "close",
     "flush",
     "init",
+    "LoggingIntegration",
 ]

insider/_envelope.py

@@ -1,5 +1,5 @@
 """
-Beacon envelope construction + size-budget enforcement.
+Footprint envelope construction + size-budget enforcement.
 
 `build_envelope` is called from the capture functions in `client.py`. It
 takes the raw bits (kind, level, message, exception payload, scope,
@@ -58,7 +58,7 @@ def build_envelope(
     occurred_at: Optional[str] = None,
     commit_hash: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Assemble the Beacon envelope. Pure: no I/O, no globals."""
+    """Assemble the Footprint envelope. Pure: no I/O, no globals."""
     body: Dict[str, Any] = dict(payload or {})
     if tags:
         body["tags"] = tags

insider/_footprint.py

@@ -0,0 +1,64 @@
+"""Build flat footprint payloads for beam ingest."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._version import __version__
+from .stacktrace import runtime_payload
+
+
+def build_footprint_payload(
+    *,
+    request_id: Optional[str],
+    request_path: str,
+    request_method: Optional[str],
+    request_user: str = "anonymous",
+    request_body: Any = None,
+    response_body: Any = None,
+    response_time: float,
+    status_code: int,
+    system_logs: Optional[list] = None,
+    ip_address: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    db_query_count: int = 0,
+    exception_block: Optional[Dict[str, Any]] = None,
+    environment: str = "production",
+    release: Optional[str] = None,
+    service_name: Optional[str] = None,
+    commit_hash: Optional[str] = None,
+) -> Dict[str, Any]:
+    runtime = runtime_payload(__version__)
+    stack_trace = None
+    exception_name = None
+    if exception_block:
+        exception_name = exception_block.get("type")
+        stack_trace = dict(exception_block)
+        if commit_hash:
+            stack_trace["commit_hash"] = commit_hash
+
+    body = request_body
+    if body is not None and not isinstance(body, (dict, list, str, int, float, bool)):
+        body = str(body)
+
+    return {
+        "request_id": request_id,
+        "request_user": request_user,
+        "request_path": request_path,
+        "request_body": body if body is not None else None,
+        "request_method": (request_method or "").lower() or None,
+        "response_body": response_body,
+        "response_time": float(response_time),
+        "status_code": status_code,
+        "system_logs": system_logs,
+        "ip_address": ip_address,
+        "user_agent": user_agent,
+        "db_query_count": db_query_count,
+        "exception_name": exception_name,
+        "stack_trace": stack_trace,
+        "service_name": service_name,
+        "environment": environment,
+        "language": runtime.get("language"),
+        "framework": runtime.get("framework"),
+        "release": release,
+    }

insider/_version.py

@@ -5,4 +5,4 @@ lookup on every beacon. Bump this and `[project].version` together when
 cutting a release.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

insider/client.py

@@ -18,9 +18,12 @@ import atexit
 import os
 import subprocess
 import threading
-from typing import Any, Callable, Dict, Iterable, List, Optional
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Union
 
-from ._envelope import build_envelope, enforce_size_budget
+import json
+
+from ._envelope import MAX_ENVELOPE_BYTES, build_envelope, enforce_size_budget
+from ._footprint import build_footprint_payload
 from ._version import __version__
 from .dsn import DSN, InvalidDSNError
 from .safety import debug, safe, set_debug
@@ -30,10 +33,27 @@ from .stacktrace import caller_source, exception_payload, runtime_payload
 from .transport import BackgroundTransport
 
 
-VALID_KINDS = {"error", "perf", "log", "custom"}
+VALID_KINDS = {"error", "perf", "log", "custom", "request"}
 VALID_LEVELS = {"debug", "info", "warning", "error", "fatal"}
 
 
+def _byte_len_footprint(obj: Dict[str, Any]) -> int:
+    try:
+        return len(json.dumps(obj, default=str, ensure_ascii=False).encode("utf-8"))
+    except Exception:
+        return 10**9
+
+IntegrationLike = Union[Any, type]
+
+
+def _setup_integrations(integrations: Sequence[IntegrationLike]) -> None:
+    for integration in integrations:
+        instance = integration() if isinstance(integration, type) else integration
+        setup_once = getattr(instance, "setup_once", None)
+        if callable(setup_once):
+            setup_once()
+
+
 # ---------------------------------------------------------------------------
 # DSN resolution
 # ---------------------------------------------------------------------------
@@ -78,9 +98,11 @@ class Client:
         transport_flush_timeout: float = 2.0,
         debug: bool = False,
         transport: Optional[BackgroundTransport] = None,
+        enable_logs: bool = False,
     ) -> None:
         set_debug(debug)
         self.dsn = dsn
+        self.enable_logs = bool(enable_logs)
         self.send_default_pii = bool(send_default_pii)
         self.before_send = before_send
         self.scrub_keys: List[str] = list(scrub_keys or [])
@@ -135,6 +157,10 @@ class Client:
         exception_block = exception_payload(
             exc, in_app_include=self.scope.static.in_app_include
         )
+        if self.scope.current_request() is not None:
+            self.scope.set_pending_exception(exception_block)
+            return self.scope.current_trace_id()
+
         payload: Dict[str, Any] = {
             "exception": exception_block,
             "runtime": runtime_payload(__version__),
@@ -142,6 +168,9 @@ class Client:
         request_ctx = self.scope.current_request()
         if request_ctx is not None:
             payload["request"] = request_ctx
+        breadcrumbs = self.scope.current_breadcrumbs()
+        if breadcrumbs:
+            payload["breadcrumbs"] = breadcrumbs
 
         envelope = build_envelope(
             kind="error",
@@ -150,7 +179,7 @@ class Client:
             source=self._source_from_exception(exception_block),
             environment=self.scope.static.environment,
             release=self.scope.static.release,
-            trace_id=trace_id,
+            trace_id=trace_id or self.scope.current_trace_id(),
             commit_hash=self.commit_hash,
             payload=payload,
             tags=tags,
@@ -173,6 +202,19 @@ class Client:
             debug(f"capture_message expects str, got {type(message).__name__}")
             return None
         level = level if level in VALID_LEVELS else "info"
+
+        if self.scope.current_request() is not None:
+            from datetime import datetime, timezone
+
+            self.scope.add_request_log(
+                level=level,
+                message=message,
+                source=source or caller_source(skip=2),
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+            return self.scope.current_trace_id()
+
+        level = level if level in VALID_LEVELS else "info"
         kind = kind if kind in VALID_KINDS else "log"
 
         payload: Dict[str, Any] = {"runtime": runtime_payload(__version__)}
@@ -195,6 +237,146 @@ class Client:
         )
         return self._dispatch(envelope)
 
+    def capture_log(
+        self,
+        message: str,
+        *,
+        level: str = "info",
+        tags: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        trace_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """Record a structured log line (`kind=log`). Alias ergonomics over `capture_message`."""
+        return self.capture_message(
+            message,
+            level=level,
+            tags=tags,
+            extra=extra,
+            source=source,
+            trace_id=trace_id,
+            kind="log",
+        )
+
+    def capture_request(
+        self,
+        *,
+        duration_ms: float,
+        op: str,
+        status_code: Optional[int] = None,
+        method: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        tags: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        """Emit one HTTP request footprint to the beam endpoint."""
+        if not isinstance(duration_ms, (int, float)) or duration_ms < 0:
+            debug(f"capture_request expects duration_ms >= 0, got {duration_ms!r}")
+            return None
+        if not isinstance(op, str) or not op.strip():
+            debug("capture_request expects non-empty op str")
+            return None
+        code = status_code if status_code is not None else 200
+        if not isinstance(code, int) or not (100 <= code <= 599):
+            debug(f"capture_request invalid status_code: {status_code!r}")
+            return None
+
+        exception_block = self.scope.current_pending_exception()
+        request_ctx = self.scope.current_request() or {}
+        logs = self.scope.current_request_logs()
+        headers = request_ctx.get("headers") if isinstance(request_ctx.get("headers"), dict) else {}
+
+        footprint = build_footprint_payload(
+            request_id=trace_id or self.scope.current_trace_id(),
+            request_path=op.strip(),
+            request_method=method,
+            request_user=str(request_ctx.get("user") or "anonymous"),
+            request_body=request_ctx.get("body"),
+            response_time=float(duration_ms),
+            status_code=code,
+            system_logs=logs or None,
+            ip_address=request_ctx.get("ip") or request_ctx.get("ip_address") or headers.get("x-forwarded-for"),
+            user_agent=request_ctx.get("user_agent") or headers.get("user-agent"),
+            exception_block=exception_block,
+            environment=self.scope.static.environment,
+            release=self.scope.static.release,
+            commit_hash=self.commit_hash,
+        )
+        if tags:
+            footprint["_tags"] = tags
+        if extra:
+            footprint["_extra"] = extra
+        return self._dispatch_footprint(footprint)
+
+    def capture_perf(
+        self,
+        op: str,
+        duration_ms: float,
+        *,
+        status_code: Optional[int] = None,
+        method: Optional[str] = None,
+        level: str = "info",
+        tags: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        source: str = "django.request",
+        trace_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Record a performance timing beacon (`kind=perf`).
+
+        Used for HTTP request durations, slow queries, and other timing
+        signals. Does not create Issues on the server — perf rows live in
+        Beacons only. Pair with `trace_id` to link a perf row to an error
+        on the same request (see DjangoIntegration).
+        """
+        if not isinstance(op, str) or not op.strip():
+            debug("capture_perf expects non-empty op str")
+            return None
+        if not isinstance(duration_ms, (int, float)) or duration_ms < 0:
+            debug(f"capture_perf expects duration_ms >= 0, got {duration_ms!r}")
+            return None
+        if status_code is not None:
+            if not isinstance(status_code, int) or not (100 <= status_code <= 599):
+                debug(f"capture_perf invalid status_code: {status_code!r}")
+                return None
+        level = level if level in VALID_LEVELS else "info"
+
+        payload: Dict[str, Any] = {
+            "runtime": runtime_payload(__version__),
+            "duration_ms": float(duration_ms),
+            "op": op.strip(),
+        }
+        if status_code is not None:
+            payload["status_code"] = status_code
+        if method is not None:
+            payload["method"] = method
+
+        request_ctx = self.scope.current_request()
+        if request_ctx is not None:
+            payload["request"] = request_ctx
+
+        message = self._perf_summary_message(
+            method=method,
+            op=op.strip(),
+            status_code=status_code,
+            duration_ms=float(duration_ms),
+        )
+
+        envelope = build_envelope(
+            kind="perf",
+            level=level,
+            message=message,
+            source=source,
+            environment=self.scope.static.environment,
+            release=self.scope.static.release,
+            trace_id=trace_id or self.scope.current_trace_id(),
+            commit_hash=self.commit_hash,
+            payload=payload,
+            tags=tags,
+            extra=extra,
+        )
+        return self._dispatch(envelope)
+
     # ------------------------------------------------------------------
     # Lifecycle
     # ------------------------------------------------------------------
@@ -209,6 +391,32 @@ class Client:
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _dispatch_footprint(self, footprint: Dict[str, Any]) -> Optional[str]:
+        """Scrub → before_send → size budget → transport submit."""
+        scrubbed = dict(footprint)
+        scrubbed.pop("_tags", None)
+        scrubbed.pop("_extra", None)
+        if self.before_send is not None:
+            try:
+                wrapped = {"payload": scrubbed, **scrubbed}
+                result = self.before_send(wrapped)  # type: ignore[assignment]
+            except Exception as exc:
+                debug(f"before_send raised {type(exc).__name__}: {exc}; dropping footprint")
+                return None
+            if result is None:
+                return None
+            if isinstance(result, dict) and "payload" in result:
+                scrubbed = result["payload"]
+            elif isinstance(result, dict):
+                scrubbed = result
+
+        if _byte_len_footprint(scrubbed) > MAX_ENVELOPE_BYTES:
+            debug("footprint exceeds size budget; dropping")
+            return None
+
+        accepted = self.transport.submit(scrubbed)
+        return scrubbed.get("request_id") if accepted else None
+
     def _dispatch(self, envelope: Dict[str, Any]) -> Optional[str]:
         """Scrub → before_send → size budget → transport submit."""
         envelope["payload"] = scrub(envelope.get("payload"), extra_keys=self.scrub_keys)
@@ -237,6 +445,24 @@ class Client:
             return tail.get("module") or tail.get("function")
         return None
 
+    @staticmethod
+    def _perf_summary_message(
+        *,
+        method: Optional[str],
+        op: str,
+        status_code: Optional[int],
+        duration_ms: float,
+    ) -> str:
+        """Short list-view label, e.g. `GET /api/users/ 200 45ms`."""
+        parts: List[str] = []
+        if method:
+            parts.append(method)
+        parts.append(op)
+        if status_code is not None:
+            parts.append(str(status_code))
+        parts.append(f"{duration_ms:.0f}ms")
+        return " ".join(parts)
+
 
 # ---------------------------------------------------------------------------
 # Module-level facade
@@ -259,6 +485,8 @@ def _set_active(client: Optional[Client]) -> None:
 @safe
 def init(
     dsn: Optional[str] = None,
+    *,
+    integrations: Optional[Sequence[IntegrationLike]] = None,
     **kwargs: Any,
 ) -> Optional[Client]:
     """
@@ -268,6 +496,9 @@ def init(
     Calling `init` a second time is allowed but logs a warning and
     closes the previous client first. The new client becomes the
     process-global one.
+
+    Pass framework integrations via `integrations=[...]`. Each integration's
+    `setup_once()` runs after the client is active.
     """
     global _active_client
     raw = _resolve_dsn_string(dsn)
@@ -280,6 +511,8 @@ def init(
         debug(f"invalid DSN: {exc}; entering disabled mode")
         return None
 
+    integration_list = list(integrations or [])
+
     with _init_lock:
         if _active_client is not None:
             debug("re-initializing; closing previous client")
@@ -287,9 +520,11 @@ def init(
                 _active_client.close()
             except Exception as exc:
                 debug(f"previous client close failed: {exc}")
-        client = Client(parsed, **kwargs)
+        enable_logs = bool(kwargs.pop("enable_logs", False))
+        client = Client(parsed, enable_logs=enable_logs, **kwargs)
         _set_active(client)
 
+    _setup_integrations(integration_list)
     atexit.register(_atexit_close)
     return client
 
@@ -347,6 +582,83 @@ def capture_message(
     )
 
 
+@safe
+def capture_log(
+    message: str,
+    *,
+    level: str = "info",
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    source: Optional[str] = None,
+    trace_id: Optional[str] = None,
+) -> Optional[str]:
+    client = _client()
+    if client is None:
+        return None
+    return client.capture_log(
+        message,
+        level=level,
+        tags=tags,
+        extra=extra,
+        source=source,
+        trace_id=trace_id,
+    )
+
+
+@safe
+def capture_request(
+    *,
+    duration_ms: float,
+    op: str,
+    status_code: Optional[int] = None,
+    method: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+    client = _client()
+    if client is None:
+        return None
+    return client.capture_request(
+        duration_ms=duration_ms,
+        op=op,
+        status_code=status_code,
+        method=method,
+        trace_id=trace_id,
+        tags=tags,
+        extra=extra,
+    )
+
+
+@safe
+def capture_perf(
+    op: str,
+    duration_ms: float,
+    *,
+    status_code: Optional[int] = None,
+    method: Optional[str] = None,
+    level: str = "info",
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    source: str = "django.request",
+    trace_id: Optional[str] = None,
+) -> Optional[str]:
+    client = _client()
+    if client is None:
+        return None
+    return client.capture_perf(
+        op,
+        duration_ms,
+        status_code=status_code,
+        method=method,
+        level=level,
+        tags=tags,
+        extra=extra,
+        source=source,
+        trace_id=trace_id,
+    )
+
+
 @safe
 def flush(timeout: Optional[float] = None) -> bool:
     client = _client()

insider/contrib/django/apps.py

@@ -13,6 +13,7 @@ from typing import Any, Dict
 from django.apps import AppConfig
 
 from ... import init
+from ...integrations.django import DjangoIntegration
 from ...safety import debug
 
 
@@ -57,4 +58,4 @@ class InsiderConfig(AppConfig):
         # env-var fallback in `init` still applies if Django's settings
         # didn't define it.
         dsn = kwargs.pop("dsn", None)
-        init(dsn, **kwargs)
+        init(dsn, integrations=[DjangoIntegration()], **kwargs)