loggerai-sdk 0.1.0__py3-none-any.whl

loggerai/__init__.py

@@ -0,0 +1,122 @@
+"""
+LoggerAI for Python: performance monitoring, errors, logs and health checks
+for FastAPI, Starlette, Django, Flask and Celery.
+
+    import loggerai
+    loggerai.init()                      # reads LOGGERAI_KEY (sk_live_...)
+
+    # FastAPI / Starlette
+    from loggerai.asgi import LoggerAIMiddleware
+    app.add_middleware(LoggerAIMiddleware)
+
+Nothing is sent without a key, nothing ever raises into your app, and
+secrets are masked before anything leaves it.
+"""
+from __future__ import annotations
+
+import contextlib
+import time
+from typing import Any, Callable, Dict, Iterator, Optional
+
+from . import context
+from ._version import __version__
+from .client import Client, get_client, set_client
+
+__all__ = ["init", "capture_exception", "set_user", "set_route", "measure", "track", "flush", "health_checks", "Client", "__version__"]
+
+
+def init(key: Optional[str] = None, **options: Any) -> Client:
+    """Start LoggerAI. Every option also has an environment variable:
+    key (LOGGERAI_KEY), endpoint, service, environment, release, enabled.
+    Others: logs_level ("WARNING", or None for no logs), capture_queries,
+    capture_http, capture_redis, ignore_paths, health_checks={"database": fn},
+    flush_interval (seconds), timeout, root (the app's folder, for stack traces)."""
+    old = get_client()
+    if old is not None:
+        old.close(timeout=1.0)
+    client = Client(key, **options)
+    set_client(client)
+    if client.enabled:
+        from . import instrument
+        instrument.all_from(client)
+        if client.health_checks:
+            client.start()
+    return client
+
+
+def capture_exception(exc: Optional[BaseException] = None, **extra: Any) -> None:
+    """Report an exception you handled but still want to see."""
+    import sys
+    exc = exc or sys.exc_info()[1]
+    client = get_client()
+    if exc is not None and client is not None:
+        client.exception(exc, handled=True, extra=extra or None)
+
+
+def set_user(user_id: Any) -> None:
+    """Count the current request against a user. Only a one-way hash of the id is sent."""
+    unit, client = context.current.get(), get_client()
+    if unit is not None and client is not None:
+        unit.user = client.user_ref(user_id)
+
+
+def set_route(template: str) -> None:
+    """Name the current request yourself (a template like /orders/{id}, never a raw path)."""
+    unit = context.current.get()
+    if unit is not None:
+        unit.route = template
+
+
+@contextlib.contextmanager
+def measure(target: str, operation: str = "CALL") -> Iterator[None]:
+    """Time a call LoggerAI can't see on its own, e.g. an SDK with its own HTTP client:
+
+        with loggerai.measure("api.stripe.com", "POST"):
+            stripe.PaymentIntent.confirm(...)
+    """
+    t = time.perf_counter()
+    ok = False
+    try:
+        yield
+        ok = True
+    finally:
+        context.dependency(target, operation, (time.perf_counter() - t) * 1000, ok)
+
+
+@contextlib.contextmanager
+def track(kind: str, name: str) -> Iterator[context.Unit]:
+    """Time a unit of work outside a web request: a job, a scheduled task, a script.
+
+        with loggerai.track("job", "send_invoices"):
+            ...
+    """
+    client = get_client()
+    unit = context.Unit(kind if kind in ("job", "command", "http") else "job", "JOB" if kind != "command" else "CLI")
+    unit.route = name
+    token = context.current.set(unit)
+    status = 200
+    try:
+        yield unit
+    except Exception as e:
+        status = 500
+        if client is not None:
+            client.exception(e, status=500)
+        raise
+    finally:
+        context.current.reset(token)
+        if client is not None:
+            client.finish(unit, status)
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Send everything now (e.g. at the end of a script or a serverless call)."""
+    client = get_client()
+    return client.flush(timeout) if client is not None else True
+
+
+def health_checks(checks: Dict[str, Callable[[], Any]]) -> None:
+    """Add health checks after init: each returns True/False, or (ok, detail)."""
+    client = get_client()
+    if client is not None:
+        client.health_checks.update(checks)
+        client.start()

loggerai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

loggerai/asgi.py

@@ -0,0 +1,60 @@
+"""ASGI middleware: FastAPI, Starlette, and any ASGI app.
+
+    from loggerai.asgi import LoggerAIMiddleware
+    app.add_middleware(LoggerAIMiddleware)
+"""
+from __future__ import annotations
+
+from . import context
+from .client import get_client
+
+
+def _route(scope) -> str | None:
+    route = scope.get("route")
+    if route is not None:
+        path = getattr(route, "path_format", None) or getattr(route, "path", None)
+        if path:
+            # Routes inside a mounted sub-app are relative to the mount.
+            mount = scope.get("app_root_path") or ""
+            return (mount.rstrip("/") + path) if mount and not path.startswith(mount) else path
+    endpoint = scope.get("endpoint")
+    app = scope.get("app")
+    if endpoint is not None and app is not None:  # older Starlette: find the route by its endpoint
+        for r in getattr(app, "routes", []) or []:
+            if getattr(r, "endpoint", None) is endpoint:
+                return getattr(r, "path_format", None) or getattr(r, "path", None)
+    return None
+
+
+class LoggerAIMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        client = get_client()
+        if scope["type"] != "http" or client is None or not client.enabled or client.ignored(scope.get("path", "")):
+            return await self.app(scope, receive, send)
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers") or []}
+        unit = context.Unit("http", scope.get("method", "GET"), context.trace_from(headers.get("traceparent")),
+                            context.session_from(headers.get("x-loggerai-session")))
+        token = context.current.set(unit)
+        status = 500
+
+        async def _send(message):
+            nonlocal status
+            if message["type"] == "http.response.start":
+                status = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, _send)
+        except BaseException as e:
+            unit.route = unit.route or _route(scope)
+            if isinstance(e, Exception):
+                client.exception(e, status=500)
+            status = 500
+            raise
+        finally:
+            unit.route = unit.route or _route(scope)
+            context.current.reset(token)
+            client.finish(unit, status)

loggerai/celery.py

@@ -0,0 +1,44 @@
+"""Celery: every task timed like a request (kind "job"), failures reported.
+
+    import loggerai, loggerai.celery
+    loggerai.init()
+    loggerai.celery.instrument()
+"""
+from __future__ import annotations
+
+from . import context
+from .client import get_client
+
+_tokens = {}
+
+
+def instrument() -> None:
+    from celery import signals
+
+    @signals.task_prerun.connect(weak=False)
+    def _start(task_id=None, task=None, **kw):
+        client = get_client()
+        if client is None or not client.enabled:
+            return
+        unit = context.Unit("job", "JOB")
+        unit.route = getattr(task, "name", None) or "task"
+        _tokens[task_id] = (unit, context.current.set(unit))
+
+    @signals.task_failure.connect(weak=False)
+    def _failed(task_id=None, exception=None, **kw):
+        client = get_client()
+        if client is not None and exception is not None:
+            client.exception(exception, status=500)
+
+    @signals.task_postrun.connect(weak=False)
+    def _end(task_id=None, state=None, **kw):
+        got = _tokens.pop(task_id, None)
+        client = get_client()
+        if got is None or client is None:
+            return
+        unit, token = got
+        try:
+            context.current.reset(token)
+        except ValueError:
+            context.current.set(None)
+        client.finish(unit, 200 if state == "SUCCESS" else 500)

loggerai/client.py

@@ -0,0 +1,284 @@
+"""
+The client: settings, the buffer, and a background thread that sends batches
+to LoggerAI every few seconds. Nothing here ever raises into the app or makes
+a request wait; when LoggerAI can't be reached, records are dropped rather
+than piling up.
+"""
+from __future__ import annotations
+
+import atexit
+import gzip
+import hashlib
+import hmac
+import json
+import logging
+import os
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Callable, Dict, List, Optional
+
+from . import context
+from ._version import __version__
+from .frames import frames, type_name
+from .redact import redact, redact_string
+
+log = logging.getLogger("loggerai")
+
+DEFAULT_ENDPOINT = "https://loggerapp.ehigiator.com/api/v1/ingest/batch"
+KINDS = ("requests", "errors", "logs", "checks")
+MAX_BUFFER = 10_000          # per kind; beyond this the oldest go
+MAX_PER_BATCH = 1_000        # the server's limit per kind
+MAX_BATCH_BYTES = 900_000    # under the server's 1 MB
+
+
+def _env(name: str, default: Optional[str] = None) -> Optional[str]:
+    v = os.environ.get(name)
+    return v if v not in (None, "") else default
+
+
+def _truthy(v) -> bool:
+    return str(v).strip().lower() not in ("0", "false", "no", "off", "")
+
+
+class Client:
+    def __init__(
+        self,
+        key: Optional[str] = None,
+        *,
+        endpoint: Optional[str] = None,
+        service: Optional[str] = None,
+        environment: Optional[str] = None,
+        release: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        flush_interval: float = 5.0,
+        timeout: float = 2.0,
+        logs_level: Optional[str] = "WARNING",
+        capture_queries: bool = True,
+        capture_http: bool = True,
+        capture_redis: bool = True,
+        ignore_paths: tuple = ("/health", "/healthz", "/up", "/favicon.ico", "/metrics"),
+        health_checks: Optional[Dict[str, Callable]] = None,
+        health_interval: float = 60.0,
+        root: Optional[str] = None,
+    ):
+        self.key = key or _env("LOGGERAI_KEY")
+        self.endpoint = endpoint or _env("LOGGERAI_ENDPOINT", DEFAULT_ENDPOINT)
+        self.service = service or _env("LOGGERAI_SERVICE", "app")
+        self.environment = environment or _env("LOGGERAI_ENVIRONMENT") or _env("ENVIRONMENT") or _env("APP_ENV") or "production"
+        self.release = release or _env("LOGGERAI_RELEASE")
+        on = _truthy(_env("LOGGERAI_ENABLED", "true")) if enabled is None else enabled
+        self.enabled = bool(on and self.key and self.key.startswith("sk_"))
+        if on and self.key and not self.key.startswith("sk_"):
+            log.warning("LoggerAI: servers need the secret key (sk_live_...); the public key is for browsers. Not sending.")
+        self.flush_interval = max(1.0, float(flush_interval))
+        self.timeout = timeout
+        self.logs_level = logs_level
+        self.capture_queries, self.capture_http, self.capture_redis = capture_queries, capture_http, capture_redis
+        self.ignore_paths = tuple(ignore_paths or ())
+        self.health_checks = dict(health_checks or {})
+        self.health_interval = health_interval
+        self.root = os.path.abspath(root or os.getcwd())
+        self.host = socket.gethostname()
+
+        self._lock = threading.Lock()
+        self._buf: Dict[str, List[dict]] = {k: [] for k in KINDS}
+        self._wake = threading.Event()
+        self._idle = threading.Event()
+        self._idle.set()
+        self._thread: Optional[threading.Thread] = None
+        self._pid = os.getpid()
+        self._stopped = False
+        self._next_health = 0.0
+        self.last_error: Optional[str] = None
+
+    # ---- recording ------------------------------------------------------------------
+
+    def ignored(self, path: str) -> bool:
+        return any(path == p or path.startswith(p.rstrip("/") + "/") for p in self.ignore_paths)
+
+    def add(self, kind: str, record: dict) -> None:
+        if not self.enabled:
+            return
+        with self._lock:
+            buf = self._buf[kind]
+            buf.append(record)
+            if len(buf) > MAX_BUFFER:
+                del buf[: len(buf) - MAX_BUFFER]
+        self._ensure_thread()
+
+    def finish(self, unit: context.Unit, status: int) -> None:
+        self.add("requests", unit.record(status))
+
+    def exception(self, exc: BaseException, status: Optional[int] = None, handled: bool = False, extra: Optional[dict] = None) -> None:
+        if not self.enabled or getattr(exc, "__loggerai_seen__", False):
+            return
+        try:
+            exc.__loggerai_seen__ = True  # reported once, however many layers see it
+        except Exception:
+            pass
+        unit = context.current.get()
+        self.add("errors", {
+            "ts": round(time.time(), 3),
+            "type": type_name(exc),
+            "message": redact_string(str(exc)[:1000]),
+            "handled": handled,
+            "route": unit.route if unit else None,
+            "method": unit.method if unit else None,
+            "status": status,
+            "trace_id": unit.trace_id if unit else None,
+            "frames": frames(exc, self.root),
+            "context": redact(extra) if extra else {},
+        })
+
+    def log(self, level: str, logger: str, message: str) -> None:
+        unit = context.current.get()
+        self.add("logs", {
+            "ts": round(time.time(), 3), "level": level, "logger": logger[:120], "message": redact_string(message[:8000]),
+            "route": unit.route if unit else None, "trace_id": unit.trace_id if unit else None,
+        })
+
+    def user_ref(self, user_id) -> Optional[str]:
+        """An opaque, stable id for a user: never the id itself, never an email."""
+        if user_id in (None, ""):
+            return None
+        return hmac.new((self.key or "").encode(), str(user_id).encode(), hashlib.sha256).hexdigest()[:16]
+
+    # ---- sending ---------------------------------------------------------------------
+
+    def _ensure_thread(self) -> None:
+        if self._pid != os.getpid():  # forked (gunicorn, uWSGI, Celery): the parent's thread didn't come along
+            self._pid = os.getpid()
+            self._thread = None
+            with self._lock:
+                self._buf = {k: [] for k in KINDS}
+        if self._thread is None and not self._stopped:
+            self._thread = threading.Thread(target=self._run, name="loggerai", daemon=True)
+            self._thread.start()
+
+    def start(self) -> None:
+        """Starts the sender now (for health checks on a quiet app)."""
+        if self.enabled:
+            self._ensure_thread()
+
+    def _run(self) -> None:
+        while not self._stopped:
+            self._wake.wait(self.flush_interval)
+            self._wake.clear()
+            self._idle.clear()
+            try:
+                self._run_health()
+                self._send_all()
+            except Exception as e:  # never let the thread die
+                log.debug("LoggerAI: send failed: %s", e)
+            finally:
+                self._idle.set()
+
+    def _run_health(self) -> None:
+        if not self.health_checks or time.monotonic() < self._next_health:
+            return
+        self._next_health = time.monotonic() + self.health_interval
+        for name, fn in self.health_checks.items():
+            t = time.perf_counter()
+            try:
+                r = fn()
+                ok, detail = (r if isinstance(r, tuple) else (r is not False, None))
+            except Exception as e:
+                ok, detail = False, f"{type(e).__name__}: {e}"[:255]
+            self.add("checks", {"ts": round(time.time(), 3), "name": name, "ok": bool(ok),
+                                "ms": round((time.perf_counter() - t) * 1000, 2), "detail": detail})
+
+    def _drain(self) -> Dict[str, List[dict]]:
+        with self._lock:
+            out = {k: v[:MAX_PER_BATCH] for k, v in self._buf.items() if v}
+            for k in out:
+                del self._buf[k][: len(out[k])]
+        return out
+
+    def _send_all(self) -> None:
+        for _ in range(20):  # a burst goes out in several batches, then waits for the next tick
+            parts = self._drain()
+            if not parts or not self.enabled:
+                return
+            self._post(parts)
+
+    def _post(self, parts: Dict[str, List[dict]]) -> None:
+        body = json.dumps({
+            "sdk": {"name": "loggerai-python", "version": __version__},
+            "service": self.service, "environment": self.environment, "release": self.release, "host": self.host,
+            **parts,
+        }, separators=(",", ":"), default=str).encode()
+        if len(body) > MAX_BATCH_BYTES and sum(len(v) for v in parts.values()) > 1:
+            for half in _halves(parts):
+                self._post(half)
+            return
+        req = urllib.request.Request(self.endpoint, data=gzip.compress(body), method="POST", headers={
+            "Content-Type": "application/json", "Content-Encoding": "gzip", "X-LoggerAI-Key": self.key or "",
+            "User-Agent": f"loggerai-python/{__version__}"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                r.read()
+            self.last_error = None
+        except urllib.error.HTTPError as e:
+            self.last_error = f"LoggerAI answered {e.code}"
+            if e.code == 401:
+                self.enabled = False  # a wrong or revoked key won't start working by retrying
+                log.warning("LoggerAI: the key was refused (401). Check LOGGERAI_KEY; sending stopped.")
+            elif e.code not in (429,) and e.code < 500:
+                log.warning("LoggerAI: batch rejected (%s)", e.code)
+        except Exception as e:
+            self.last_error = f"couldn't reach LoggerAI: {type(e).__name__}"
+            log.debug("LoggerAI: %s", self.last_error)
+
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Sends everything recorded so far. True when the buffer is empty."""
+        if not self.enabled:
+            return True
+        if self._thread is None or self._pid != os.getpid():
+            self._send_all()  # no sender thread here (e.g. a short script): send in this thread
+            return not any(self._buf.values())
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            self._idle.wait(max(0.0, deadline - time.monotonic()))
+            if not any(self._buf.values()):
+                return True
+            self._wake.set()
+            time.sleep(0.05)
+            self._idle.wait(max(0.0, deadline - time.monotonic()))
+        return not any(self._buf.values())
+
+    def close(self, timeout: float = 2.0) -> None:
+        self.flush(timeout)
+        self._stopped = True
+        self._wake.set()
+
+
+def _halves(parts: Dict[str, List[dict]]):
+    a, b = {}, {}
+    for k, v in parts.items():
+        mid = len(v) // 2
+        if v[:mid]:
+            a[k] = v[:mid]
+        if v[mid:]:
+            b[k] = v[mid:]
+    return [x for x in (a, b) if x]
+
+
+_client: Optional[Client] = None
+
+
+def get_client() -> Optional[Client]:
+    return _client
+
+
+def set_client(c: Optional[Client]) -> None:
+    global _client
+    _client = c
+
+
+@atexit.register
+def _at_exit() -> None:
+    if _client is not None:
+        _client.close(timeout=2.0)

loggerai/context.py

@@ -0,0 +1,79 @@
+"""The unit of work in progress (an HTTP request, a job, a command): what it
+waited on, grouped by target and operation, until it finishes.
+
+Kept in a ContextVar, so it follows the request into async code and into the
+thread pools frameworks run sync code in."""
+from __future__ import annotations
+
+import os
+import re
+import time
+from contextvars import ContextVar
+from typing import Dict, Optional
+
+_TRACEPARENT = re.compile(r"^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$")
+
+
+class Unit:
+    __slots__ = ("kind", "method", "route", "trace_id", "session_id", "user", "ts", "started", "deps")
+
+    def __init__(self, kind: str, method: str, trace_id: Optional[str] = None, session_id: Optional[str] = None):
+        self.kind = kind
+        self.method = method
+        self.route: Optional[str] = None
+        self.trace_id = trace_id or os.urandom(16).hex()
+        self.session_id = session_id
+        self.user: Optional[str] = None
+        self.ts = time.time()
+        self.started = time.perf_counter()
+        self.deps: Dict[tuple, list] = {}
+
+    def dep(self, target: str, op: str, ms: float, ok: bool = True) -> None:
+        d = self.deps.get((target, op))
+        if d is None:
+            d = self.deps[(target, op)] = [0, 0.0, 0]
+        d[0] += 1
+        d[1] += ms
+        if not ok:
+            d[2] += 1
+
+    def record(self, status: int) -> dict:
+        return {
+            "ts": round(self.ts, 3),
+            "kind": self.kind,
+            "method": self.method,
+            "route": self.route or "(unmatched)",
+            "status": int(status),
+            "duration_ms": round((time.perf_counter() - self.started) * 1000, 2),
+            "trace_id": self.trace_id,
+            "session_id": self.session_id,
+            "user": self.user,
+            "deps": [{"target": t, "op": o, "count": c, "ms": round(ms, 2), "errors": e} for (t, o), (c, ms, e) in self.deps.items()],
+        }
+
+
+current: ContextVar[Optional[Unit]] = ContextVar("loggerai_unit", default=None)
+
+
+def trace_from(traceparent: Optional[str]) -> Optional[str]:
+    """The trace id from a W3C traceparent header, if it's well formed."""
+    m = _TRACEPARENT.match((traceparent or "").strip().lower())
+    return m.group(1) if m and m.group(1) != "0" * 32 else None
+
+
+def session_from(value: Optional[str]) -> Optional[str]:
+    v = (value or "").strip()
+    return v[:64] if v and re.fullmatch(r"[A-Za-z0-9._:-]+", v) else None
+
+
+def dependency(target: str, op: str, ms: float, ok: bool = True) -> None:
+    """Record a call made during the current unit (ignored outside one)."""
+    unit = current.get()
+    if unit is not None:
+        unit.dep(target, op[:20], ms, ok)
+
+
+def sql_verb(sql: str) -> str:
+    for word in (sql or "").lstrip(" (\n\t").split(None, 1)[:1]:
+        return word.upper()[:20]
+    return "?"

loggerai/django.py

@@ -0,0 +1,102 @@
+"""Django: call loggerai.init() in settings.py (it reads LOGGERAI_KEY), and add
+the middleware first in MIDDLEWARE:
+
+    MIDDLEWARE = ["loggerai.django.LoggerAIMiddleware", ...]
+
+Queries are timed through Django's own database layer."""
+from __future__ import annotations
+
+import re
+import time
+
+from . import context
+from .client import get_client
+
+_CONVERTER = re.compile(r"<(?:[^:<>]+:)?([^<>]+)>")
+_NAMED = re.compile(r"\(\?P<([^>]+)>[^)]*\)")
+_VENDORS = {"postgresql": "postgres", "microsoft": "sqlserver"}
+
+
+def route_template(resolver_match) -> str | None:
+    route = getattr(resolver_match, "route", None)
+    if route is None:
+        return None
+    if route.startswith("^") or route.endswith("$"):  # re_path
+        route = _NAMED.sub(r"{\1}", route.lstrip("^").rstrip("$"))
+    return "/" + _CONVERTER.sub(r"{\1}", route).lstrip("/")
+
+
+def _db_wrapper(execute, sql, params, many, ctx):
+    if context.current.get() is None:
+        return execute(sql, params, many, ctx)
+    t = time.perf_counter()
+    ok = False
+    try:
+        r = execute(sql, params, many, ctx)
+        ok = True
+        return r
+    finally:
+        vendor = ctx["connection"].vendor
+        context.dependency(_VENDORS.get(vendor, vendor), context.sql_verb(sql), (time.perf_counter() - t) * 1000, ok)
+
+
+def _install_db_timing():
+    from django.db.backends.signals import connection_created
+
+    def _on_connect(sender, connection, **kw):
+        if _db_wrapper not in connection.execute_wrappers:
+            connection.execute_wrappers.append(_db_wrapper)
+
+    connection_created.connect(_on_connect, weak=False, dispatch_uid="loggerai")
+    from django.db import connections
+    for conn in connections.all(initialized_only=True) if _has_initialized_only() else []:
+        _on_connect(None, conn)
+
+
+def _has_initialized_only() -> bool:
+    import inspect
+    from django.db import connections
+    return "initialized_only" in inspect.signature(connections.all).parameters
+
+
+class LoggerAIMiddleware:
+    sync_capable = True
+    async_capable = False
+
+    _db_done = False
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        client = get_client()
+        if client is not None and client.capture_queries and not LoggerAIMiddleware._db_done:
+            LoggerAIMiddleware._db_done = True
+            _install_db_timing()
+
+    def __call__(self, request):
+        client = get_client()
+        if client is None or not client.enabled or client.ignored(request.path):
+            return self.get_response(request)
+        unit = context.Unit("http", request.method, context.trace_from(request.META.get("HTTP_TRACEPARENT")),
+                            context.session_from(request.META.get("HTTP_X_LOGGERAI_SESSION")))
+        token = context.current.set(unit)
+        status = 500
+        try:
+            response = self.get_response(request)
+            status = response.status_code
+            return response
+        finally:
+            unit.route = route_template(getattr(request, "resolver_match", None)) or unit.route
+            user = getattr(request, "user", None)
+            if user is not None and getattr(user, "is_authenticated", False):
+                unit.user = client.user_ref(getattr(user, "pk", None))
+            context.current.reset(token)
+            client.finish(unit, status)
+
+    def process_exception(self, request, exception):
+        client = get_client()
+        if client is not None:
+            unit = context.current.get()
+            if unit is not None and unit.route is None:
+                unit.route = route_template(getattr(request, "resolver_match", None))
+            client.exception(exception, status=500)
+        return None

loggerai/flask.py

@@ -0,0 +1,42 @@
+"""Flask:
+
+    import loggerai, loggerai.flask
+    loggerai.init()
+    loggerai.flask.instrument(app)
+"""
+from __future__ import annotations
+
+import re
+
+from . import context
+from .client import get_client
+from .wsgi import LoggerAIMiddleware
+
+_CONVERTER = re.compile(r"<(?:[^:<>]+:)?([^<>]+)>")
+
+
+def route_template(rule: str) -> str:
+    """'/orders/<int:order_id>' -> '/orders/{order_id}'"""
+    return _CONVERTER.sub(r"{\1}", rule)
+
+
+def instrument(app) -> None:
+    from flask import got_request_exception, request
+
+    if getattr(app, "_loggerai", False):
+        return
+    app._loggerai = True
+    app.wsgi_app = LoggerAIMiddleware(app.wsgi_app)
+
+    @app.before_request
+    def _loggerai_route():
+        unit = context.current.get()
+        if unit is not None and request.url_rule is not None:
+            unit.route = route_template(request.url_rule.rule)
+
+    def _on_exception(sender, exception, **extra):
+        client = get_client()
+        if client is not None:
+            client.exception(exception, status=500)
+
+    got_request_exception.connect(_on_exception, app, weak=False)

loggerai/frames.py

@@ -0,0 +1,41 @@
+"""Stack frames for an error, innermost first, with the app's own code marked
+(in_app) so LoggerAI groups errors by where they happened in your code."""
+from __future__ import annotations
+
+import os
+import sysconfig
+from typing import List
+
+_LIBS = tuple(p for p in {sysconfig.get_paths().get("stdlib"), sysconfig.get_paths().get("platstdlib")} if p)
+_OWN = os.path.dirname(os.path.abspath(__file__))
+
+
+def _in_app(path: str) -> bool:
+    if not path or path.startswith("<"):
+        return False
+    if "site-packages" in path or "dist-packages" in path or path.startswith(_OWN):
+        return False
+    return not path.startswith(_LIBS)
+
+
+def frames(exc: BaseException, root: str, limit: int = 50) -> List[dict]:
+    out = []
+    tb = exc.__traceback__
+    entries = []
+    while tb is not None:
+        entries.append(tb)
+        tb = tb.tb_next
+    for tb in reversed(entries[-limit:]):  # innermost first
+        code = tb.tb_frame.f_code
+        path = os.path.abspath(code.co_filename)
+        rel = os.path.relpath(path, root) if path.startswith(root + os.sep) else path
+        qual = getattr(code, "co_qualname", code.co_name)  # 3.11+: Class.method
+        cls = qual.rsplit(".", 1)[0] if "." in qual and "<locals>" not in qual else None
+        out.append({"file": rel, "line": tb.tb_lineno, "function": code.co_name, "class": cls, "in_app": _in_app(path)})
+    return out
+
+
+def type_name(exc: BaseException) -> str:
+    t = type(exc)
+    mod = t.__module__
+    return t.__qualname__ if mod in ("builtins", "__main__") else f"{mod}.{t.__qualname__}"

loggerai/instrument.py

@@ -0,0 +1,215 @@
+"""Times what a request waits on, for whichever libraries are installed:
+SQLAlchemy (any database), httpx and requests (outgoing HTTP), redis-py. And
+a logging handler for warnings and above. Each is patched once and costs
+nothing outside a request."""
+from __future__ import annotations
+
+import logging
+import time
+from urllib.parse import urlsplit
+
+from . import context
+from .client import get_client
+
+_done = set()
+_DIALECTS = {"postgresql": "postgres", "mssql": "sqlserver"}
+
+
+def _once(name: str) -> bool:
+    if name in _done:
+        return False
+    _done.add(name)
+    return True
+
+
+def sqlalchemy() -> None:
+    try:
+        from sqlalchemy import event
+        from sqlalchemy.engine import Engine
+    except ImportError:
+        return
+    if not _once("sqlalchemy"):
+        return
+
+    @event.listens_for(Engine, "before_cursor_execute")
+    def _before(conn, cursor, statement, params, ctx, many):
+        conn.info.setdefault("loggerai_t", []).append(time.perf_counter())
+
+    @event.listens_for(Engine, "after_cursor_execute")
+    def _after(conn, cursor, statement, params, ctx, many):
+        stack = conn.info.get("loggerai_t")
+        if stack:
+            ms = (time.perf_counter() - stack.pop()) * 1000
+            name = conn.engine.dialect.name
+            context.dependency(_DIALECTS.get(name, name), context.sql_verb(statement), ms)
+
+    @event.listens_for(Engine, "handle_error")
+    def _error(exc_ctx):
+        conn = exc_ctx.connection
+        stack = conn.info.get("loggerai_t") if conn is not None else None
+        if stack:
+            ms = (time.perf_counter() - stack.pop()) * 1000
+            name = conn.engine.dialect.name
+            context.dependency(_DIALECTS.get(name, name), context.sql_verb(exc_ctx.statement or ""), ms, ok=False)
+
+
+def _host(url) -> str:
+    try:
+        return urlsplit(str(url)).hostname or "unknown"
+    except ValueError:
+        return "unknown"
+
+
+def httpx() -> None:
+    try:
+        import httpx as _httpx
+    except ImportError:
+        return
+    if not _once("httpx"):
+        return
+    send, asend = _httpx.Client.send, _httpx.AsyncClient.send
+
+    def _send(self, request, *a, **kw):
+        if context.current.get() is None:
+            return send(self, request, *a, **kw)
+        t = time.perf_counter()
+        ok = False
+        try:
+            r = send(self, request, *a, **kw)
+            ok = r.status_code < 500
+            return r
+        finally:
+            context.dependency(_host(request.url), request.method, (time.perf_counter() - t) * 1000, ok)
+
+    async def _asend(self, request, *a, **kw):
+        if context.current.get() is None:
+            return await asend(self, request, *a, **kw)
+        t = time.perf_counter()
+        ok = False
+        try:
+            r = await asend(self, request, *a, **kw)
+            ok = r.status_code < 500
+            return r
+        finally:
+            context.dependency(_host(request.url), request.method, (time.perf_counter() - t) * 1000, ok)
+
+    _httpx.Client.send, _httpx.AsyncClient.send = _send, _asend
+
+
+def requests() -> None:
+    try:
+        import requests as _requests
+    except ImportError:
+        return
+    if not _once("requests"):
+        return
+    send = _requests.Session.send
+
+    def _send(self, request, **kw):
+        if context.current.get() is None:
+            return send(self, request, **kw)
+        t = time.perf_counter()
+        ok = False
+        try:
+            r = send(self, request, **kw)
+            ok = r.status_code < 500
+            return r
+        finally:
+            context.dependency(_host(request.url), request.method or "GET", (time.perf_counter() - t) * 1000, ok)
+
+    _requests.Session.send = _send
+
+
+def redis() -> None:
+    try:
+        import redis as _redis
+    except ImportError:
+        return
+    if not _once("redis"):
+        return
+
+    def wrap(cls, name, op=None):
+        orig = getattr(cls, name, None)
+        if orig is None:
+            return
+
+        def sync(self, *args, **kw):
+            if context.current.get() is None:
+                return orig(self, *args, **kw)
+            t = time.perf_counter()
+            ok = False
+            try:
+                r = orig(self, *args, **kw)
+                ok = True
+                return r
+            finally:
+                context.dependency("redis", op or str(args[0] if args else "?").upper(), (time.perf_counter() - t) * 1000, ok)
+
+        async def asyn(self, *args, **kw):
+            if context.current.get() is None:
+                return await orig(self, *args, **kw)
+            t = time.perf_counter()
+            ok = False
+            try:
+                r = await orig(self, *args, **kw)
+                ok = True
+                return r
+            finally:
+                context.dependency("redis", op or str(args[0] if args else "?").upper(), (time.perf_counter() - t) * 1000, ok)
+
+        import inspect
+        setattr(cls, name, asyn if inspect.iscoroutinefunction(orig) else sync)
+
+    wrap(_redis.Redis, "execute_command")
+    wrap(_redis.client.Pipeline, "execute", "PIPELINE")
+    try:
+        import redis.asyncio as _ar
+        wrap(_ar.Redis, "execute_command")
+        wrap(_ar.client.Pipeline, "execute", "PIPELINE")
+    except ImportError:
+        pass
+
+
+_LEVELS = {"WARNING": "WARNING", "ERROR": "ERROR", "CRITICAL": "CRITICAL", "INFO": "INFO", "DEBUG": "DEBUG"}
+
+
+class LoggerAIHandler(logging.Handler):
+    """Sends log records at or above its level. A record carrying an exception
+    is reported as an error with its stack trace instead (once)."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.name == "loggerai" or record.name.startswith("loggerai."):
+            return
+        client = get_client()
+        if client is None or not client.enabled:
+            return
+        try:
+            if record.exc_info and record.exc_info[1] is not None:
+                client.exception(record.exc_info[1], status=None, handled=True, extra={"logger": record.name, "log": record.getMessage()[:500]})
+                return
+            client.log(_LEVELS.get(record.levelname, "WARNING"), record.name, record.getMessage())
+        except Exception:
+            pass
+
+
+def logging_handler(level: str) -> None:
+    if not level or not _once("logging"):
+        return
+    handler = LoggerAIHandler(level=getattr(logging, str(level).upper(), logging.WARNING))
+    logging.getLogger().addHandler(handler)
+    # uvicorn and gunicorn log errors (with the exception) to their own loggers, which may not reach the root.
+    for name in ("uvicorn.error", "gunicorn.error"):
+        lg = logging.getLogger(name)
+        if not lg.propagate:
+            lg.addHandler(handler)
+
+
+def all_from(client) -> None:
+    if client.capture_queries:
+        sqlalchemy()
+    if client.capture_http:
+        httpx()
+        requests()
+    if client.capture_redis:
+        redis()
+    logging_handler(client.logs_level)

loggerai/redact.py

@@ -0,0 +1,99 @@
+"""
+Masks secrets before anything leaves the app: by key name (fields, headers,
+query parameters) and by shape (bearer tokens and JWTs anywhere in a string).
+The same rules as LoggerAI's server, browser script and other SDKs.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+MASK = "[REDACTED]"
+
+# A key is sensitive when one of its words is one of these
+# ("accessToken" -> access, token; "X-CSRF-Token" -> x, csrf, token).
+_WORDS = {
+    "password", "passwd", "pwd", "pass", "passphrase", "secret", "token", "otp", "pin", "cvv", "cvc",
+    "ssn", "cookie", "authorization", "auth", "signature", "sig", "credential", "credentials", "bvn", "nin",
+}
+# ...or when its words run together into one of these ("x-api-key" -> xapikey).
+_JOINED = (
+    "apikey", "accesskey", "privatekey", "secretkey", "cardnumber", "clientsecret", "sessionid",
+    "authtoken", "accesstoken", "refreshtoken", "idtoken", "csrftoken", "xsrf", "setcookie",
+)
+# Query parameters that carry credentials in URLs (e.g. Google's ?key=).
+_URL_EXTRA = {"key", "code", "access_token", "id_token"}
+
+_SPLIT = re.compile(r"[^A-Za-z0-9]+|(?<=[a-z0-9])(?=[A-Z])")
+_JWT = re.compile(r"eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}")
+_BEARER = re.compile(r"(?i)\b(bearer|basic|token)\s+[A-Za-z0-9\-._~+/]{12,}=*")
+_URLISH = re.compile(r"^https?://", re.I)
+
+
+def is_sensitive(key: Any) -> bool:
+    if not isinstance(key, str) or not key:
+        return False
+    words = [w.lower() for w in _SPLIT.split(key) if w]
+    if any(w in _WORDS for w in words):
+        return True
+    joined = "".join(words)
+    return any(j in joined for j in _JOINED)
+
+
+def redact_string(s: str) -> str:
+    s = _JWT.sub("[REDACTED_JWT]", s)
+    return _BEARER.sub(lambda m: f"{m.group(1)} {MASK}", s)
+
+
+def redact_url(url: str) -> str:
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return redact_string(url)
+    if not parts.query:
+        return redact_string(url)
+    q = [(k, MASK if (is_sensitive(k) or k.lower() in _URL_EXTRA) and v else v) for k, v in parse_qsl(parts.query, keep_blank_values=True)]
+    netloc = parts.netloc
+    if "@" in netloc:  # user:password@host
+        netloc = MASK + "@" + netloc.rsplit("@", 1)[1]
+    return redact_string(urlunsplit((parts.scheme, netloc, parts.path, urlencode(q, safe="[]/:,"), parts.fragment)))
+
+
+def _redact_text(s: str) -> str:
+    """A string that may itself be JSON, a form body or a URL."""
+    t = s.strip()
+    if t[:1] in "{[":
+        try:
+            return json.dumps(redact(json.loads(t)), ensure_ascii=False)
+        except (ValueError, RecursionError):
+            pass
+    if _URLISH.match(t):
+        return redact_url(t)
+    if "=" in t and " " not in t and len(t) < 20000:
+        pairs = parse_qsl(t, keep_blank_values=True)
+        if pairs and any(is_sensitive(k) for k, _ in pairs):
+            return urlencode([(k, MASK if is_sensitive(k) and v else v) for k, v in pairs], safe="[]")
+    return redact_string(s)
+
+
+def redact(value: Any, _depth: int = 0) -> Any:
+    """A copy of value with secrets masked. Safe on any JSON-like data."""
+    if _depth > 40:
+        return value
+    if isinstance(value, dict):
+        out = {}
+        for k, v in value.items():
+            if is_sensitive(k) and v not in (None, "", [], {}):
+                out[k] = MASK
+            elif isinstance(k, str) and k.lower() in ("url", "href", "referrer", "referer", "location") and isinstance(v, str):
+                out[k] = redact_url(v)
+            else:
+                out[k] = redact(v, _depth + 1)
+        return out
+    if isinstance(value, list):
+        return [redact(v, _depth + 1) for v in value]
+    if isinstance(value, str):
+        return _redact_text(value) if value else value
+    return value

loggerai/wsgi.py

@@ -0,0 +1,39 @@
+"""WSGI middleware for any WSGI app. Flask users: use loggerai.flask.instrument(app),
+which adds route names and exceptions on top of this."""
+from __future__ import annotations
+
+from . import context
+from .client import get_client
+
+
+class LoggerAIMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    def __call__(self, environ, start_response):
+        client = get_client()
+        if client is None or not client.enabled or client.ignored(environ.get("PATH_INFO", "")):
+            return self.app(environ, start_response)
+        unit = context.Unit("http", environ.get("REQUEST_METHOD", "GET"), context.trace_from(environ.get("HTTP_TRACEPARENT")),
+                            context.session_from(environ.get("HTTP_X_LOGGERAI_SESSION")))
+        token = context.current.set(unit)
+        status = [500]
+
+        def _start(code, headers, exc_info=None):
+            try:
+                status[0] = int(str(code).split(" ", 1)[0])
+            except ValueError:
+                pass
+            return start_response(code, headers, exc_info) if exc_info is not None else start_response(code, headers)
+
+        try:
+            body = self.app(environ, _start)
+            # Most apps return a list; for streamed bodies the time stops here, before the stream is read.
+            return body
+        except Exception as e:
+            client.exception(e, status=500)
+            status[0] = 500
+            raise
+        finally:
+            context.current.reset(token)
+            client.finish(unit, status[0])

loggerai_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: loggerai-sdk
+Version: 0.1.0
+Summary: LoggerAI for Python: performance monitoring, errors, logs and health checks for FastAPI, Django, Flask and Celery.
+Project-URL: Homepage, https://loggerai.uk
+Project-URL: Source, https://github.com/ehisakhile/loggerai-python
+Author-email: LoggerAI <dev@loggerai.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apm,django,errors,fastapi,flask,logging,monitoring,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# LoggerAI for Python
+
+Performance monitoring, errors, logs and health checks for FastAPI,
+Starlette, Django, Flask and Celery, with AI that explains what went wrong.
+
+- **Every endpoint** timed under its route template (`/orders/{order_id}`):
+  p50/p95/p99, Apdex, status codes, slow and failed requests.
+- **What each request waits on**: database queries (SQLAlchemy and Django),
+  outgoing HTTP (`httpx`, `requests`), Redis.
+- **Exceptions**, grouped by cause, with stack traces that show your code first.
+- **Logs** at warning and above.
+- **Health checks** you define (database, cache, a queue).
+- **Background work** (Celery tasks, scripts) timed like requests.
+- **Browser sessions** recorded by LoggerAI's browser script link to the
+  server request each click caused (`traceparent`, `x-loggerai-session`).
+
+The package is `loggerai-sdk`; you import it as `loggerai`.
+
+Secrets (passwords, tokens, cookies, API keys, JWTs) are masked before
+anything leaves your server, request and response bodies are never sent, and
+users are counted by a one-way hash of their id. No dependencies; Python 3.8+.
+
+## Install
+
+```bash
+pip install loggerai-sdk
+```
+
+Get your project's **secret key** (`sk_live_...`) from LoggerAI → your
+project → **Connect**, and set it in the environment:
+
+```bash
+LOGGERAI_KEY=sk_live_...
+LOGGERAI_RELEASE=$GIT_SHA      # optional: "since release X"
+```
+
+Without a key nothing is recorded or sent, so local development stays quiet.
+
+### FastAPI / Starlette
+
+```python
+import loggerai
+from loggerai.asgi import LoggerAIMiddleware
+
+loggerai.init()
+app = FastAPI()
+app.add_middleware(LoggerAIMiddleware)
+```
+
+### Django
+
+```python
+# settings.py
+import loggerai
+loggerai.init()
+
+MIDDLEWARE = [
+    "loggerai.django.LoggerAIMiddleware",   # first
+    ...
+]
+```
+
+### Flask
+
+```python
+import loggerai, loggerai.flask
+
+loggerai.init()
+app = Flask(__name__)
+loggerai.flask.instrument(app)
+```
+
+### Celery
+
+```python
+import loggerai, loggerai.celery
+
+loggerai.init(service="worker")
+loggerai.celery.instrument()
+```
+
+### Any other WSGI app
+
+```python
+from loggerai.wsgi import LoggerAIMiddleware
+application = LoggerAIMiddleware(application)
+```
+
+## Health checks
+
+```python
+def database():
+    with engine.connect() as c:
+        c.execute(text("SELECT 1"))
+    return True               # or (False, "why")
+
+loggerai.init(health_checks={"database": database, "redis": lambda: r.ping()})
+```
+
+They run every minute in the background and show on the project's health
+page; alert on them from the dashboard.
+
+## More
+
+```python
+loggerai.set_user(request.user.id)          # only a one-way hash is sent
+
+with loggerai.measure("api.stripe.com", "POST"):   # calls it can't see itself
+    stripe.PaymentIntent.confirm(intent_id)
+
+with loggerai.track("job", "send_invoices"):       # scripts, cron jobs
+    send_invoices()
+
+try:
+    risky()
+except ValueError as e:
+    loggerai.capture_exception(e, order=order.id)  # handled, but worth seeing
+
+loggerai.flush()     # at the end of a short script or a serverless call
+```
+
+## Settings
+
+| Environment | `init()` | Default | |
+|---|---|---|---|
+| `LOGGERAI_KEY` | `key` | — | Secret key; off without it |
+| `LOGGERAI_SERVICE` | `service` | `app` | Name this process (`api`, `worker`) |
+| `LOGGERAI_ENVIRONMENT` | `environment` | `production` | Separates production from staging |
+| `LOGGERAI_RELEASE` | `release` | — | Version or git SHA |
+| `LOGGERAI_ENABLED` | `enabled` | `true` | Turn it off without removing the key |
+| | `logs_level` | `"WARNING"` | Lowest log level sent; `None` for no logs |
+| | `ignore_paths` | `/health`, `/up`, … | Paths not recorded |
+| | `capture_queries`, `capture_http`, `capture_redis` | `True` | |
+| | `flush_interval` | `5` | Seconds between batches |
+
+## How it sends
+
+Records are kept in memory and sent from a background thread every few
+seconds, gzipped, with a 2-second timeout. Requests never wait on LoggerAI.
+If it can't be reached, records are dropped instead of piling up. With
+gunicorn or uWSGI, each worker process sends its own batches.
+
+## Support
+
+dev@loggerai.uk · https://loggerai.uk

loggerai_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+loggerai/__init__.py,sha256=8QJqC-RI8rp9FoFJ35x1IkmT0mG5G_GrnV5mzuomhmc,4149
+loggerai/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+loggerai/asgi.py,sha256=yU8jx5Om5gSebXL4Wg-sskVkfMtCWPuoBaTe6ZXrYoQ,2363
+loggerai/celery.py,sha256=1Y5lHrdMpcfkyxCCw9p9DAg_aJ7s-ap0bSgWOWjmfik,1359
+loggerai/client.py,sha256=RSQInckRooD0eJ6U_68epjXs7H6IBUsaUTJWJw5Utoo,11241
+loggerai/context.py,sha256=wRR3s4t0-dn40fWqNvNhhnDkkMfHY0pDN6-fbQ9g7_Y,2823
+loggerai/django.py,sha256=oxWSijk5E-BXJ-mDfayrWn05f_ybHmQ-gCD2VBnZfd0,3703
+loggerai/flask.py,sha256=e0XOzGrrdu2-yeNpPlIDcEr5HbHet7r2TCjbMwRxTMk,1100
+loggerai/frames.py,sha256=QaiRrWPKlfVZZmC6x8hVjUAbNAOBGWIdc281TIGYFZI,1563
+loggerai/instrument.py,sha256=wX8qOaEhQI8ZOgWLA2xb5K_AUQN-WDtczUp-BT8pY7Y,6936
+loggerai/redact.py,sha256=i_mmpVIQvkxNUqKAEcdDt3Gx6Mm2BUKv-pFVhIovEeo,3855
+loggerai/wsgi.py,sha256=av7gL-fjU0Vl0b095fLbqE0juB7N2l5DyMvGFrr0FEI,1534
+loggerai_sdk-0.1.0.dist-info/METADATA,sha256=t4_m-sZFG9oZHvh7Ph9HthFQUweWimEfIoYRaFW2KzA,4941
+loggerai_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+loggerai_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=FhG3gg2wfy8WFL8pwSmIts0IEIsd-YpJkIj4Z8PydjM,1065
+loggerai_sdk-0.1.0.dist-info/RECORD,,

loggerai_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

loggerai_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LoggerAI
+
+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.