devbench 0.1.0__py3-none-any.whl

devbench/__init__.py

@@ -0,0 +1,121 @@
+"""Dev Bench server SDK for Python.
+
+    pip install devbench
+    DEVBENCH_DSN=https://<public>:<secret>@<ingest host>   (from `adt dsn create`)
+
+then one line where your framework wants it (README): Django
+(``"devbench.django"`` in INSTALLED_APPS), FastAPI/Starlette
+(``app.add_middleware(DevbenchMiddleware)``), Flask (``Devbench(app)``),
+Celery (``devbench.celery.install()``; automatic under Django).
+
+What it does:
+
+* accepts and forwards the correlation id     (the middlewares, trace_headers)
+* reports unhandled exceptions                (the middlewares, Celery hooks,
+                                               capture_exception)
+* reports handled failures                    (report_handled)
+* records who was affected                    (set_user)
+* keeps recent log lines per trace            (capture_logs; a logging handler)
+
+Nothing here raises into the application.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from . import _core, context, reporter
+from .config import DSN, Configuration, InvalidDSN
+from .identity import set_user
+from .trace import HEADER as TRACE_HEADER
+from .trace import Trace
+from .version import PROTOCOL_VERSION, VERSION
+
+__version__ = VERSION
+
+__all__ = [
+    "PROTOCOL_VERSION", "VERSION", "DSN", "Configuration", "InvalidDSN", "Trace", "TRACE_HEADER",
+    "configure", "enabled", "set_user", "capture_exception", "report_handled", "ignore_exceptions",
+    "trace_headers", "current_trace", "capture_logs", "flush", "test",
+]
+
+
+def configure(dsn: Optional[str] = None, service: Optional[str] = None, release: Optional[str] = None,
+              enabled: Optional[bool] = None, flush_interval: Optional[float] = None) -> None:
+    """Sets any of the environment's values from code (only those given)::
+
+        devbench.configure(dsn=secrets["devbench_dsn"], service="billing-api")
+
+    Takes effect from the next report. Never raises."""
+    _core.configure(dsn=dsn, service=service, release=release, enabled=enabled, flush_interval=flush_interval)
+
+
+def enabled() -> bool:
+    """False when DEVBENCH_ENABLED=false (or configure(enabled=False))."""
+    return _core.enabled()
+
+
+def capture_exception(error: Optional[BaseException] = None, symbol: Optional[str] = None) -> None:
+    """Reports an exception the application caught and wants seen, as
+    Sentry's capture_exception does (the one being handled when ``error`` is
+    omitted). Returns None and never raises::
+
+        except requests.RequestException as e:
+            devbench.capture_exception(e, symbol="billing.sync")
+    """
+    if error is None:
+        import sys
+
+        error = sys.exc_info()[1]
+    reporter.capture(error, "explicit", True, symbol)
+
+
+def report_handled(error: Any, symbol: str, reason: Optional[str] = None) -> None:
+    """Records that a failure was handled (caught and not re-raised) here.
+    Does not change behaviour. Repeats at the same site are counted::
+
+        except IntegrityError as e:
+            devbench.report_handled(e, symbol="customers.views.update", reason="uniqueness")
+    """
+    reporter.report_handled(error, symbol, reason)
+
+
+def ignore_exceptions() -> list:
+    """Class names (``module.QualName``) never reported; append your own."""
+    return reporter.ignore_exceptions()
+
+
+def current_trace() -> Optional[Trace]:
+    """The x-adt-trace of the request or job being handled, or None."""
+    return context.current_trace()
+
+
+def trace_headers() -> Dict[str, str]:
+    """Headers to add to an outbound HTTP call to another instrumented
+    service: the active trace with its hop incremented, or {}::
+
+        requests.post(url, json=body, headers={**headers, **devbench.trace_headers()})
+    """
+    trace = context.current_trace()
+    if trace is None:
+        return {}
+    forwarded = trace.next_hop()
+    return {TRACE_HEADER: str(forwarded)} if forwarded is not None else {}
+
+
+def capture_logs() -> bool:
+    """Keeps recent log lines per trace for triage (direct mode). The
+    integrations call this; a plain WSGI/ASGI app may call it itself."""
+    return _core.capture_logs()
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Sends whatever has been counted now, waiting at most ``timeout``
+    seconds. Returns True when nothing is left unsent."""
+    return _core.flush(timeout)
+
+
+def test(out: Any = None) -> bool:
+    """Checks DEVBENCH_DSN against ingest and prints the result; the same as
+    ``python -m devbench test``."""
+    return _core.self_test(out)

devbench/__main__.py

@@ -0,0 +1,24 @@
+"""``python -m devbench test``: checks DEVBENCH_DSN against Dev Bench and
+prints the HTTP result, without waiting for a flush. Exits non-zero when the
+DSN is missing, malformed, unreachable or rejected."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from . import _core
+
+USAGE = "usage: python -m devbench test\n"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args != ["test"]:
+        sys.stderr.write(USAGE)
+        return 2
+    return 0 if _core.self_test(sys.stdout) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

devbench/_core.py

@@ -0,0 +1,252 @@
+"""Configuration and transport selection.
+
+One transport per process, decided at the first report:
+
+* ``DEVBENCH_ENABLED=false``: none.
+* ``DEVBENCH_DSN`` (or ``ADT_DSN``): direct to Dev Bench. A DSN that does not
+  parse logs one warning and reports nothing.
+* neither: none. (The Ruby and Go SDKs fall back to a local sidecar socket;
+  this SDK is direct-only, so an environment without a DSN, such as
+  development or CI, sends nothing and says nothing.)
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import sys
+import threading
+from typing import IO, Any, Dict, Optional
+
+from . import logs
+from .config import DSN, Configuration, InvalidDSN
+from .direct import EXIT_TIMEOUT, DirectTransport
+
+_LOGGER = logging.getLogger("devbench")
+_lock = threading.RLock()
+_config: Optional[Configuration] = None
+_transport: Any = None
+_warned: Dict[str, bool] = {}
+_exit_flush_installed = False
+
+
+class _NullTransport:
+    """Reporting is off: everything is accepted and dropped."""
+
+    def deliver(self, payload: Any) -> None:
+        pass
+
+    def flush(self, timeout: float = 0) -> bool:
+        return True
+
+    def start(self) -> None:
+        pass
+
+    def stop(self) -> None:
+        pass
+
+
+NULL = _NullTransport()
+
+
+def config() -> Configuration:
+    """The configuration, read from the environment on first use."""
+    global _config
+    current = _config
+    if current is not None:
+        return current
+    with _lock:
+        if _config is None:
+            _config = Configuration()
+        return _config
+
+
+def transport() -> Any:
+    """The active transport. Built once, on first use, so a DSN configured
+    from code before the first report is seen."""
+    global _transport
+    current = _transport
+    if current is not None:
+        return current
+    with _lock:
+        if _transport is None:
+            _transport = _build_transport()
+        return _transport
+
+
+def enabled() -> bool:
+    try:
+        return config().enabled
+    except Exception:
+        return False
+
+
+def direct() -> bool:
+    """True when this process reports to Dev Bench (a DSN is set and
+    parses)."""
+    try:
+        return isinstance(transport(), DirectTransport)
+    except Exception:
+        return False
+
+
+def configure(dsn: Optional[str] = None, service: Optional[str] = None, release: Optional[str] = None,
+              enabled: Optional[bool] = None, flush_interval: Optional[float] = None) -> None:
+    """Configures from code instead of (or on top of) the environment. Only
+    the fields given change. Takes effect from the next report. Never raises
+    into the caller."""
+    try:
+        cfg = config()
+        if dsn is not None:
+            cfg.dsn = dsn
+        if service is not None:
+            cfg.service = service
+        if release is not None:
+            cfg.release = release
+        if enabled is not None:
+            cfg.enabled = bool(enabled)
+        if flush_interval is not None:
+            cfg.flush_interval = float(flush_interval)
+        _reset_transport()
+        # Capture already in place follows the new configuration.
+        if logs.active() or _capture_requested:
+            _apply_capture()
+    except Exception as e:
+        warn_once("configure", "devbench.configure raised %s; reporting is unchanged" % type(e).__name__)
+
+
+_capture_requested = False
+
+
+def capture_logs() -> bool:
+    """Keeps recent log lines, per trace, for triage to ask for (direct mode
+    only; elsewhere a no-op): a handler on the root logger. Every
+    integration calls this; a plain WSGI/ASGI app may call it itself.
+    Returns True when capture is on. Never raises."""
+    global _capture_requested
+    try:
+        _capture_requested = True
+        return _apply_capture()
+    except Exception:
+        return False
+
+
+def _apply_capture() -> bool:
+    if enabled() and direct():
+        logs.install()
+        logs.activate()
+        return True
+    logs.deactivate()
+    return False
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Sends whatever has been counted, now, waiting at most ``timeout``
+    seconds. Returns True when nothing is left unsent. Never raises."""
+    try:
+        return bool(transport().flush(timeout=timeout))
+    except Exception:
+        return False
+
+
+def self_test(out: Optional[IO[str]] = None) -> bool:
+    """Checks the DSN against ingest and prints the result
+    (``python -m devbench test``). Returns True when ingest accepted the key.
+    Never raises."""
+    out = out if out is not None else sys.stdout
+    try:
+        cfg = config()
+        if not cfg.enabled:
+            out.write("Dev Bench is disabled (DEVBENCH_ENABLED=false); nothing was sent.\n")
+            return False
+        if not (cfg.dsn or "").strip():
+            out.write("DEVBENCH_DSN is not set. Set it to the DSN Dev Bench gave you for this environment "
+                      "(https://<public>:<secret>@<host>, from `adt dsn create`), or call devbench.configure(dsn=...).\n")
+            return False
+        try:
+            dsn = DSN.parse(cfg.dsn)
+        except InvalidDSN as e:
+            out.write("DEVBENCH_DSN %s.\n" % e)
+            return False
+        client = DirectTransport(dsn, cfg.resolved_service(), cfg.resolved_release())
+        return client.self_test(out)
+    except Exception as e:
+        out.write("Dev Bench test failed: %s: %s\n" % (type(e).__name__, e))
+        return False
+
+
+def reset() -> None:
+    """Drops the active transport (stopping a direct client's thread) and the
+    configuration, so both are rebuilt from scratch. For tests."""
+    global _config, _capture_requested
+    _reset_transport()
+    logs.deactivate()
+    with _lock:
+        _config = None
+        _capture_requested = False
+        _warned.clear()
+
+
+def warn_once(kind: str, message: str) -> None:
+    """Logs a problem with Dev Bench itself, once per kind per process, on
+    the ``devbench`` logger. Never raises."""
+    try:
+        with _lock:
+            if _warned.get(kind):
+                return
+            _warned[kind] = True
+        _LOGGER.warning("[devbench] %s", message)
+    except Exception:
+        pass
+
+
+def rebuild_transport() -> None:
+    """Drops a transport built before the integrations said what the app is
+    (its counts are flushed first), so the next use builds it with the right
+    service and root. Nothing to do when none was built."""
+    if _transport is not None:
+        _reset_transport()
+
+
+def _reset_transport() -> None:
+    global _transport
+    with _lock:
+        old, _transport = _transport, None
+    stop = getattr(old, "stop", None)
+    if stop is not None:
+        stop()
+
+
+def _build_transport() -> Any:
+    try:
+        cfg = config()
+        if not cfg.enabled or not (cfg.dsn or "").strip():
+            return NULL
+        try:
+            dsn = DSN.parse(cfg.dsn)
+        except InvalidDSN as e:
+            warn_once("dsn", "DEVBENCH_DSN %s; nothing will be reported" % e)
+            return NULL
+        _install_exit_flush()
+        return DirectTransport(dsn, cfg.resolved_service(), cfg.resolved_release(),
+                               interval=cfg.flush_interval, warn=warn_once)
+    except Exception:
+        return NULL
+
+
+def _install_exit_flush() -> None:
+    """One last flush when the process exits, bounded to 2 s (spec)."""
+    global _exit_flush_installed
+    if _exit_flush_installed:
+        return
+    _exit_flush_installed = True
+    atexit.register(_exit_flush)
+
+
+def _exit_flush() -> None:
+    current = _transport
+    if isinstance(current, DirectTransport):
+        try:
+            current.flush(timeout=EXIT_TIMEOUT)
+        except Exception:
+            pass

devbench/_integration.py

@@ -0,0 +1,107 @@
+"""What every framework integration shares."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, List, Optional, Tuple
+
+from . import _core, context, reporter
+from .trace import HEADER as TRACE_HEADER
+
+HANDLED_HEADER = "x-adt-handled"
+EXPOSE_HEADER = "Access-Control-Expose-Headers"
+
+# Names a framework gives an app that say nothing about which app it is.
+_GENERIC = frozenset(["", "__main__", "app", "main", "wsgi", "asgi", "application", "server", "api"])
+
+
+def setup(service: Optional[str] = None, root: Optional[str] = None) -> None:
+    """Records what the framework knows about the app (its name, its root,
+    whether this is a Celery worker), unless something more specific already
+    did, then starts log capture. A transport built before the hints arrived
+    is rebuilt, so the service name never depends on import order. Never
+    raises."""
+    try:
+        cfg = _core.config()
+        changed = False
+        name = (service or "").split(".")[0].strip()
+        if name not in _GENERIC and not cfg.framework_service:
+            cfg.framework_service = name
+            changed = True
+        if root and not cfg.app_root:
+            cfg.app_root = str(root)
+            changed = True
+        if not cfg.worker and celery_worker_command():
+            cfg.worker = "celery"
+            changed = True
+        if changed:
+            _core.rebuild_transport()
+        _core.capture_logs()
+    except Exception:
+        pass
+
+
+def celery_worker_command(argv: Optional[List[str]] = None) -> bool:
+    """`celery -A proj worker ...`: the command line is all there is before
+    Celery's worker_init fires, and the service must be known before the
+    first report."""
+    argv = sys.argv if argv is None else argv
+    if not argv:
+        return False
+    words = [a for a in argv[1:] if not a.startswith("-")]
+    return "worker" in words and "celery" in os.path.basename(argv[0] or "").lower()
+
+
+def callable_path(fn: Any) -> Optional[str]:
+    """``module.qualname`` of a view, endpoint or task function: where a
+    failure surfaced (the report's ``symbol``)."""
+    try:
+        target = getattr(fn, "view_class", None) or getattr(fn, "cls", None) or fn
+        module = getattr(target, "__module__", None)
+        qual = getattr(target, "__qualname__", None) or getattr(target, "__name__", None)
+        if not qual:
+            return None
+        return "%s.%s" % (module, qual) if module else str(qual)
+    except Exception:
+        return None
+
+
+def report_request_error(error: Any, symbol: Optional[str]) -> None:
+    reporter.capture(error, "request", False, symbol)
+
+
+def handled_count() -> int:
+    """Failures handled during this traced request (0 when it carries no
+    trace: the browser that reads the header always sends one)."""
+    scope = context.current()
+    if scope is None or scope.trace is None:
+        return 0
+    return scope.handled
+
+
+def exposed(current: Optional[str]) -> str:
+    """Access-Control-Expose-Headers with x-adt-handled added. A browser
+    cannot read a custom response header cross-origin unless it is listed
+    there (an SPA on another origin than its API would see nothing)."""
+    current = current or ""
+    if HANDLED_HEADER in current.lower():
+        return current
+    return "%s, %s" % (current, HANDLED_HEADER) if current else HANDLED_HEADER
+
+
+def with_handled(headers: List[Tuple[str, str]]) -> List[Tuple[str, str]]:
+    """A WSGI/ASGI header list with x-adt-handled set when failures were
+    handled during this traced request; the list unchanged otherwise. The
+    value is a count and nothing else: any script on the page can read it."""
+    count = handled_count()
+    if count <= 0:
+        return headers
+    out = [(k, v) for k, v in headers if k.lower() not in (HANDLED_HEADER, EXPOSE_HEADER.lower())]
+    current = next((v for k, v in headers if k.lower() == EXPOSE_HEADER.lower()), None)
+    out.append((HANDLED_HEADER, str(count)))
+    out.append((EXPOSE_HEADER, exposed(current)))
+    return out
+
+
+__all__ = ["TRACE_HEADER", "HANDLED_HEADER", "EXPOSE_HEADER", "setup", "callable_path", "report_request_error", "handled_count", "exposed", "with_handled"]

devbench/asgi.py

@@ -0,0 +1,82 @@
+"""ASGI middleware for FastAPI, Starlette and any ASGI app::
+
+    from devbench.asgi import DevbenchMiddleware   # or devbench.fastapi
+    app.add_middleware(DevbenchMiddleware)
+
+Accepts the correlation id for the duration of the request, scopes identity
+to it, reports an exception that escapes the app and re-raises the same
+object (Starlette's ServerErrorMiddleware, outside it, still answers 500 and
+runs your handlers), and marks a traced response during which failures were
+handled (``x-adt-handled``).
+
+A plain ASGI middleware, not BaseHTTPMiddleware: the request's context (the
+trace, the user) reaches the endpoint, its thread pool and its logging calls
+unchanged, and responses stream as before.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, MutableMapping, Optional
+
+from . import _core, _integration, context
+from .trace import Trace
+
+Scope = MutableMapping[str, Any]
+Message = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+_TRACE_HEADER = b"x-adt-trace"
+
+
+class DevbenchMiddleware:
+    def __init__(self, app: Callable[[Scope, Receive, Send], Awaitable[None]]) -> None:
+        self.app = app
+        _integration.setup()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http" or not _core.enabled():
+            await self.app(scope, receive, send)
+            return
+        trace = _parse(scope)
+
+        async def send_wrapper(message: Message) -> None:
+            if message.get("type") == "http.response.start":
+                try:
+                    message = _with_handled(message)
+                except Exception:
+                    pass
+            await send(message)
+
+        with context.scoped(trace):
+            try:
+                await self.app(scope, receive, send_wrapper)
+            except Exception as error:
+                _integration.report_request_error(error, _symbol(scope))
+                raise
+
+
+def _parse(scope: Scope) -> Optional[Trace]:
+    try:
+        for name, value in scope.get("headers") or ():
+            if name.lower() == _TRACE_HEADER:
+                return Trace.parse(value)
+    except Exception:
+        pass
+    return None
+
+
+def _symbol(scope: Scope) -> Optional[str]:
+    # Starlette's router puts the matched endpoint in the scope.
+    endpoint = scope.get("endpoint")
+    return _integration.callable_path(endpoint) if endpoint is not None else None
+
+
+def _with_handled(message: Message) -> Message:
+    if _integration.handled_count() <= 0:
+        return message
+    headers = [(k.decode("latin-1"), v.decode("latin-1")) for k, v in message.get("headers") or ()]
+    updated = _integration.with_handled(headers)
+    message = dict(message)
+    message["headers"] = [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in updated]
+    return message