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

insider_python-0.1.5/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: insider-python
+Version: 0.1.5
+Summary: Python SDK for Insider — ship Beacons to your Insider server.
+Author: Insider
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Insider-Inc/insider-python
+Keywords: insider,telemetry,errors,monitoring,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3>=1.26
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: django>=4.2; extra == "dev"
+Requires-Dist: djangorestframework>=3.14; extra == "dev"
+
+# 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()` /
+`get_asgi_application()`:
+
+#### WSGI (Gunicorn)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+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()
+```
+
+#### ASGI (Daphne / Uvicorn — plain Django)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    release="1.2.3",
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
+)
+
+from django.core.asgi import get_asgi_application
+application = get_asgi_application()
+```
+
+#### ASGI + Channels (`ProtocolTypeRouter`)
+
+Wrap only the HTTP branch; disable handler auto-perf to avoid double capture:
+
+```python
+import os
+import django
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+
+django.setup()
+
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.django.asgi import wrap_asgi_application
+from insider.integrations.logging import LoggingIntegration
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    enable_logs=True,
+    integrations=[DjangoIntegration(auto_perf=False), LoggingIntegration()],
+)
+
+from channels.routing import ProtocolTypeRouter, URLRouter
+from django.core.asgi import get_asgi_application
+
+application = ProtocolTypeRouter({
+    "http": wrap_asgi_application(get_asgi_application()),
+    "websocket": URLRouter(websocket_urlpatterns),
+})
+```
+
+Set `INSIDER_DEBUG=true` to print which hooks installed at startup.
+
+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.5/README.md

@@ -0,0 +1,210 @@
+# 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()` /
+`get_asgi_application()`:
+
+#### WSGI (Gunicorn)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+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()
+```
+
+#### ASGI (Daphne / Uvicorn — plain Django)
+
+```python
+import os
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.logging import LoggingIntegration
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    release="1.2.3",
+    enable_logs=True,
+    integrations=[DjangoIntegration(), LoggingIntegration()],
+)
+
+from django.core.asgi import get_asgi_application
+application = get_asgi_application()
+```
+
+#### ASGI + Channels (`ProtocolTypeRouter`)
+
+Wrap only the HTTP branch; disable handler auto-perf to avoid double capture:
+
+```python
+import os
+import django
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+
+django.setup()
+
+import insider
+from insider.integrations.django import DjangoIntegration
+from insider.integrations.django.asgi import wrap_asgi_application
+from insider.integrations.logging import LoggingIntegration
+
+insider.init(
+    dsn=os.environ.get("INSIDER_DSN"),
+    environment="production",
+    enable_logs=True,
+    integrations=[DjangoIntegration(auto_perf=False), LoggingIntegration()],
+)
+
+from channels.routing import ProtocolTypeRouter, URLRouter
+from django.core.asgi import get_asgi_application
+
+application = ProtocolTypeRouter({
+    "http": wrap_asgi_application(get_asgi_application()),
+    "websocket": URLRouter(websocket_urlpatterns),
+})
+```
+
+Set `INSIDER_DEBUG=true` to print which hooks installed at startup.
+
+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.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "insider-python"
-version = "0.1.3"
+version = "0.1.5"
 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.5}/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.5}/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.5/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.5}/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.5"