insider-python 0.1.3__tar.gz → 0.1.4__tar.gz

{insider_python-0.1.3 → insider_python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: insider-python
-Version: 0.1.3
+Version: 0.1.4
 Summary: Python SDK for Insider — ship Beacons to your Insider server.
 Author: Insider
 License-Expression: MIT
@@ -63,10 +63,11 @@ try:
     risky()
 except Exception as exc:
     insider.capture_exception(exc)
-
-insider.capture_message("cache miss spiked", level="warning")
 ```
 
+Out-of-band events (background jobs, explicit calls) use standalone beacons:
+`capture_exception`, `capture_log`, `capture_perf`.
+
 ### Django
 
 Initialize in `wsgi.py` (or `asgi.py`) before `get_wsgi_application()`:
@@ -75,57 +76,98 @@ Initialize in `wsgi.py` (or `asgi.py`) before `get_wsgi_application()`:
 import os
 import insider
 from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
 
 insider.init(
     dsn=os.environ.get("INSIDER_DSN"),
     environment="production",
     release="1.2.3",
-    integrations=[DjangoIntegration()],
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
 )
 
 from django.core.wsgi import get_wsgi_application
 application = get_wsgi_application()
 ```
 
-That's the whole setup. Every unhandled exception in a view — including
-Django REST Framework API views — is now a Beacon in your dashboard.
+That's the whole setup. **Every HTTP request** emits **one** `kind=request`
+beacon containing:
+
+- timing (duration, method, path, status)
+- request context (headers, path, query string)
+- stdlib logs during that request (when `enable_logs=True`)
+- unhandled exception + stack trace (when the request fails)
+
 No middleware, no `INSTALLED_APPS`, and no `EXCEPTION_HANDLER` wiring.
 
-**Legacy setup** (still supported): add `insider.contrib.django` to
-`INSTALLED_APPS` and `InsiderMiddleware` to `MIDDLEWARE`. Prefer the
-`wsgi.py` pattern for new projects.
+Disable auto capture on high-traffic apps until sampling lands:
 
-## Configuration
+```python
+integrations=[DjangoIntegration(auto_perf=False)]
+```
+
+### Logging
+
+During an HTTP request, stdlib `logging` lines are **buffered into the
+request envelope** — not beamed as separate rows:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("checkout completed")  # → payload.logs[] on the request beacon
+```
 
-Order of precedence (first wins):
+Requires `enable_logs=True`, `LoggingIntegration()`, and a configured
+logger level (see your app's `LOGGING` settings).
 
-1. Keyword args to `insider.init(...)`.
-2. `INSIDER_*` environment variables.
-3. Django settings (when the Django integration is active).
-4. Hard-coded defaults.
+Outside an HTTP request, stdlib logs still beam as standalone `kind=log`
+beacons. For explicit structured events, use `capture_log()`:
+
+```python
+insider.capture_log(
+    "User checkout completed",
+    level="info",
+    source="checkout.service",
+    tags={"feature": "checkout"},
+)
+```
+
+Manual perf timings (Celery, custom spans):
+
+```python
+insider.capture_perf(
+    op="celery.tasks.send_email",
+    duration_ms=842,
+)
+```
+
+## Footprint kinds
+
+| Kind | When |
+|------|------|
+| `request` | One per HTTP request (DjangoIntegration) |
+| `error` | Manual `capture_exception()` outside request cycle |
+| `log` | Manual `capture_log()` or stdlib logs outside request cycle |
+| `perf` | Manual `capture_perf()` for non-HTTP timings |
+
+## Configuration
 
 If no DSN is found anywhere, the SDK enters **disabled mode**: every
-public call is a no-op, no thread starts, no socket opens.
+public call is a no-op.
 
 | Option | Default | Notes |
 |--------|---------|-------|
 | `dsn` | env `INSIDER_DSN` | If absent, SDK is disabled |
-| `environment` | `"production"` | Top-level Beacon field |
-| `release` | `None` | Top-level Beacon field |
-| `send_default_pii` | `False` | Required to capture `user.id`, request bodies |
-| `before_send` | `None` | `(beacon) -> beacon | None` hook |
-| `scrub_keys` | `None` | Extra keys to filter (added to the default deny-list) |
-| `in_app_include` | `None` | Filename prefixes considered "your code" |
-| `transport_queue_size` | `1000` | Bounded; drops on overflow |
-| `transport_flush_timeout` | `2.0` | Seconds. Used by `close()` / `flush()` |
-| `debug` | `False` | Print SDK's own warnings to stderr |
+| `environment` | `"production"` | Top-level Footprint field |
+| `release` | `None` | Top-level Footprint field |
+| `enable_logs` | `False` | Buffer stdlib logs into request envelopes |
+| `send_default_pii` | `False` | Required to capture request bodies |
+| `debug` | `False` | Print SDK warnings to stderr |
 
 ## Promise
 
-The SDK never raises into your code. Every public function catches
-`Exception` at its boundary; if something goes wrong inside the SDK,
-you get nothing back and a debug log (if enabled). Your app keeps
-running.
+The SDK never raises into your code.
 
 ## License
 

insider_python-0.1.4/README.md

@@ -0,0 +1,146 @@
+# insider-python
+
+The Python SDK for [Insider](https://insider.moraks.cloud/).
+
+Beam Beacons from your Python service to your Insider server with a
+one-line setup. No runtime overhead on your request path. Never raises
+into your code, no matter what.
+
+## Install
+
+```bash
+pip install insider-python
+```
+
+For the Django integration:
+
+```bash
+pip install "insider-python[django]"
+```
+
+## Quick start
+
+### Plain Python
+
+```python
+import insider
+
+insider.init(
+    dsn="https://<beacon_token>@insider.example.com/<project_uuid>",
+    environment="production",
+    release="1.2.3",
+)
+
+try:
+    risky()
+except Exception as exc:
+    insider.capture_exception(exc)
+```
+
+Out-of-band events (background jobs, explicit calls) use standalone beacons:
+`capture_exception`, `capture_log`, `capture_perf`.
+
+### Django
+
+Initialize in `wsgi.py` (or `asgi.py`) before `get_wsgi_application()`:
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    release="1.2.3",
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
+)
+
+from django.core.wsgi import get_wsgi_application
+application = get_wsgi_application()
+```
+
+That's the whole setup. **Every HTTP request** emits **one** `kind=request`
+beacon containing:
+
+- timing (duration, method, path, status)
+- request context (headers, path, query string)
+- stdlib logs during that request (when `enable_logs=True`)
+- unhandled exception + stack trace (when the request fails)
+
+No middleware, no `INSTALLED_APPS`, and no `EXCEPTION_HANDLER` wiring.
+
+Disable auto capture on high-traffic apps until sampling lands:
+
+```python
+integrations=[DjangoIntegration(auto_perf=False)]
+```
+
+### Logging
+
+During an HTTP request, stdlib `logging` lines are **buffered into the
+request envelope** — not beamed as separate rows:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("checkout completed")  # → payload.logs[] on the request beacon
+```
+
+Requires `enable_logs=True`, `LoggingIntegration()`, and a configured
+logger level (see your app's `LOGGING` settings).
+
+Outside an HTTP request, stdlib logs still beam as standalone `kind=log`
+beacons. For explicit structured events, use `capture_log()`:
+
+```python
+insider.capture_log(
+    "User checkout completed",
+    level="info",
+    source="checkout.service",
+    tags={"feature": "checkout"},
+)
+```
+
+Manual perf timings (Celery, custom spans):
+
+```python
+insider.capture_perf(
+    op="celery.tasks.send_email",
+    duration_ms=842,
+)
+```
+
+## Footprint kinds
+
+| Kind | When |
+|------|------|
+| `request` | One per HTTP request (DjangoIntegration) |
+| `error` | Manual `capture_exception()` outside request cycle |
+| `log` | Manual `capture_log()` or stdlib logs outside request cycle |
+| `perf` | Manual `capture_perf()` for non-HTTP timings |
+
+## Configuration
+
+If no DSN is found anywhere, the SDK enters **disabled mode**: every
+public call is a no-op.
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `dsn` | env `INSIDER_DSN` | If absent, SDK is disabled |
+| `environment` | `"production"` | Top-level Footprint field |
+| `release` | `None` | Top-level Footprint field |
+| `enable_logs` | `False` | Buffer stdlib logs into request envelopes |
+| `send_default_pii` | `False` | Required to capture request bodies |
+| `debug` | `False` | Print SDK warnings to stderr |
+
+## Promise
+
+The SDK never raises into your code.
+
+## License
+
+MIT

{insider_python-0.1.3 → insider_python-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "insider-python"
-version = "0.1.3"
+version = "0.1.4"
 description = "Python SDK for Insider — ship Beacons to your Insider server."
 readme = "README.md"
 requires-python = ">=3.8"

{insider_python-0.1.3 → insider_python-0.1.4}/src/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_python-0.1.3 → insider_python-0.1.4}/src/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_python-0.1.4/src/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_python-0.1.3 → insider_python-0.1.4}/src/insider/_version.py

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