devlite 0.1.0__py3-none-any.whl

devlite/__init__.py

@@ -0,0 +1,147 @@
+"""DevLite Python SDK — AI-powered observability with a 2-line integration.
+
+    import devlite
+
+    devlite.init({api_key: "dl_live_xxxxx"})
+
+Automatic request tracking, error grouping, source context, user impact
+tracking, and sensitive-data scrubbing — mirroring the @devlite/nodejs npm
+SDK, with zero runtime dependencies.
+
+Public API (all Pythonic snake_case):
+    init, capture_error, capture_message, report_metric, capture_log,
+    start_span, report_span, report_deployment, add_breadcrumb, set_tag,
+    set_user, run_with_context, start_host_metrics, instrument_flask,
+    flush, close
+"""
+
+from ._client import Client, HostMetricsHandle, Span
+from ._context import run_with_context
+
+__version__ = "0.1.0"
+
+_client = None
+
+
+def init(options=None):
+    """Initialize DevLite. The only required call.
+
+    Args:
+        options: dict with keys like api_key, environment, service_name,
+            release, sample_rate, gzip, debug, endpoint, on_error, ...
+            `api_key` is required (or set DEVLITE_API_KEY env var).
+    """
+    global _client
+    if _client is not None:
+        import warnings
+
+        warnings.warn("[DevLite] init() called more than once — ignoring subsequent call.")
+        return
+    _client = Client(options or {})
+
+
+def _require_client():
+    if _client is None:
+        raise RuntimeError("[DevLite] SDK not initialized. Call devlite.init(api_key=...) first.")
+    return _client
+
+
+def capture_error(error, extra=None):
+    """Capture a handled error with optional extra context."""
+    _require_client().capture_error(error, extra=extra)
+
+
+def capture_message(message, level="info", extra=None):
+    """Capture a non-error event, e.g. a business-logic message."""
+    _require_client().capture_message(message, level=level, extra=extra)
+
+
+def report_metric(name, value, unit=None, tags=None):
+    """Report a metric data point (feeds forecasting/anomaly detection)."""
+    _require_client().report_metric(name, value, unit=unit, tags=tags)
+
+
+def capture_log(message, level="info", fields=None):
+    """Capture a structured log line with arbitrary fields."""
+    _require_client().capture_log(message, level=level, fields=fields)
+
+
+def start_span(name, options=None):
+    """Start a trace span; returns an object with id/trace_id and end(status)."""
+    return _require_client().start_span(name, options=options)
+
+
+def report_span(name, trace_id=None, parent_id=None, tags=None, start_time=None, end_time=None, duration_ms=None, status="ok"):
+    """Report a finished span if you track timing yourself."""
+    _require_client().report_span(
+        name,
+        trace_id=trace_id,
+        parent_id=parent_id,
+        tags=tags,
+        start_time=start_time,
+        end_time=end_time,
+        duration_ms=duration_ms,
+        status=status,
+    )
+
+
+def report_deployment(version=None, commit_sha=None, notes=None):
+    """Report a deployment — powers performance before/after deployment views."""
+    _require_client().report_deployment(version=version, commit_sha=commit_sha, notes=notes)
+
+
+def add_breadcrumb(entry):
+    """Add a manual breadcrumb (e.g. 'user started checkout') for richer AI context."""
+    _require_client().add_breadcrumb(entry)
+
+
+def set_tag(key, value):
+    """Tag all subsequent events, e.g. set_tag('region', 'lagos')."""
+    _require_client().set_tag(key, value)
+
+
+def set_user(user):
+    """Identify the user for the CURRENT request (scoped to the request)."""
+    _require_client().set_user(user)
+
+
+def start_host_metrics(interval_ms=15000):
+    """Start sampling host CPU/memory (plus network/disk on Linux) as metrics."""
+    return _require_client().start_host_metrics(interval_ms=interval_ms)
+
+
+def instrument_flask(app):
+    """Wire automatic request/error/user tracking into a Flask app."""
+    return _require_client().instrument_flask(app)
+
+
+def flush():
+    """Force-send whatever is currently queued (useful in serverless)."""
+    _require_client().flush()
+
+
+def close():
+    """Cleanly stop the SDK — flushes remaining events."""
+    if _client is not None:
+        _client.close()
+
+
+__all__ = [
+    "__version__",
+    "init",
+    "capture_error",
+    "capture_message",
+    "report_metric",
+    "capture_log",
+    "start_span",
+    "report_span",
+    "report_deployment",
+    "add_breadcrumb",
+    "set_tag",
+    "set_user",
+    "run_with_context",
+    "start_host_metrics",
+    "instrument_flask",
+    "flush",
+    "close",
+]

devlite/_client.py

@@ -0,0 +1,184 @@
+"""DevLite client — the singleton that owns config, transport, and context."""
+
+import atexit
+import threading
+import uuid
+
+from ._config import build_config
+from ._context import Context, get_user, now_ms, run_with_context
+from ._errors import build_error_event
+from ._metrics import collect_host_metrics
+from ._scrub import scrub_deep
+from ._transport import Transport
+
+
+def _new_hex(nbytes):
+    return uuid.uuid4().hex[: nbytes * 2]
+
+
+class Span:
+    """A trace span you can end() once the work completes."""
+
+    def __init__(self, client, name, options=None):
+        options = options or {}
+        self.client = client
+        self.type = "span"
+        self.id = options.get("id") or _new_hex(6)
+        self.name = name
+        self.trace_id = options.get("trace_id") or _new_hex(8)
+        self.parent_id = options.get("parent_id")
+        self.tags = options.get("tags") or {}
+        self.start_time = now_ms()
+        self.end_time = None
+        self.duration_ms = None
+        self.status = None
+
+    def end(self, status="ok"):
+        self.end_time = now_ms()
+        self.duration_ms = self.end_time - self.start_time
+        self.status = status
+        event = {
+            "type": "span",
+            "id": self.id,
+            "name": self.name,
+            "traceId": self.trace_id,
+            "parentId": self.parent_id,
+            "tags": self.tags,
+            "startTime": self.start_time,
+            "endTime": self.end_time,
+            "durationMs": self.duration_ms,
+            "status": status,
+        }
+        self.client._enqueue_scubbed(event)
+
+
+class HostMetricsHandle:
+    def __init__(self, client, interval_ms):
+        self.client = client
+        self.interval_ms = max(1000, interval_ms)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="devlite-host-metrics")
+        self._thread.start()
+
+    def _run(self):
+        self._sample()
+        while not self._stop.wait(self.interval_ms / 1000.0):
+            self._sample()
+
+    def _sample(self):
+        try:
+            for metric in collect_host_metrics():
+                self.client._transport.enqueue(metric)
+        except Exception:
+            pass
+
+    def stop(self):
+        self._stop.set()
+
+
+class _NoopHandle:
+    def stop(self):
+        pass
+
+
+class Client:
+    def __init__(self, options):
+        self.config = build_config(options)
+        self.context = Context()
+        self.transport = Transport(self.config)
+        self._host_metrics = None
+        self._closed = False
+        atexit.register(self.close)
+
+    # --- public API (also exposed at package top level) -------------------
+
+    def capture_error(self, error, extra=None):
+        event = build_error_event(
+            error,
+            self.config,
+            breadcrumbs=self.context.snapshot().get("breadcrumbs", []),
+            user=get_user(),
+            extra=extra or {},
+        )
+        self.transport.enqueue(event)
+
+    def capture_message(self, message, level="info", extra=None):
+        raw = {"type": "message", "level": level, "message": message, "extra": extra or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def report_metric(self, name, value, unit=None, tags=None):
+        if not isinstance(name, str) or not name:
+            raise ValueError("[DevLite] report_metric() requires a string `name`.")
+        if not isinstance(value, (int, float)):
+            raise ValueError("[DevLite] report_metric() requires a numeric `value`.")
+        raw = {"type": "metric", "name": name, "value": value, "unit": unit or None, "tags": tags or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def capture_log(self, message, level="info", fields=None):
+        raw = {"type": "log", "level": level, "message": message, "fields": fields or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def start_span(self, name, options=None):
+        return Span(self, name, options)
+
+    def report_span(self, name, trace_id=None, parent_id=None, tags=None, start_time=None, end_time=None, duration_ms=None, status="ok"):
+        raw = {
+            "type": "span",
+            "id": _new_hex(6),
+            "name": name,
+            "traceId": trace_id or _new_hex(8),
+            "parentId": parent_id,
+            "tags": tags or {},
+            "startTime": start_time,
+            "endTime": end_time,
+            "durationMs": duration_ms,
+            "status": status,
+            "timestamp": now_ms(),
+        }
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def report_deployment(self, version=None, commit_sha=None, notes=None):
+        self.transport.enqueue(
+            {"type": "deployment", "version": version, "commitSha": commit_sha, "notes": notes, "timestamp": now_ms()}
+        )
+
+    def add_breadcrumb(self, entry):
+        self.context.add_breadcrumb(entry or {})
+
+    def set_tag(self, key, value):
+        self.context.set_tag(key, value)
+
+    def set_user(self, user):
+        from ._context import set_user as _set_user
+
+        _set_user(user)
+
+    def start_host_metrics(self, interval_ms=15000):
+        if self._host_metrics:
+            return _NoopHandle()  # no-op if already running
+        self._host_metrics = HostMetricsHandle(self, interval_ms)
+        return self._host_metrics
+
+    def instrument_flask(self, app):
+        from ._flask import instrument_flask
+
+        return instrument_flask(app, self.transport, self.context, self.config)
+
+    def flush(self):
+        self.transport.flush()
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._host_metrics:
+            self._host_metrics.stop()
+        self.transport.close()
+
+    # --- internals --------------------------------------------------------
+
+    def _should_scrub(self):
+        return self.config.get("scrub_sensitive_data", True) is not False
+
+    def _enqueue_scubbed(self, event):
+        self.transport.enqueue(scrub_deep(event) if self._should_scrub() else event)

devlite/_config.py

@@ -0,0 +1,62 @@
+"""Configuration for the DevLite Python SDK.
+
+Mirrors devlite-sdk's config.js so both SDKs behave identically. Defaults
+are deliberately safe: scrubbing on, request bodies off, bounded queue.
+"""
+
+import os
+
+DEFAULT_ENDPOINT = "https://devlite.andasy.dev/v1/events"
+DEFAULT_ENVIRONMENT = os.environ.get("DEVLITE_ENVIRONMENT", "development")
+DEFAULT_SERVICE_NAME = os.environ.get(
+    "DEVLITE_SERVICE_NAME",
+    os.path.basename(os.getcwd()) or "python-service",
+)
+DEFAULT_RELEASE = os.environ.get("DEVLITE_RELEASE", None)
+
+DEFAULTS = {
+    "endpoint": DEFAULT_ENDPOINT,
+    "environment": DEFAULT_ENVIRONMENT,
+    "service_name": DEFAULT_SERVICE_NAME,
+    "release": DEFAULT_RELEASE,
+    "flush_interval_ms": 5000,
+    "max_batch_size": 100,
+    "max_queue_size": 5000,  # hard ceiling to protect memory if network is down
+    "sample_rate": 1.0,  # 1.0 = capture 100% of requests
+    "capture_body": False,  # whether to capture (redacted) request headers
+    "redact_headers": ["authorization", "cookie", "x-api-key"],
+    "debug": False,
+    "max_retries": 3,
+    "retry_base_delay_ms": 500,
+    "gzip": True,  # compress request bodies with Content-Encoding: gzip
+    "on_error": None,  # optional callback(err) for SDK-internal failures
+    "capture_source_context": True,  # attach surrounding source lines to errors
+    "scrub_sensitive_data": True,  # auto-redact emails, tokens, credit cards, etc.
+    "capture_console_breadcrumbs": True,  # log warnings/errors become breadcrumbs
+    "request_timeout_ms": 10000,
+}
+
+
+def build_config(options):
+    """Merge user options over the defaults; validates the essentials.
+
+    Raises ValueError with a clear message on invalid config, mirroring
+    buildConfig() in the Node SDK.
+    """
+    if not options:
+        options = {}
+    api_key = options.get("api_key") or os.environ.get("DEVLITE_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "[DevLite] init() requires an `api_key` (or DEVLITE_API_KEY env var)."
+        )
+
+    config = dict(DEFAULTS)
+    config.update({k: v for k, v in options.items() if v is not None})
+    config["api_key"] = api_key
+
+    sample_rate = config["sample_rate"]
+    if not isinstance(sample_rate, (int, float)) or sample_rate < 0 or sample_rate > 1:
+        raise ValueError("[DevLite] `sample_rate` must be a number between 0 and 1.")
+
+    return config

devlite/_context.py

@@ -0,0 +1,78 @@
+"""Request-scoped context: breadcrumbs, tags, and the current user.
+
+Python equivalent of context.js + userContext.js from the Node SDK. Uses
+contextvars (the modern replacement for thread-locals) so user context set
+inside one request handler never leaks across concurrent requests.
+"""
+
+import contextvars
+import time
+
+MAX_BREADCRUMBS = 20
+
+_request_store = contextvars.ContextVar("devlite_request_store", default=None)
+
+
+def _store():
+    store = _request_store.get()
+    if store is None:
+        store = {}
+        _request_store.set(store)
+    return store
+
+
+class Context:
+    """Keeps a small rolling log of recent events (breadcrumbs) and global tags."""
+
+    def __init__(self):
+        self.breadcrumbs = []
+        self.tags = {}
+
+    def add_breadcrumb(self, entry):
+        self.breadcrumbs.append({"timestamp": now_ms(), **entry})
+        if len(self.breadcrumbs) > MAX_BREADCRUMBS:
+            self.breadcrumbs.pop(0)
+
+    def set_tag(self, key, value):
+        self.tags[key] = value
+
+    def snapshot(self):
+        return {"breadcrumbs": list(self.breadcrumbs), "tags": dict(self.tags)}
+
+
+def run_with_context(fn, seed=None):
+    """Run fn inside a fresh request context, optionally seeded (e.g. sampled=False)."""
+    previous = _request_store.get()
+    _request_store.set(dict(seed) if seed else {})
+    try:
+        return fn()
+    finally:
+        _request_store.set(previous)
+
+
+def set_user(user):
+    """Scope a user to the current request context. Mirrors devlite.setUser()."""
+    store = _store()
+    if isinstance(user, dict):
+        store["user"] = user
+    else:
+        store["user"] = {"id": str(user)}
+
+
+def get_user():
+    store = _request_store.get()
+    return (store or {}).get("user") or None
+
+
+def set_sampled(value):
+    store = _store()
+    store["sampled"] = value
+
+
+def is_sampled_out():
+    store = _request_store.get()
+    return bool(store) and store.get("sampled") is False
+
+
+def now_ms():
+    return int(time.time() * 1000)

devlite/_errors.py

@@ -0,0 +1,111 @@
+"""Error-event enrichment: grouping fingerprint, source context, scrubbing.
+
+Python port of errorEvent.js / fingerprint.js / sourceContext.js from the
+Node SDK, so errors captured by either SDK group into the same issue shape.
+"""
+
+import hashlib
+import os
+import re
+import traceback
+
+from ._context import now_ms
+from ._scrub import scrub_deep
+
+_NUMBER_RE = re.compile(r"\d+")
+_FRAME_NUMBERS_RE = re.compile(r", line \d+")
+_MAX_FINGERPRINT_FRAMES = 5
+_SOURCE_CONTEXT_LINES = 3
+
+
+def normalize_message(message):
+    if not message:
+        return ""
+    return re.sub(r"\s+", " ", _NUMBER_RE.sub("#", str(message))).strip()
+
+
+def normalize_stack_frames(stack, max_frames=_MAX_FINGERPRINT_FRAMES):
+    """Strip line numbers (which change per-instance) but keep file + function."""
+    if not stack:
+        return ""
+    lines = [line for line in stack.splitlines() if line.strip().startswith("File ")]
+    frames = [_FRAME_NUMBERS_RE.sub("", line).strip() for line in lines[:max_frames]]
+    return "|".join(frames)
+
+
+def compute_fingerprint(type_, message, stack, custom_key=None):
+    """Stable fingerprint so the SAME bug groups into a single issue.
+
+    Honors an explicit custom_key (manual grouping) over heuristics.
+    """
+    if custom_key:
+        basis = str(custom_key)
+    else:
+        basis = "{}::{}::{}".format(type_ or "Error", normalize_message(message), normalize_stack_frames(stack))
+    return hashlib.sha1(basis.encode("utf-8", errors="replace")).hexdigest()[:16]
+
+
+def get_source_context(tb, context_lines=_SOURCE_CONTEXT_LINES):
+    """Read the actual lines of code around the crash, live from disk.
+
+    Returns a list of {line, content} dicts or None if the source is
+    unavailable (stdlib frames, missing files, etc.).
+    """
+    try:
+        frames = traceback.extract_tb(tb)
+        if not frames:
+            return None
+        frame = frames[-1]  # innermost frame = where the exception was raised
+        filename = frame.filename
+        lineno = frame.lineno
+        if not filename or not os.path.isfile(filename):
+            return None
+        with open(filename, "r", encoding="utf-8", errors="replace") as fh:
+            lines = fh.read().splitlines()
+        start = max(0, lineno - 1 - context_lines)
+        end = min(len(lines), lineno + context_lines)
+        return [
+            {"line": i + 1, "content": lines[i]}
+            for i in range(start, end)
+        ]
+    except Exception:
+        return None
+
+
+def format_stack(exc):
+    try:
+        return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    except Exception:
+        return str(exc)
+
+
+def build_error_event(exc, config, breadcrumbs=None, user=None, extra=None, fatal=False):
+    """Assemble a fully-enriched error event — same shape as the Node SDK."""
+    name = type(exc).__name__ if exc is not None else "Error"
+    message = str(exc) or name
+    stack = format_stack(exc)
+
+    extra = dict(extra) if extra else {}
+    fingerprint = compute_fingerprint(name, message, stack, custom_key=extra.get("fingerprint"))
+
+    source_context = None
+    if config.get("capture_source_context", True) and exc is not None:
+        source_context = get_source_context(exc.__traceback__)
+
+    raw_event = {
+        "type": "error",
+        "fatal": fatal,
+        "name": name,
+        "message": message,
+        "stack": stack,
+        "fingerprint": fingerprint,
+        "sourceContext": source_context,
+        "user": user or None,
+        "breadcrumbs": breadcrumbs or [],
+        "extra": extra,
+        "timestamp": now_ms(),
+    }
+
+    if config.get("scrub_sensitive_data", True):
+        return scrub_deep(raw_event)
+    return raw_event

devlite/_flask.py

@@ -0,0 +1,115 @@
+"""Optional Flask instrumentation.
+
+Call devlite.instrument_flask(app) after creating your Flask app to get:
+  - automatic request + slow_request events for every HTTP request
+  - unhandled exception capture with full enrichment (grouping, source
+    context, user impact, breadcrumbs)
+  - request-scoped user context (devlite.set_user() inside handlers)
+  - request breadcrumbs feeding the AI's root-cause explanation
+
+Flask itself is an optional dependency (installed separately); importing
+this module never requires it — the import happens lazily in
+instrument_flask().
+"""
+
+import time
+from contextvars import ContextVar
+
+from ._context import now_ms, run_with_context
+
+_request_start = ContextVar("devlite_request_start", default=None)
+_request_meta = ContextVar("devlite_request_meta", default=None)
+
+SLOW_REQUEST_THRESHOLD_MS = 1000
+
+
+def _record_start():
+    _request_start.set(time.time() * 1000)
+    _request_meta.set(None)
+
+
+def _redact_headers(headers, redact_list):
+    out = {}
+    for key, value in headers.items():
+        out[key] = "[REDACTED]" if key.lower() in redact_list else value
+    return out
+
+
+def instrument_flask(app, transport, context, config):
+    """Wire Flask request/exception hooks into the SDK transport."""
+    redact_list = config.get("redact_headers", ["authorization", "cookie", "x-api-key"])
+    capture_body = config.get("capture_body", False)
+    sample_rate = float(config.get("sample_rate", 1.0))
+    sample_every = 1.0 / sample_rate if sample_rate > 0 else float("inf")
+
+    import random
+
+    counter = [0]
+
+    @app.before_request
+    def _start():
+        run_with_context(lambda: None)  # fresh request context
+        _record_start()
+        counter[0] += 1
+        sampled = sample_rate >= 1.0 or (counter[0] % int(sample_every) == 0)
+        from ._context import set_sampled
+
+        set_sampled(sampled)
+
+    @app.after_request
+    def _finish(response):
+        start = _request_start.get()
+        if start is None:
+            return response
+        duration_ms = int(now_ms() - start)
+        meta = _request_meta.get() or {}
+        path = meta.get("path") or (response.request.path if getattr(response, "request", None) else "/")
+        method = meta.get("method") or (response.request.method if getattr(response, "request", None) else "GET")
+        status = response.status_code
+
+        context.add_breadcrumb({"type": "request", "method": method, "path": path, "statusCode": status, "durationMs": duration_ms})
+
+        headers = None
+        if capture_body and getattr(response, "request", None):
+            headers = _redact_headers(response.request.headers, redact_list)
+
+        transport.enqueue({
+            "type": "request",
+            "method": method,
+            "path": path,
+            "statusCode": status,
+            "durationMs": duration_ms,
+            "headers": headers,
+            "timestamp": int(start),
+        })
+        if duration_ms > SLOW_REQUEST_THRESHOLD_MS:
+            transport.enqueue({
+                "type": "slow_request",
+                "method": method,
+                "path": path,
+                "durationMs": duration_ms,
+                "timestamp": int(start),
+            })
+        return response
+
+    @app.errorhandler(Exception)
+    def _on_error(exc):
+        from werkzeug.exceptions import HTTPException
+
+        if isinstance(exc, HTTPException) and exc.code and exc.code < 500:
+            return exc  # 4xx are handled responses, not incidents
+
+        from ._context import get_user
+        from ._errors import build_error_event
+
+        breadcrumbs = context.snapshot().get("breadcrumbs", [])
+        event = build_error_event(
+            exc,
+            config,
+            breadcrumbs=breadcrumbs,
+            user=get_user(),
+        )
+        transport.enqueue(event)
+        raise exc
+
+    return app

devlite/_metrics.py

@@ -0,0 +1,207 @@
+"""Zero-dependency host telemetry sampler — Python port of systemMetrics.js.
+
+Collects process CPU %, memory (process + system), CPU load, and — on
+Linux, where /proc exposes it — network and disk throughput deltas. On
+Windows, only CPU/memory/load are reported. Emits plain DevLite `metric`
+events ready for the transport queue.
+"""
+
+import os
+import platform
+import socket
+import sys
+import time
+
+from ._context import now_ms
+
+_last_cpu = os.times()
+_last_cpu_at = time.time()
+_last_network = None
+_last_disk = None
+
+_SYS_TICKS = os.sysconf("SC_CLK_TCK") if hasattr(os, "sysconf") else 100
+
+
+def cpu_percent():
+    """% of a single core the process is using since the last call (0-100)."""
+    global _last_cpu, _last_cpu_at
+    now = time.time()
+    cur = os.times()
+    dt = max(1.0, now - _last_cpu_at)
+    user = (cur.user - _last_cpu.user) + (cur.children_user - _last_cpu.children_user)
+    system = (cur.system - _last_cpu.system) + (cur.children_system - _last_cpu.children_system)
+    _last_cpu = cur
+    _last_cpu_at = now
+    pct = ((user + system) / dt) * 100.0
+    return round(min(100.0, pct), 2)
+
+
+def _process_rss_bytes():
+    """Resident set size in bytes, cross-platform, no dependencies."""
+    if sys.platform == "linux":
+        try:
+            with open("/proc/self/status", "r", encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    if line.startswith("VmRSS:"):
+                        return int(line.split()[1]) * 1024
+        except Exception:
+            pass
+    elif sys.platform == "win32":
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            class PROCESS_MEMORY_COUNTERS(ctypes.Structure):
+                _fields_ = [
+                    ("cb", wintypes.DWORD),
+                    ("PageFaultCount", wintypes.DWORD),
+                    ("PeakWorkingSetSize", ctypes.c_size_t),
+                    ("WorkingSetSize", ctypes.c_size_t),
+                    ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+                    ("PagefileUsage", ctypes.c_size_t),
+                    ("PeakPagefileUsage", ctypes.c_size_t),
+                ]
+
+            counters = PROCESS_MEMORY_COUNTERS()
+            counters.cb = ctypes.sizeof(PROCESS_MEMORY_COUNTERS)
+            handle = ctypes.windll.kernel32.GetCurrentProcess()
+            if ctypes.windll.psapi.GetProcessMemoryInfo(handle, ctypes.byref(counters), counters.cb):
+                return counters.WorkingSetSize
+        except Exception:
+            pass
+    else:  # macOS / BSD
+        try:
+            import resource
+
+            return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss * 1024
+        except Exception:
+            pass
+    return None
+
+
+def memory_snapshot():
+    return {"rss": _process_rss_bytes()}
+
+
+def _read_net_dev():
+    if platform.system() != "Linux":
+        return None
+    try:
+        rx = 0
+        tx = 0
+        with open("/proc/net/dev", "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh.readlines()[2:]:
+                parts = line.split(":")
+                if len(parts) < 2:
+                    continue
+                fields = parts[1].split()
+                if len(fields) < 9:
+                    continue
+                try:
+                    rx += int(fields[0])
+                    tx += int(fields[8])
+                except ValueError:
+                    pass
+        return {"rx": rx, "tx": tx}
+    except Exception:
+        return None
+
+
+def _read_disk_stats():
+    if platform.system() != "Linux":
+        return None
+    try:
+        read_bytes = 0
+        write_bytes = 0
+        with open("/proc/diskstats", "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                parts = line.split()
+                if len(parts) < 10:
+                    continue
+                name = parts[2]
+                if name.startswith(("loop", "ram", "zram", "dm-")):
+                    continue
+                try:
+                    read_bytes += int(parts[5]) * 512
+                    write_bytes += int(parts[9]) * 512
+                except ValueError:
+                    pass
+        return {"readBytes": read_bytes, "writeBytes": write_bytes}
+    except Exception:
+        return None
+
+
+def network_rates():
+    global _last_network
+    cur = _read_net_dev()
+    if not cur:
+        return None
+    if not _last_network:
+        _last_network = {"ts": time.time(), **cur}
+        return None
+    dt = max(1.0, time.time() - _last_network["ts"])
+    out = {
+        "rxBytesPerSec": int(max(0, (cur["rx"] - _last_network["rx"]) / dt)),
+        "txBytesPerSec": int(max(0, (cur["tx"] - _last_network["tx"]) / dt)),
+    }
+    _last_network = {"ts": time.time(), **cur}
+    return out
+
+
+def disk_rates():
+    global _last_disk
+    cur = _read_disk_stats()
+    if not cur:
+        return None
+    if not _last_disk:
+        _last_disk = {"ts": time.time(), **cur}
+        return None
+    dt = max(1.0, time.time() - _last_disk["ts"])
+    out = {
+        "readBytesPerSec": int(max(0, (cur["readBytes"] - _last_disk["readBytes"]) / dt)),
+        "writeBytesPerSec": int(max(0, (cur["writeBytes"] - _last_disk["writeBytes"]) / dt)),
+    }
+    _last_disk = {"ts": time.time(), **cur}
+    return out
+
+
+def collect_host_metrics(options=None):
+    """Collect one round of host metrics as DevLite metric events."""
+    options = options or {}
+    include_disk = options.get("include_disk", True)
+    include_network = options.get("include_network", True)
+    host = socket.gethostname()
+    base = {"type": "metric", "unit": "bytes", "tags": {"host": host}, "timestamp": _now_ms()}
+    metrics = []
+
+    metrics.append({**base, "name": "host.cpu.percent", "value": cpu_percent(), "unit": "percent"})
+
+    mem = memory_snapshot()
+    if mem.get("rss") is not None:
+        metrics.append({**base, "name": "host.memory.rss", "value": mem["rss"]})
+
+    if hasattr(os, "getloadavg"):
+        try:
+            load1, load5, load15 = os.getloadavg()
+            metrics.append({**base, "name": "host.cpu.load1", "value": load1, "unit": "load"})
+            metrics.append({**base, "name": "host.cpu.load5", "value": load5, "unit": "load"})
+            metrics.append({**base, "name": "host.cpu.load15", "value": load15, "unit": "load"})
+        except OSError:
+            pass
+
+    if include_network:
+        net = network_rates()
+        if net:
+            metrics.append({**base, "name": "host.network.rxBytesPerSec", "value": net["rxBytesPerSec"], "unit": "bytes/sec"})
+            metrics.append({**base, "name": "host.network.txBytesPerSec", "value": net["txBytesPerSec"], "unit": "bytes/sec"})
+
+    if include_disk:
+        disk = disk_rates()
+        if disk:
+            metrics.append({**base, "name": "host.disk.readBytesPerSec", "value": disk["readBytesPerSec"], "unit": "bytes/sec"})
+            metrics.append({**base, "name": "host.disk.writeBytesPerSec", "value": disk["writeBytesPerSec"], "unit": "bytes/sec"})
+
+    return metrics

devlite/_queue.py

@@ -0,0 +1,39 @@
+"""Bounded thread-safe FIFO queue for buffered telemetry events."""
+
+from collections import deque
+from threading import Lock
+
+
+class EventQueue:
+    """Simple bounded FIFO queue.
+
+    When full, drops the oldest events first (better to lose old data than
+    crash the host app or grow memory unbounded) — same semantics as the
+    Node SDK's queue.js.
+    """
+
+    def __init__(self, max_queue_size=5000):
+        self.max_queue_size = max_queue_size
+        self._items = deque()
+        self._lock = Lock()
+        self.dropped_count = 0
+
+    def push(self, event):
+        with self._lock:
+            if len(self._items) >= self.max_queue_size:
+                self._items.popleft()
+                self.dropped_count += 1
+            self._items.append(event)
+
+    def drain(self, max_batch_size=None):
+        max_batch_size = max_batch_size if max_batch_size is not None else self.max_queue_size
+        with self._lock:
+            batch = []
+            while self._items and len(batch) < max_batch_size:
+                batch.append(self._items.popleft())
+            return batch
+
+    @property
+    def size(self):
+        with self._lock:
+            return len(self._items)

devlite/_scrub.py

@@ -0,0 +1,74 @@
+"""Sensitive-data scrubbing — a faithful Python port of devlite-sdk's scrub.js.
+
+Automatically redacts common sensitive patterns from any string field before
+it is sent off-host. Runs on every event regardless of config as a safety
+net. Deliberately conservative: better to over-redact than leak a credential
+into a third-party dashboard.
+"""
+
+import re
+
+PATTERNS = [
+    ("email", re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+"), "[REDACTED_EMAIL]"),
+    ("credit_card", re.compile(r"\b(?:\d[ -]*?){13,16}\b"), "[REDACTED_CC]"),
+    ("jwt", re.compile(r"eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"), "[REDACTED_JWT]"),
+    (
+        "api_key_assignment",
+        re.compile(r"(api[_-]?key|secret|token|password)\s*[:=]\s*['\"]?[\w\-\.]{8,}['\"]?", re.I),
+        r"\1=[REDACTED]",
+    ),
+    ("bearer_token", re.compile(r"Bearer\s+[\w\-\.]+", re.I), "Bearer [REDACTED]"),
+    ("aws_key", re.compile(r"AKIA[0-9A-Z]{16}"), "[REDACTED_AWS_KEY]"),
+]
+
+SENSITIVE_KEY_NAMES = {
+    "password",
+    "pass",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "authorization",
+    "cookie",
+    "ssn",
+    "creditcard",
+    "credit_card",
+}
+
+_MAX_DEPTH = 8
+
+
+def scrub_string(value):
+    if not isinstance(value, str) or not value:
+        return value
+    for _, regex, replacement in PATTERNS:
+        value = regex.sub(replacement, value)
+    return value
+
+
+def _is_sensitive_key(key):
+    normalized = re.sub(r"[^a-z]", "", str(key).lower())
+    return normalized in SENSITIVE_KEY_NAMES
+
+
+def scrub_deep(value, depth=0):
+    """Recursively scrub strings and fully redact sensitive-keyed values."""
+    if depth > _MAX_DEPTH:
+        return value
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value
+    if isinstance(value, str):
+        return scrub_string(value)
+    if isinstance(value, (list, tuple, set)):
+        return [scrub_deep(v, depth + 1) for v in value]
+    if isinstance(value, dict):
+        out = {}
+        for key, val in value.items():
+            out[key] = "[REDACTED]" if _is_sensitive_key(key) else scrub_deep(val, depth + 1)
+        return out
+    # Fallback for non-JSON types (datetimes, objects, ...) — keep safe, plain.
+    return str(value)

devlite/_transport.py

@@ -0,0 +1,144 @@
+"""Batch transport with retry/backoff and gzip — Python port of transport.js.
+
+Uses only the standard library (urllib), so the SDK has zero runtime
+dependencies. Batches events into {apiKey, service, environment, release,
+events[]} payloads and POSTs them to the DevLite ingest endpoint exactly
+like the Node SDK.
+"""
+
+import gzip
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+
+from ._queue import EventQueue
+
+COHERENT_SAMPLED_TYPES = {
+    "request",
+    "slow_request",
+    "error",
+    "message",
+    "metric",
+    "log",
+    "span",
+}
+
+
+def _json_default(obj):
+    return str(obj)
+
+
+class Transport:
+    def __init__(self, config):
+        self.config = config
+        self.queue = EventQueue(max_queue_size=config.get("max_queue_size", 5000))
+        self._lock = threading.Lock()
+        self._closed = False
+        self._flusher = None
+
+        if config.get("flush_interval_ms", 5000) > 0:
+            self._flusher = threading.Thread(
+                target=self._flusher_loop, daemon=True, name="devlite-transport"
+            )
+            self._flusher.start()
+
+    # --- public -----------------------------------------------------------
+
+    def enqueue(self, event):
+        if self._closed:
+            return
+        if event.get("type") in COHERENT_SAMPLED_TYPES:
+            from ._context import is_sampled_out
+
+            if is_sampled_out():
+                return
+        self.queue.push(event)
+        if self.queue.size >= self.config.get("max_batch_size", 100):
+            self.flush()
+
+    def flush(self):
+        if self._closed:
+            return
+        batch = self.queue.drain(self.config.get("max_batch_size", 100))
+        if not batch:
+            return
+        self._send_with_retry(batch)
+
+    def close(self):
+        self._closed = True
+        self.flush()
+
+    def _flusher_loop(self):
+        interval = self.config.get("flush_interval_ms", 5000) / 1000.0
+        while not self._closed:
+            time.sleep(interval)
+            try:
+                self.flush()
+            except Exception:
+                # never let background delivery kill the host process
+                pass
+
+    # --- internals --------------------------------------------------------
+
+    def _payload(self, batch):
+        return {
+            "apiKey": self.config["api_key"],
+            "service": self.config.get("service_name"),
+            "environment": self.config.get("environment"),
+            "release": self.config.get("release"),
+            "events": batch,
+        }
+
+    def _send_with_retry(self, batch, attempt=1):
+        try:
+            self._send(batch)
+        except Exception as err:  # noqa: BLE001
+            if attempt < self.config.get("max_retries", 3):
+                delay = self.config.get("retry_base_delay_ms", 500) * (2 ** (attempt - 1)) / 1000.0
+                time.sleep(delay)
+                self._send_with_retry(batch, attempt + 1)
+                return
+            self._handle_error(err, batch)
+
+    def _send(self, batch):
+        body = json.dumps(self._payload(batch), default=_json_default).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": self.config.get("user_agent", "devlite-python/0.1.0"),
+        }
+
+        # Marks this request as the SDK's own delivery so an instrumented
+        # ingest server never records it as app telemetry (feedback loop).
+        headers["X-DevLite-Transport"] = "1"
+
+        if self.config.get("gzip", True):
+            body = gzip.compress(body)
+            headers["Content-Encoding"] = "gzip"
+
+        req = urllib.request.Request(
+            self.config.get("endpoint"),
+            data=body,
+            headers=headers,
+            method="POST",
+        )
+        timeout = self.config.get("request_timeout_ms", 10000) / 1000.0
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            if resp.status >= 400:
+                raise RuntimeError("DevLite ingest responded with status {}".format(resp.status))
+
+    def _handle_error(self, err, batch):
+        if self.config.get("debug"):
+            print(
+                "[DevLite] failed to send {} event(s) after {} attempts: {}".format(
+                    len(batch), self.config.get("max_retries", 3), err
+                )
+            )
+        on_error = self.config.get("on_error")
+        if callable(on_error):
+            try:
+                on_error(err)
+            except Exception:
+                # never let a user callback crash the SDK
+                pass

devlite-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: devlite
+Version: 0.1.0
+Summary: DevLite Python SDK — AI-powered observability with a 2-line integration. Automatic error grouping, source context, user impact tracking, and sensitive-data scrubbing built in.
+License: MIT
+Project-URL: Homepage, https://devlite.io
+Project-URL: Repository, https://github.com/Ishimwe-Kevin/devlite-app
+Keywords: observability,monitoring,apm,error-tracking,error-monitoring,logging,ai,devlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# devlite — Python SDK
+
+AI-powered observability for Python. Add two lines, get automatic request tracking, error capture, error grouping, source context, user tracking, and slow-endpoint detection — no config files, no manual instrumentation, **zero runtime dependencies**.
+
+This is the Python counterpart of [`@devlite/nodejs`](https://www.npmjs.com/package/@devlite/nodejs) — both SDKs speak the same batch protocol to the [DevLite ingest API](https://github.com/Ishimwe-Kevin/devlite-app).
+
+## Install
+
+```bash
+pip install devlite            # core (Flask optional)
+pip install "devlite[flask]"   # + Flask instrumentation
+```
+
+## 60-second quickstart (Flask)
+
+```python
+from flask import Flask
+import devlite
+
+devlite.init(api_key="dl_live_xxxxx")
+
+app = Flask(__name__)
+devlite.instrument_flask(app)
+```
+
+That's it — every HTTP request, slow endpoint, and unhandled exception is now captured automatically, with:
+
+- **Grouped errors** — the same bug occurring 1,000 times shows up as one issue, not 1,000
+- **Real source code context** — the actual lines around the crash, read live from disk
+- **Automatic sensitive-data scrubbing** — emails, tokens, passwords redacted before anything leaves your process
+- **User impact tracking** — know exactly which users hit which bugs
+
+Point `api_key`/`endpoint` at your own DevLite ingest instance (Supabase-backed) to start seeing data.
+
+## Manual capture API
+
+```python
+# Capture a handled error with extra context
+devlite.capture_error(err, {"userId": "123", "action": "checkout"})
+devlite.capture_error(err, {"fingerprint": "payment-timeout"})  # force grouping key
+
+# Non-error event
+devlite.capture_message("Payment retried after timeout", "warning")
+
+# Custom metric — feeds forecasting/anomaly detection
+devlite.report_metric("order.total", 42.5, unit="USD", tags={"region": "lagos"})
+
+# Structured log line
+devlite.capture_log("checkout completed", "info", {"orderId": "ord_123", "durationMs": 250})
+
+# Trace a unit of work
+span = devlite.start_span("checkout.process", {"trace_id": "abc"})
+span.end("ok")  # "ok" | "error"
+
+# Tell DevLite about a deployment (powers before/after performance views)
+devlite.report_deployment(version="v2.1.3", commit_sha="a1b2c3d")
+
+# Breadcrumbs attach to the next captured error, improving AI root-cause
+devlite.add_breadcrumb({"type": "business_event", "note": "user started checkout"})
+
+# Tag all subsequent events
+devlite.set_tag("region", "lagos")
+```
+
+## User impact tracking
+
+`set_user()` is scoped to the current request (via `contextvars`, so concurrent requests never leak each other's identity):
+
+```python
+from flask import request
+
+@app.before_request
+def identify():
+    devlite.set_user({"id": request.remote_addr, "email": request.headers.get("X-User-Email")})
+```
+
+## Configuration options
+
+```python
+devlite.init({
+    "api_key": "dl_live_xxxxx",        # required
+    "environment": "production",        # default: $DEVLITE_ENVIRONMENT or "development"
+    "service_name": "payments-api",     # default: $DEVLITE_SERVICE_NAME or current folder
+    "release": "v2.1.3",                # e.g. git sha, shown in deployment views
+    "sample_rate": 1.0,                 # 0.0–1.0. Sampling is COHERENT: a sampled-out
+                                        # request drops its errors/spans/logs/metrics together.
+    "capture_body": False,              # capture (redacted) request headers — off by default
+    "flush_interval_ms": 5000,          # how often batched events are sent
+    "gzip": True,                       # compress request bodies (Content-Encoding: gzip)
+    "debug": False,                     # log SDK internals
+    "on_error": lambda err: print(err), # SDK-internal send failures
+})
+```
+
+All of `api_key`, `service_name`, `release`, and `endpoint` can also be set via environment variables (`DEVLITE_API_KEY`, `DEVLITE_SERVICE_NAME`, `DEVLITE_RELEASE`, `DEVLITE_ENDPOINT`).
+
+## Serverless / short-lived processes
+
+Events are batched, so call `flush()` before your function returns:
+
+```python
+devlite.flush()
+```
+
+## Graceful shutdown
+
+The SDK flushes remaining events on interpreter exit (`atexit`). If you manage shutdown yourself:
+
+```python
+devlite.close()
+```
+
+## What makes this competitive
+
+- **Automatic error grouping** — the same underlying bug, however many times it fires, is fingerprinted and grouped into one issue, instead of flooding your dashboard with duplicates.
+- **Source code context** — every captured error includes the actual lines of code around the crash, read live from disk, not just a bare stack trace.
+- **Automatic sensitive-data scrubbing** — on by default. Emails, JWTs, bearer tokens, AWS keys, credit card numbers, and any field literally named `password`/`token`/`secret` are redacted before anything leaves your process.
+- **Never blocks your app** — all sends are async (background thread), batched, and retried with backoff. If DevLite's backend is unreachable, your app keeps running.
+- **Zero dependencies** — pure Python standard library.
+
+## Development
+
+```bash
+pip install -e ".[flask,test]"
+python -m pytest
+```
+
+## License
+
+MIT

devlite-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+devlite/__init__.py,sha256=0zRVYTY5Yx1V6TUfO4jJxX_76tbUFT2WFOwx_qqWm6w,4423
+devlite/_client.py,sha256=Z5i6IlANy2-cympISwvINjCmOSj0qnNRrYJWXcWv8EA,6230
+devlite/_config.py,sha256=VCE_TLB-74EqahTkHFrAk8GxpGMxykl5vkiqbPc9C0s,2362
+devlite/_context.py,sha256=ynGlqODptyP7wo6NpzZsmOQNeOqbUlaT0C4NyWCDTO0,1974
+devlite/_errors.py,sha256=MzF0S0ifCUHOBxFRvcoYT6msPXtTj_3RtmUVt9M9phI,3681
+devlite/_flask.py,sha256=gWTcVmlDxrpbLzxiP6s3rO0kJimYnRnGK2nWIuKTa50,3849
+devlite/_metrics.py,sha256=XI-deM9JgIdrnNQs_T1XgDjNCXTGsHJqB9eW4uvCnCQ,7224
+devlite/_queue.py,sha256=TAdWvUadmHvsgdtVcbK4lDBZLjTUkfSjJnyZ0grFsfE,1191
+devlite/_scrub.py,sha256=NjNS1N5hILZ8wv35caoHUjCNZnQ0-_0PykWlg5KvjoQ,2281
+devlite/_transport.py,sha256=6V_C49WJlgcKGExX6uyr06t20XnHerDgEqpPwy7eKFU,4576
+devlite-0.1.0.dist-info/licenses/LICENSE,sha256=YEYgiCxTHR-xVnbS1--3YalDzZpmrPRFBGHFaDX6AGg,1068
+devlite-0.1.0.dist-info/METADATA,sha256=nbwCiAHxZnrmMlLwEe4mEc3kT_7nv1jYcx-bco0AwdU,6308
+devlite-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+devlite-0.1.0.dist-info/top_level.txt,sha256=w8bsDCX1j10mIkzzqMTjZb_vcu_ZNAyegLnv9N1Pe4Y,8
+devlite-0.1.0.dist-info/RECORD,,

devlite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devlite-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishvexa Hub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devlite-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devlite