trailscope 0.1.0__py3-none-any.whl

trailscope/__init__.py

@@ -0,0 +1,55 @@
+"""Trailscope SDK for Python: non-blocking request logging for Django, ASGI apps and Celery."""
+
+from ._context import (
+    TrailscopeContext,
+    current_context,
+    deserialize_context,
+    record_error,
+    serialize_context,
+    set_attribute,
+    set_correlation,
+    set_user,
+    use_context,
+)
+from ._ids import format_traceparent, new_request_id, new_span_id, new_trace_id, parse_traceparent
+from ._redact import REDACTED, Redactor, mask_ip
+from ._version import __version__
+from .client import (
+    DEFAULT_IGNORE_ROUTES,
+    Client,
+    ClientStats,
+    HttpExchange,
+    JobScope,
+    get_client,
+    init,
+)
+from .handler import TrailscopeHandler
+
+__all__ = [
+    "DEFAULT_IGNORE_ROUTES",
+    "REDACTED",
+    "Client",
+    "ClientStats",
+    "HttpExchange",
+    "JobScope",
+    "Redactor",
+    "TrailscopeContext",
+    "TrailscopeHandler",
+    "__version__",
+    "current_context",
+    "deserialize_context",
+    "format_traceparent",
+    "get_client",
+    "init",
+    "mask_ip",
+    "new_request_id",
+    "new_span_id",
+    "new_trace_id",
+    "parse_traceparent",
+    "record_error",
+    "serialize_context",
+    "set_attribute",
+    "set_correlation",
+    "set_user",
+    "use_context",
+]

trailscope/_capture.py

@@ -0,0 +1,108 @@
+"""Body capture policy, serialization and truncation."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import Any, Literal
+
+BodyCapture = Literal["errors", "always", "never"]
+
+_BINARY_TYPES = (
+    "multipart/",
+    "application/octet-stream",
+    "image/",
+    "audio/",
+    "video/",
+    "font/",
+    "application/pdf",
+    "application/zip",
+    "application/gzip",
+    "application/x-protobuf",
+    "application/grpc",
+)
+
+
+def is_binary_content_type(content_type: str | None) -> bool:
+    """Whether a body with this content type should never be captured."""
+    if not content_type:
+        return False
+    return content_type.lower().startswith(_BINARY_TYPES)
+
+
+def should_capture_bodies(
+    policy: BodyCapture, status: int, duration_ms: float, slow_ms: float
+) -> bool:
+    if policy == "never":
+        return False
+    if policy == "always":
+        return True
+    return status >= 400 or duration_ms >= slow_ms
+
+
+def truncate(text: str, limit: int) -> tuple[str, bool]:
+    data = text.encode("utf-8")
+    if len(data) <= limit:
+        return text, False
+    # Cut at a byte boundary and drop a trailing partial character.
+    return data[:limit].decode("utf-8", errors="ignore"), True
+
+
+def serialize_body(value: Any, content_type: str | None, limit: int) -> tuple[str, bool] | None:
+    """Serializes a body-like value and truncates it to ``limit`` bytes.
+
+    Returns None for binary or empty bodies. Raw bodies of binary and multipart
+    requests are skipped; already parsed form fields (a dict) are kept.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (bytes, bytearray, memoryview, str)) and is_binary_content_type(
+        content_type
+    ):
+        return None
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        raw = bytes(value[: limit + 4])
+        if b"\x00" in raw[:512]:
+            return None
+        text = raw.decode("utf-8", errors="replace")
+        if len(value) > limit:
+            return truncate(text, limit)[0], True
+    elif isinstance(value, str):
+        text = value
+    else:
+        try:
+            text = json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))
+        except (TypeError, ValueError):
+            return None
+    if not text:
+        return None
+    return truncate(text, limit)
+
+
+def split_url(url: str) -> tuple[str, str]:
+    """``/a/b?x=1`` -> (``/a/b``, ``x=1``)."""
+    path, _, query = url.partition("?")
+    return path or "/", query
+
+
+def flatten_headers(
+    headers: Mapping[str, Any] | Iterable[tuple[str, Any]] | None,
+) -> dict[str, str]:
+    """Lower-cased names; repeated headers joined with ``, ``."""
+    out: dict[str, str] = {}
+    if headers is None:
+        return out
+    items = headers.items() if isinstance(headers, Mapping) else headers
+    for k, v in items:
+        if v is None:
+            continue
+        name = (k.decode("latin-1") if isinstance(k, bytes) else str(k)).lower()
+        val = (
+            v.decode("latin-1")
+            if isinstance(v, bytes)
+            else ", ".join(v)
+            if isinstance(v, list)
+            else str(v)
+        )
+        out[name] = f"{out[name]}, {val}" if name in out else val
+    return out

trailscope/_context.py

@@ -0,0 +1,125 @@
+"""Request-scoped context carried through threads and async tasks with contextvars."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import Any
+
+Scalar = str | int | float | bool
+
+
+@dataclass
+class TrailscopeContext:
+    request_id: str
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None = None
+    user_id: str | None = None
+    #: Journey keys, e.g. ``{"account_id": "acc_1"}``.
+    correlation: dict[str, str] = field(default_factory=dict)
+    attributes: dict[str, Scalar] = field(default_factory=dict)
+    #: Route pattern, once the framework has matched one.
+    route: str | None = None
+    #: The exception that failed the request, recorded by an error hook.
+    error: BaseException | None = None
+
+
+_current: ContextVar[TrailscopeContext | None] = ContextVar("trailscope_context", default=None)
+
+
+def current_context() -> TrailscopeContext | None:
+    return _current.get()
+
+
+def set_context(ctx: TrailscopeContext | None) -> Token[TrailscopeContext | None]:
+    return _current.set(ctx)
+
+
+def reset_context(token: Token[TrailscopeContext | None]) -> None:
+    try:
+        _current.reset(token)
+    except ValueError:
+        # Reset from another context (e.g. a generator finalized elsewhere).
+        _current.set(None)
+
+
+@contextmanager
+def use_context(ctx: TrailscopeContext) -> Iterator[TrailscopeContext]:
+    """Runs a block inside ``ctx``."""
+    token = _current.set(ctx)
+    try:
+        yield ctx
+    finally:
+        reset_context(token)
+
+
+def set_user(user_id: str | int | None) -> None:
+    """Attaches a user ID to the current request."""
+    ctx = _current.get()
+    if ctx is not None and user_id is not None and user_id != "":
+        ctx.user_id = str(user_id)
+
+
+def set_correlation(key: str, value: str | int) -> None:
+    """Adds a correlation (journey) key to the current request and everything it triggers."""
+    ctx = _current.get()
+    if ctx is not None and key:
+        ctx.correlation[key] = str(value)
+
+
+def set_attribute(key: str, value: Scalar) -> None:
+    """Adds a free-form attribute to the current request."""
+    ctx = _current.get()
+    if ctx is not None and key:
+        ctx.attributes[key] = value
+
+
+def record_error(error: BaseException, ctx: TrailscopeContext | None = None) -> None:
+    """Attaches the exception that failed the request (kept when the response is a 5xx)."""
+    ctx = ctx or _current.get()
+    if ctx is not None and ctx.error is None:
+        ctx.error = error
+
+
+def serialize_context(ctx: TrailscopeContext | None = None) -> dict[str, Any] | None:
+    """The part of a context that travels with a background job."""
+    ctx = ctx or _current.get()
+    if ctx is None:
+        return None
+    out: dict[str, Any] = {
+        "requestId": ctx.request_id,
+        "traceId": ctx.trace_id,
+        "spanId": ctx.span_id,
+    }
+    if ctx.user_id:
+        out["userId"] = ctx.user_id
+    if ctx.correlation:
+        out["correlation"] = dict(ctx.correlation)
+    return out
+
+
+def deserialize_context(value: object) -> dict[str, Any] | None:
+    """Validates a serialized context (from job data or message headers)."""
+    if not isinstance(value, dict):
+        return None
+
+    def s(key: str) -> str | None:
+        v = value.get(key)
+        return v if isinstance(v, str) and len(v) <= 128 else None
+
+    correlation: dict[str, str] = {}
+    raw = value.get("correlation")
+    if isinstance(raw, dict):
+        for k, v in raw.items():
+            if isinstance(k, str) and isinstance(v, (str, int)):
+                correlation[k] = str(v)
+    return {
+        "request_id": s("requestId"),
+        "trace_id": s("traceId"),
+        "span_id": s("spanId"),
+        "user_id": s("userId"),
+        "correlation": correlation,
+    }

trailscope/_ids.py

@@ -0,0 +1,56 @@
+"""Request, trace and span IDs, and W3C `traceparent`."""
+
+from __future__ import annotations
+
+import re
+import secrets
+import uuid
+from dataclasses import dataclass
+
+_TRACEPARENT = re.compile(r"^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$")
+_REQUEST_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+
+
+def new_request_id() -> str:
+    """32 hex characters, like the server's generated IDs."""
+    return uuid.uuid4().hex
+
+
+def new_trace_id() -> str:
+    return secrets.token_hex(16)
+
+
+def new_span_id() -> str:
+    return secrets.token_hex(8)
+
+
+@dataclass(frozen=True)
+class TraceParent:
+    trace_id: str
+    parent_span_id: str
+    sampled: bool
+
+
+def parse_traceparent(header: str | None) -> TraceParent | None:
+    """Parses a W3C `traceparent` header; None when it is missing or invalid."""
+    if not header:
+        return None
+    m = _TRACEPARENT.match(header.strip().lower())
+    if not m:
+        return None
+    version, trace_id, span_id, flags = m.groups()
+    if version == "ff" or set(trace_id) == {"0"} or set(span_id) == {"0"}:
+        return None
+    return TraceParent(trace_id, span_id, (int(flags, 16) & 1) == 1)
+
+
+def format_traceparent(trace_id: str, span_id: str, sampled: bool = True) -> str:
+    return f"00-{trace_id}-{span_id}-{'01' if sampled else '00'}"
+
+
+def accept_request_id(value: str | None) -> str | None:
+    """A client-provided request ID, only if it looks sane."""
+    if not value:
+        return None
+    v = value.strip()
+    return v if _REQUEST_ID.match(v) else None

trailscope/_redact.py

@@ -0,0 +1,168 @@
+"""Redaction of headers, bodies, query strings and IPs. Same rules as the Node SDK."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from re import Pattern
+from typing import Any
+from urllib.parse import unquote_plus
+
+REDACTED = "[REDACTED]"
+
+DEFAULT_REDACT_HEADERS = ("authorization", "cookie", "set-cookie", "x-api-key")
+
+DEFAULT_REDACT_KEYS = (
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "access_token",
+    "refresh_token",
+    "otp",
+    "pin",
+    "cvv",
+    "card",
+    "card_number",
+    "iban",
+    "ssn",
+)
+
+_IPV4 = re.compile(r"^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$")
+
+
+def _norm_key(k: str) -> str:
+    """``accessToken``, ``access-token`` and ``ACCESS_TOKEN`` all become ``accesstoken``."""
+    return k.replace("_", "").replace("-", "").lower()
+
+
+class Redactor:
+    def __init__(
+        self,
+        *,
+        headers: Iterable[str] = (),
+        keys: Iterable[str] = (),
+        patterns: Iterable[str | Pattern[str]] = (),
+        mask_ip: bool = True,
+        disable_defaults: bool = False,
+    ) -> None:
+        base_headers = () if disable_defaults else DEFAULT_REDACT_HEADERS
+        base_keys: list[str] = [] if disable_defaults else list(DEFAULT_REDACT_KEYS)
+        self._headers = {h.lower() for h in (*base_headers, *headers)}
+        self._paths: list[list[str]] = []
+        simple = list(base_keys)
+        for k in keys:
+            if "." in k:
+                self._paths.append([_norm_key(p) for p in k.split(".")])
+            elif k:
+                simple.append(k)
+        self._keys = {_norm_key(k) for k in simple}
+        self._patterns = [re.compile(p) if isinstance(p, str) else p for p in patterns]
+        self.mask_ip = mask_ip
+        self._raw_keys: Pattern[str] | None = None
+        if simple:
+            alts = "|".join("[_-]?".join(re.escape(part) for part in k.split("_")) for k in simple)
+            self._raw_keys = re.compile(
+                r'("(?:' + alts + r')"\s*:\s*)("(?:[^"\\]|\\.)*"?|[^,}\]\s]+)', re.IGNORECASE
+            )
+
+    def redact_headers(self, headers: Mapping[str, str]) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for name, value in headers.items():
+            lower = name.lower()
+            out[lower] = REDACTED if lower in self._headers else self.apply_patterns(value)
+        return out
+
+    def redact_body(self, body: str, content_type: str = "") -> str:
+        if not body:
+            return body
+        t = body.lstrip()
+        if t.startswith(("{", "[")):
+            try:
+                parsed = json.loads(body)
+            except ValueError:
+                return self._redact_raw_text(body)
+            return json.dumps(
+                self.redact_value(parsed, []), ensure_ascii=False, separators=(",", ":")
+            )
+        if "x-www-form-urlencoded" in content_type:
+            return self.redact_urlencoded(body)
+        return self._redact_raw_text(body)
+
+    def redact_urlencoded(self, s: str) -> str:
+        parts = []
+        for pair in s.split("&"):
+            k, sep, v = pair.partition("=")
+            if not sep:
+                parts.append(pair)
+                continue
+            try:
+                decoded = unquote_plus(k)
+            except Exception:
+                decoded = k
+            if _norm_key(decoded) in self._keys:
+                parts.append(f"{k}={REDACTED}")
+            else:
+                parts.append(f"{k}={self.apply_patterns(v)}")
+        return "&".join(parts)
+
+    def redact_query(self, q: str) -> str:
+        return self.redact_urlencoded(q.lstrip("?")) if q else q
+
+    def redact_value(self, v: Any, path: list[str]) -> Any:
+        """Redacts a structured value: JSON bodies and job payloads."""
+        if isinstance(v, list):
+            return [self.redact_value(item, [*path, "*"]) for item in v]
+        if isinstance(v, dict):
+            out: dict[str, Any] = {}
+            for k, child in v.items():
+                nk = _norm_key(str(k))
+                p = [*path, nk]
+                if (nk in self._keys or self._path_matches(p)) and child is not None:
+                    out[k] = REDACTED
+                else:
+                    out[k] = self.redact_value(child, p)
+            return out
+        if isinstance(v, str):
+            return self.apply_patterns(v)
+        return v
+
+    def apply_patterns(self, s: str) -> str:
+        for p in self._patterns:
+            s = p.sub(REDACTED, s)
+        return s
+
+    def ip(self, ip: str | None) -> str | None:
+        if not ip or not self.mask_ip:
+            return ip
+        return mask_ip(ip)
+
+    def _redact_raw_text(self, s: str) -> str:
+        if self._raw_keys is not None:
+            s = self._raw_keys.sub(lambda m: f'{m.group(1)}"{REDACTED}"', s)
+        return self.apply_patterns(s)
+
+    def _path_matches(self, path: list[str]) -> bool:
+        return any(
+            len(p) == len(path)
+            and all(
+                want == "*" or got == "*" or want == got for want, got in zip(p, path, strict=True)
+            )
+            for p in self._paths
+        )
+
+
+def mask_ip(raw: str) -> str:
+    """Zeroes the last IPv4 octet, or keeps the first 48 bits of an IPv6 address."""
+    ip = raw.strip()
+    if ip.startswith("::ffff:") and "." in ip:
+        ip = ip[7:]
+    m = _IPV4.match(ip)
+    if m:
+        return f"{m.group(1)}.{m.group(2)}.{m.group(3)}.0"
+    if ":" in ip:
+        head = ip.split("::")[0]
+        parts = [p for p in head.split(":") if p]
+        return ":".join(parts[:3]) + "::"
+    return ""

trailscope/_version.py

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