devbench 0.1.0__py3-none-any.whl

devbench/scrub.py

@@ -0,0 +1,247 @@
+"""A port of the sidecar's strict egress (internal/scrub and
+Sidecar.forEgress): what this SDK does to an exemplar or a log line before it
+leaves the process, so leaving out the sidecar does not loosen redaction
+(DECISIONS #160). Held to testdata/redaction_vectors.json.
+
+Strict mode is the only mode: template (values the format marks: quoted
+strings, numbers, durations), then scrub (values with a shape: emails, cards,
+tokens, credentials, IPs), then the prose heuristic (runs of capitalised words
+that are not framework vocabulary).
+
+Patterns are Go's, with Go's ``\\b``, ``\\d`` and ``\\s`` (see fingerprint).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Optional, Tuple
+
+from . import fingerprint as fp_mod
+from .fingerprint import GO_NOT_WS as NOT_WS
+from .fingerprint import GO_WS as WS
+from .fingerprint import go_re, utf8
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .egress_policy import EgressPolicy
+
+# The card and phone rules (#186; internal/scrub/numbers.go, the `numbers`
+# vectors): a candidate regex plus checks on the whole candidate, run in the
+# replacement callback. A rejected candidate is left as written and matching
+# carries on after it; it is never retried shorter. No lookaround in the
+# candidates (the Go SDK is RE2), so every SDK finds the same ones.
+CARD = "<redacted:card>"
+PHONE = "<redacted:phone>"
+CARD_CANDIDATE = go_re(r"\b(?:\d[ \-]*?){13,19}\b")
+# Group 1 is the character before the number (or the start of the text): a
+# phone number is not glued to a letter, digit, `_` or `-`, which keeps a
+# UUID's tail and `ord_123456789` out. Group 2 is the candidate. Spelled out
+# rather than through go_re, whose \d rewrite does not apply inside a class.
+PHONE_CANDIDATE = re.compile(r"(^|[^A-Za-z0-9_\-])(\+?[0-9][0-9\t\n\f\r ().\-]{7,}[0-9])")
+ISO_DATE_PREFIX = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}(?:\Z|[^0-9])")
+DECIMAL = re.compile(r"[0-9]+\.[0-9]+")
+WORD_CHAR = re.compile(r"[A-Za-z0-9_]")
+NOT_DIGIT = re.compile(r"[^0-9]")
+# E.164 caps a phone number at 15 digits; anything longer is an id.
+MIN_PHONE_DIGITS = 7
+MAX_PHONE_DIGITS = 15
+
+
+def _is_timestamp(digits: str) -> bool:
+    """A bare Unix timestamp in seconds or milliseconds (2001 to 2033)."""
+    return len(digits) in (10, 13) and digits[0] == "1"
+
+
+def _luhn(digits: str) -> bool:
+    if not digits:
+        return False
+    total = 0
+    for i, c in enumerate(reversed(digits)):
+        d = ord(c) - 48
+        if i % 2 == 1:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0
+
+
+def _is_card(candidate: str) -> bool:
+    """The digits pass the Luhn check, and the candidate is not a bare
+    13-digit run starting with 1 (a millisecond timestamp)."""
+    digits = NOT_DIGIT.sub("", candidate)
+    if digits == candidate and _is_timestamp(digits):
+        return False
+    return _luhn(digits)
+
+
+def _is_phone(candidate: str, after: str) -> bool:
+    """Judged with the character after it ('' at the end of the text). Not a
+    phone when a letter, digit or `_` follows; it starts with an ISO date; it
+    is a decimal; it has fewer than 7 or more than 15 digits; or it is a bare
+    10- or 13-digit run starting with 1 (a timestamp)."""
+    if WORD_CHAR.match(after):
+        return False
+    if ISO_DATE_PREFIX.match(candidate) or DECIMAL.fullmatch(candidate):
+        return False
+    digits = NOT_DIGIT.sub("", candidate)
+    if not MIN_PHONE_DIGITS <= len(digits) <= MAX_PHONE_DIGITS:
+        return False
+    return not (digits == candidate and _is_timestamp(digits))
+
+
+# Ordered most-specific first, and the order is load-bearing: see the
+# comments on internal/scrub's rules (a credential containing an email, a
+# phone pattern eating an SSN).
+RULES = [
+    (re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----"), "<redacted:private-key>"),
+    (go_re(r"\beyJ[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\b"), "<redacted:jwt>"),
+    (go_re(r"([a-zA-Z][a-zA-Z0-9+.\-]*://)[^\t\n\f\r :/@]+:[^\t\n\f\r /@]+@"), r"\g<1><redacted:credentials>@"),
+    (go_re(r"\b(authorization|proxy-authorization)(" + WS + "*[:=]" + WS + "*)(?:" + NOT_WS + r"+[ \t]+)?" + NOT_WS + "+",
+           re.IGNORECASE), r"\g<1>\g<2><redacted:authorization>"),
+    (go_re(r"\b(bearer|basic)" + WS + r"+[A-Za-z0-9._\-=/+]{8,}", re.IGNORECASE), r"\g<1> <redacted:token>"),
+    (go_re(r"\bAKIA[0-9A-Z]{16}\b"), "<redacted:aws-key>"),
+    (go_re(r"\b(password|passwd|pwd|secret|api[_\-]?key|access[_\-]?token|refresh[_\-]?token|"
+           r"client[_\-]?secret|private[_\-]?key|session[_\-]?id|csrf[_\-]?token)"
+           "(" + WS + "*[:=]" + WS + "*)(\"[^\"]*\"|'[^']*'|" + NOT_WS + "+)", re.IGNORECASE),
+     r"\g<1>\g<2><redacted:secret>"),
+    (go_re(r"\b[^\t\n\f\r <>@]+@[^\t\n\f\r <>@]+\.[A-Za-z]{2,}\b"), "<redacted:email>"),
+    (go_re(r"\b\d{3}-\d{2}-\d{4}\b"), "<redacted:ssn>"),
+    # The card and phone rules (#186) judge each candidate in the callback.
+    (CARD_CANDIDATE, lambda m: CARD if _is_card(m.group(0)) else m.group(0)),
+    (go_re(r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"), "<redacted:ip>"),
+    (PHONE_CANDIDATE,
+     lambda m: m.group(1) + PHONE if _is_phone(m.group(2), m.string[m.end():m.end() + 1]) else m.group(0)),
+]
+
+# internal/sidecar/trace.go's traceRe.
+TRACE = go_re(r"\bv1/([A-Za-z0-9_-]{1,64})/([A-Za-z0-9_-]{1,64})/(\d{1,3})\b")
+
+# What Rails, Go and HTTP say, lowercased (internal/scrub/prose.go). Masking
+# any of these would destroy diagnostic content.
+VOCABULARY = frozenset("""
+ok created accepted content moved permanently found modified bad request
+unauthorized payment required forbidden not method allowed acceptable
+timeout conflict gone unsupported media type unprocessable entity too many
+requests internal server error implemented gateway service unavailable no
+see other temporary redirect
+started completed processing rendered rendering redirected filter chain
+halted parameters views load exists destroy update create transaction
+rollback commit cache performed performing enqueued retrying rescued
+validation failed invalid email has already been taken
+panic goroutine runtime fatal context deadline exceeded canceled cancelled
+connection refused such host timeout_ closed reset peer broken pipe
+temporarily
+warning warn info debug trace exception failure retry skipping unknown
+missing expired denied true false nil null none
+""".split())
+
+FIELD = re.compile("[^" + fp_mod.GO_SPACE_CLASS + "]+")
+TRAILING_PUNCT = re.compile(r"[.,;:!?)\"']+\Z")
+CODE_CHARS = re.compile(r"[:#/()_=<>@\[\]{}\"']")
+ASCII_DIGIT = re.compile("[0-9]")
+
+# Shape rules (EgressPolicy).
+MASKED = "masked"
+NONE = "none"
+FULL = "full"
+
+
+def text(line: str) -> str:
+    """internal/scrub.Text: every shape rule, in order."""
+    out = utf8(line)
+    for pattern, replacement in RULES:
+        out = pattern.sub(replacement, out)
+    return out
+
+
+def prose(line: str) -> str:
+    """internal/scrub.Prose: runs of two or more capitalised words that are
+    not framework vocabulary become <redacted:name>."""
+    if not line:
+        return line
+    fields = FIELD.findall(line)
+    if len(fields) < 2:
+        return line
+    out = []
+    run: list = []
+
+    def flush() -> None:
+        if len(run) >= 2:
+            out.append("<redacted:name>")
+        elif len(run) == 1:
+            out.append(run[0])
+        del run[:]
+
+    for field in fields:
+        if _proper_noun(field):
+            run.append(field)
+        else:
+            flush()
+            out.append(field)
+    flush()
+    return " ".join(out)
+
+
+def egress(line: str, policy: "Optional[EgressPolicy]" = None, service: str = "") -> str:
+    """The sidecar's forEgress in strict mode, for one line: any trace kept as
+    is, the rest templated, scrubbed and prose-masked, then the learned rules
+    (an EgressPolicy), exactly as Sidecar.redactBody applies them:
+
+    * shape 'none': the content never leaves: <withheld:shape:<fp12>>
+    * shape 'full': lifts only the prose heuristic, never base redaction
+    * shape 'masked': prose heuristic (already on in strict mode)
+    * field / term: masked afterwards, whatever the shape rule says
+    """
+    line = utf8(line)
+    match = TRACE.search(line)
+    body = TRACE.sub("<trace>", line) if match else line
+    fp, rule = _shape_rule(policy, service, body)
+    redacted = withheld(fp) if rule == NONE else _redact_body(body, rule, policy)
+    return "[%s] %s" % (match.group(0), redacted) if match else redacted
+
+
+def template_text(value: str, policy: "Optional[EgressPolicy]" = None, fp: Optional[str] = None) -> str:
+    """A bundle's template text: as the sidecar's answerEvidenceRequests does,
+    the shape's own rule (by the signal's fingerprint), strict redaction, then
+    a second shape pass. Empty when the shape's content never leaves."""
+    rule = policy.rule_for(fp) if policy is not None and fp else None
+    if rule == NONE:
+        return ""
+    return text(_redact_body(utf8(value), rule, policy))
+
+
+def withheld(fp: Optional[str]) -> str:
+    """What stands in for a line whose shape is marked 'none'."""
+    return "<withheld:shape:%s>" % (fp or "")[:12]
+
+
+def _redact_body(body: str, rule: Optional[str], policy: "Optional[EgressPolicy]") -> str:
+    redacted = text(fp_mod.template(body))
+    if rule != FULL:
+        redacted = prose(redacted)
+    return policy.mask(redacted) if policy is not None else redacted
+
+
+def _shape_rule(policy: "Optional[EgressPolicy]", service: str, body: str) -> Tuple[Optional[str], Optional[str]]:
+    if policy is None or not policy.has_shapes():
+        return None, None
+    fp = fp_mod.compute(kind="log_template", source="sidecar", service=service or "", message=body)
+    if fp is None:
+        return None, None
+    return fp, policy.rule_for(fp)
+
+
+def _proper_noun(token: str) -> bool:
+    trimmed = TRAILING_PUNCT.sub("", token)
+    if len(trimmed.encode("utf-8", "replace")) < 2:
+        return False
+    if CODE_CHARS.search(trimmed):
+        return False
+    if trimmed == trimmed.upper():
+        return False
+    first = trimmed[0]
+    if not ("A" <= first <= "Z"):
+        return False
+    if ASCII_DIGIT.search(trimmed):
+        return False
+    return trimmed.lower() not in VOCABULARY

devbench/trace.py

@@ -0,0 +1,82 @@
+"""The correlation id that ties a user action together across every service.
+
+Wire form (docs/SERVER_SDK_SPEC.md, Capability 1)::
+
+    x-adt-trace: v1/<session>/<intent>/<hop>
+
+This must agree exactly with the other SDKs and the sidecar
+(testdata/trace_vectors.json). A trace the browser writes and Python mangles
+is worse than no trace: the request still succeeds, so nothing looks wrong,
+and the evidence simply cannot be joined.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from .fingerprint import GO_SPACE
+
+HEADER = "x-adt-trace"
+WSGI_HEADER = "HTTP_X_ADT_TRACE"
+MAX_HOP = 99
+_ID = re.compile(r"[A-Za-z0-9_-]{1,64}\Z")
+_HOP = re.compile(r"[0-9]{1,3}\Z")
+
+
+class Trace:
+    __slots__ = ("session", "intent", "hop")
+
+    def __init__(self, session: str, intent: str, hop: int) -> None:
+        self.session = session
+        self.intent = intent
+        self.hop = hop
+
+    @classmethod
+    def parse(cls, value: Any) -> "Optional[Trace]":
+        """Parses a header value. Returns None rather than raising: Dev Bench
+        must never fail a customer's request, and a request carrying a mangled
+        correlation id is still a request the user wants served."""
+        if isinstance(value, bytes):
+            try:
+                value = value.decode("ascii")
+            except UnicodeDecodeError:
+                return None
+        if not isinstance(value, str):
+            return None
+        value = value.strip(GO_SPACE)  # Go: strings.TrimSpace
+        if not value.startswith("v1/"):
+            return None
+        parts = value[3:].split("/")
+        if len(parts) != 3:
+            return None
+        session, intent, hop = parts
+        if not _ID.match(session) or not _ID.match(intent) or not _HOP.match(hop):
+            return None
+        number = int(hop)
+        if number > MAX_HOP:
+            return None
+        return cls(session, intent, number)
+
+    def __str__(self) -> str:
+        return "v1/%s/%s/%d" % (self.session, self.intent, self.hop)
+
+    def __repr__(self) -> str:
+        return "Trace(%r)" % str(self)
+
+    @property
+    def key(self) -> str:
+        """Identifies the user action, independent of which service saw it."""
+        return "%s/%s" % (self.session, self.intent)
+
+    def next_hop(self) -> "Optional[Trace]":
+        """The trace to send to a downstream service, or None at the limit."""
+        if self.hop >= MAX_HOP:
+            return None
+        return Trace(self.session, self.intent, self.hop + 1)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Trace) and (self.session, self.intent, self.hop) == (other.session, other.intent, other.hop)
+
+    def __hash__(self) -> int:
+        return hash((self.session, self.intent, self.hop))

devbench/version.py

@@ -0,0 +1,12 @@
+"""The SDK's release version and the protocol version it speaks."""
+
+# This package's own release (python-v<VERSION>). The SDKs release
+# independently (docs/specs/sdk-python-php-dotnet.md, "Versioning").
+VERSION = "0.1.0"
+
+# The wire format this speaks: the `v` every payload carries (the flush body
+# and the evidence bundle). Not the release VERSION above: it changes only for
+# a breaking wire change, and ingest tells formats apart by it. It must equal
+# `current` in testdata/protocol_vectors.json (docs/SERVER_SDK_SPEC.md,
+# "Protocol version"); send it, never a literal.
+PROTOCOL_VERSION = 1

devbench/wsgi.py

@@ -0,0 +1,67 @@
+"""WSGI middleware: accepts the correlation id for the duration of the
+request, scopes identity to it, reports an exception that escapes the app
+(then re-raises the same object), and marks a traced response during which
+failures were handled (``x-adt-handled``).
+
+Flask's integration (``devbench.flask.Devbench``) installs it; any other WSGI
+app can wrap itself::
+
+    application = DevbenchMiddleware(application)
+
+Never rejects a request, never alters the response body, never raises
+anything of its own.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Optional
+
+from . import _core, _integration, context
+from .trace import WSGI_HEADER, Trace
+
+
+class DevbenchMiddleware:
+    def __init__(self, app: Callable[..., Iterable[bytes]], symbol: Optional[Callable[[dict], Optional[str]]] = None) -> None:
+        self.app = app
+        # Where a failure surfaced, read from the environ after the app ran.
+        self._symbol = symbol
+        _integration.setup()
+
+    def __call__(self, environ: dict, start_response: Callable[..., Any]) -> Iterable[bytes]:
+        # DEVBENCH_ENABLED=false: not even the scope or the header.
+        if not _core.enabled():
+            return self.app(environ, start_response)
+        trace = _parse(environ)
+
+        def start(status: str, headers: list, exc_info: Any = None) -> Any:
+            try:
+                headers = _integration.with_handled(list(headers))
+            except Exception:
+                pass
+            if exc_info is not None:
+                return start_response(status, headers, exc_info)
+            return start_response(status, headers)
+
+        # Scoped even without a trace: identity set during this request must
+        # end with it, and a thread's next request must not inherit it.
+        with context.scoped(trace):
+            try:
+                return self.app(environ, start)
+            except Exception as error:
+                # Reported inside the scope, so the report carries this
+                # request's trace and user. capture never raises.
+                _integration.report_request_error(error, self._symbol_for(environ))
+                raise
+
+    def _symbol_for(self, environ: dict) -> Optional[str]:
+        try:
+            return self._symbol(environ) if self._symbol is not None else None
+        except Exception:
+            return None
+
+
+def _parse(environ: dict) -> Optional[Trace]:
+    try:
+        return Trace.parse(environ.get(WSGI_HEADER))
+    except Exception:
+        return None

devbench-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: devbench
+Version: 0.1.0
+Summary: Dev Bench server SDK for Python: errors, who was affected, and the server log lines of a failing request, for Django, FastAPI, Flask and Celery.
+Author: Dev Bench
+License-Expression: MIT
+Project-URL: Homepage, https://developerbench.com
+Project-URL: Source, https://github.com/pasperry/devbench-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Framework :: Celery
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Dev Bench for Python
+
+Errors, who they hit, and the server log lines of the request that failed,
+from Django, FastAPI, Flask and Celery to Dev Bench. Zero runtime
+dependencies (the standard library only); Python 3.9+.
+
+## Install
+
+```sh
+pip install devbench
+```
+
+Set **one** value in the app's environment, the DSN `adt dsn create`
+printed for this environment:
+
+```sh
+DEVBENCH_DSN=https://<public>:<secret>@adt-ingest.onrender.com
+```
+
+Then add one line where your framework wants it.
+
+### Django
+
+In `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    "devbench.django",
+    # ...
+]
+```
+
+That is the whole install: at startup it puts its middleware first in
+`MIDDLEWARE` (not again if you list `devbench.django.middleware.DevbenchMiddleware`
+yourself), reports what Django answers with a 500, keeps log lines, and,
+when Celery is loaded, installs the Celery hooks. WSGI and ASGI. Django 4.2+.
+
+### FastAPI (and Starlette)
+
+```python
+from fastapi import FastAPI
+from devbench.fastapi import DevbenchMiddleware
+
+app = FastAPI()
+app.add_middleware(DevbenchMiddleware)
+```
+
+Async and sync endpoints alike. Any other ASGI app: `devbench.asgi.DevbenchMiddleware`.
+
+### Flask
+
+```python
+from flask import Flask
+from devbench.flask import Devbench
+
+app = Flask(__name__)
+Devbench(app)          # or: Devbench().init_app(app)
+```
+
+Any other WSGI app: `application = devbench.wsgi.DevbenchMiddleware(application)`.
+
+### Celery
+
+Under Django there is nothing to add. Otherwise, where your Celery app is
+created:
+
+```python
+import devbench.celery
+devbench.celery.install()
+```
+
+### Check it
+
+```sh
+python -m devbench test             # Django: python manage.py devbench_test
+# Dev Bench: checking the DSN against https://adt-ingest.onrender.com (service "acme_shop")
+#   HTTP 200: accepted - tenant "acme", environment "production". Nothing was recorded; real errors will appear as issues.
+```
+
+It prints the HTTP result, or says plainly what is wrong (`DEVBENCH_DSN is
+not set`, `HTTP 401: the key in DEVBENCH_DSN was rejected`, `could not reach
+…`) and exits non-zero. It records nothing.
+
+## Configuration
+
+All optional except the DSN.
+
+| Variable | Default | |
+|---|---|---|
+| `DEVBENCH_DSN` | — (falls back to `ADT_DSN`) | `https://<public>:<secret>@<host>[:port]` from `adt dsn create`. The server authenticates with the secret. Plain `http://` is accepted only for localhost. Unset: nothing is sent (there is no sidecar mode). |
+| `DEVBENCH_SERVICE` | Django: the project (`acme_shop` from `acme_shop.settings`); Flask: the app's import name; else `app`; **`<that>-celery` in a Celery worker** | Groups this app's issues. Set it and it wins everywhere. |
+| `DEVBENCH_RELEASE` | the first found of: a `REVISION` file in the app root (Django's `BASE_DIR`, else the working directory), `HEROKU_SLUG_COMMIT`, `KAMAL_VERSION`, `GITHUB_SHA`, `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`; else empty | Which deploy an occurrence came from. |
+| `DEVBENCH_ENABLED` | on | `false` turns everything off: no hooks, no headers, nothing sent. |
+
+Or from code, before the first report:
+
+```python
+import devbench
+devbench.configure(dsn=secrets["devbench_dsn"], service="billing-api")
+```
+
+A DSN that does not parse logs one `[devbench]` warning (on the `devbench`
+logger) and reports nothing; it never raises into the app. Neither key is
+ever printed.
+
+## What is captured automatically
+
+| What | How | `context` |
+|---|---|---|
+| A Django view or middleware error answered with a 500 | `got_request_exception` | `request` |
+| A Flask view error answered with a 500 | `got_request_exception` | `request` |
+| An exception escaping a FastAPI/Starlette app (still answered 500 by Starlette, and your exception handlers still run) | the ASGI middleware reports, then re-raises the same object | `request` |
+| A failed Celery task (the last attempt; `self.retry()` is not a failure) | `task_failure` | `job` |
+
+Each report carries the class (`module.QualName`; builtins plainly, e.g.
+`KeyError`), the message (≤ 2,000 characters), where it surfaced (the view,
+endpoint or task: `shop.views.checkout`, `acme.charge`), up to 50 stack
+frames (innermost first, paths relative to the app root), the trace, and
+the user.
+
+- **Once per exception.** An error that passes several hooks is reported
+  once.
+- **Status codes are not failures.** Django's `Http404`, `PermissionDenied`,
+  `BadRequest`, `SuspiciousOperation`; werkzeug and Starlette
+  `HTTPException`s; Celery's `Retry`, `Ignore`, `Reject`; and anything that
+  is not an `Exception` (`SystemExit`, `KeyboardInterrupt`,
+  `asyncio.CancelledError`) are never reported. Add your own by name:
+
+  ```python
+  devbench.ignore_exceptions().append("myapp.errors.NotAuthorized")
+  ```
+
+- **Never in the way.** No hook raises into the app; a failure while
+  reporting is dropped, and the application's own exception always comes
+  out unchanged.
+
+## What is sent, and when
+
+- Each report is **fingerprinted and counted in the process** (class,
+  templated message and in-app frames; the same algorithm as every other
+  Dev Bench SDK). Repeats cost a counter increment.
+- **Once a minute** a background thread sends the counts (fingerprint, how
+  many, first/last seen, up to 20 affected users each) in one small request.
+  Nothing is sent for a quiet minute (except a small poll while the process
+  holds log lines, below), and what is left is sent when the process exits
+  (waiting at most 2 seconds; a Celery prefork child flushes at shutdown).
+- **Detail only on request.** When Dev Bench sees a fingerprint for the
+  first time it asks for evidence, and the SDK uploads the stack and one
+  example message, **templated and scrubbed first** (emails, numbers, quoted
+  values, tokens, card numbers, credentials and two-word names are removed).
+  Who was affected never goes into evidence.
+- **Never harms the app.** No network I/O on a request thread; 5-second
+  timeouts on the background thread, one retry, then the data is dropped;
+  memory is bounded (512 distinct problems per minute, the rest only
+  counted). Safe under forking servers (gunicorn, uWSGI, Celery prefork):
+  each process reports on its own.
+
+## Server log lines
+
+Triage reads the server's log lines for the user action that failed. The
+SDK keeps them itself, no sidecar:
+
+- **What:** every record that reaches the root logger's handlers while a
+  request or task carries a trace (`x-adt-trace` from the browser sensor; a
+  Celery task inherits the trace of the request that enqueued it). It sees
+  exactly what your logging configuration already lets through: it never
+  turns on a level you have off, writes nothing anywhere, and leaves your
+  handlers unchanged. A logger with `propagate = False` is not seen. An
+  exception's traceback is held one line each. Untraced records are not
+  kept.
+- **Bounded:** per process, the newest 10,000 lines or 4 MiB, nothing older
+  than 15 minutes, 4 KiB per line. A logging call never waits on I/O and
+  never raises because of this.
+- **Sent only when asked:** when Dev Bench asks for a trace, the flush
+  thread sends that trace's lines from this process (the newest ≤ 200 lines
+  / 64 KiB), **redacted first** with the same strict rules as evidence, plus
+  any redaction rules Dev Bench has learned for your app.
+- **Several processes:** each gunicorn worker and Celery process keeps and
+  answers for its own lines (a task's lines are in the worker, under the
+  trace of the request that enqueued it); Dev Bench assembles them.
+
+A plain WSGI/ASGI app without one of the integrations: `devbench.capture_logs()`.
+
+## Who was affected
+
+Set it once per request, after your authentication has run (a middleware
+after Django's `AuthenticationMiddleware`, a FastAPI dependency, a Flask
+`before_request`):
+
+```python
+devbench.set_user(email=request.user.email, account=request.user.account_id)
+```
+
+- `email` is trimmed and lowercased; `account` is your own tenant/customer
+  id, sent as a string. Both optional, each truncated to 255 characters.
+- It is sent in its own field with the counts, never inside a message or
+  evidence.
+- It ends with the request (a Celery task: with the task), so the next
+  request on the same thread never inherits it.
+
+## Reporting what you caught
+
+An exception you caught but want seen, like Sentry's `capture_exception`:
+
+```python
+except requests.RequestException as e:
+    devbench.capture_exception(e, symbol="billing.sync")
+    retry_later()
+```
+
+A failure you handled and turned into a normal response, the case this
+product exists for:
+
+```python
+except IntegrityError as e:
+    devbench.report_handled(e, symbol="customers.views.update", reason="uniqueness")
+    return JsonResponse({"ok": True})   # <- the user is about to be told this worked
+```
+
+`report_handled` also marks the response with `x-adt-handled: <count>` (and
+lists it in `Access-Control-Expose-Headers`, appending to what is there).
+The browser already knows whether the user was shown an error; this is the
+one fact it cannot know on its own. The header carries a count and nothing
+else, and it is added even when reporting is down.
+
+## Trace propagation
+
+The correlation id the browser sent (`x-adt-trace`) is `devbench.current_trace()`
+for the duration of the request. Forward it on outbound calls to other
+instrumented services:
+
+```python
+requests.post(url, json=body, headers=devbench.trace_headers())
+```
+
+## Not in this release
+
+- No sidecar transport: without a DSN nothing is sent.
+- `devbench.track` (custom events) and the chat widget's signed identity
+  are in the Ruby and Go SDKs; they come to Python later.