trailscope 0.1.0__py3-none-any.whl

trailscope/django.py

@@ -0,0 +1,204 @@
+"""Django middleware (WSGI and ASGI).
+
+Add it first in ``MIDDLEWARE`` and configure it in settings::
+
+    MIDDLEWARE = ["trailscope.django.TrailscopeMiddleware", ...]
+    TRAILSCOPE = {"service": "orders-api"}  # same keyword options as trailscope.Client
+
+Without a ``TRAILSCOPE`` setting it uses the client from an earlier
+``trailscope.init()``, or creates one from the ``TRAILSCOPE_*`` environment variables.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+
+from ._capture import is_binary_content_type, should_capture_bodies
+from ._context import TrailscopeContext, record_error, reset_context, set_context
+from .client import Client, HttpExchange, get_client, init, log
+
+_CONVERTER = re.compile(r"<(?:[^>:]+:)?([^>]+)>")
+_NAMED_GROUP = re.compile(r"\(\?P<([^>]+)>[^)]*\)")
+_CTX_ATTR = "_trailscope_context"
+
+
+def route_template(pattern: str) -> str:
+    """``projects/<int:project_id>/tasks`` -> ``/projects/:project_id/tasks``.
+
+    Regex routes (``re_path``) keep their literal parts, with named groups as
+    parameters.
+    """
+    p = _NAMED_GROUP.sub(r":\1", pattern)
+    p = _CONVERTER.sub(r":\1", p).replace("^", "").replace("$", "")
+    return "/" + p.lstrip("/")
+
+
+_settings_client: Client | None = None
+
+
+def _client_for_settings() -> Client:
+    """The client configured by ``settings.TRAILSCOPE``, created once per process."""
+    global _settings_client
+    from django.conf import settings
+
+    options = getattr(settings, "TRAILSCOPE", None)
+    if isinstance(options, dict) and options:
+        if _settings_client is None:
+            _settings_client = init(**options)
+        return _settings_client
+    return get_client() or init()
+
+
+def _user_id(request: Any) -> str | None:
+    """The authenticated user, only if Django already loaded it (no extra query)."""
+    user = getattr(request, "_cached_user", None) or getattr(request, "_acached_user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        pk = getattr(user, "pk", None)
+        return str(pk) if pk is not None else None
+    return None
+
+
+def _form_fields(request: Any) -> dict[str, Any] | None:
+    """A multipart form's text fields, with files listed by name, size and type
+    (never their content). Only if Django or DRF already parsed the form, so
+    logging never triggers parsing a large upload."""
+    post = getattr(request, "_post", None)
+    files = getattr(request, "_files", None)
+    out: dict[str, Any] = {}
+    if post is not None:
+        for key in post:
+            values = post.getlist(key)
+            out[key] = values[0] if len(values) == 1 else values
+    if files is not None:
+        for key in files:
+            listed = [
+                f"[file {f.name}, {f.size} bytes, {f.content_type}]" for f in files.getlist(key)
+            ]
+            out[key] = listed[0] if len(listed) == 1 else listed
+    return out or None
+
+
+def _request_body(request: Any, client: Client) -> bytes | dict[str, Any] | None:
+    content_type = request.META.get("CONTENT_TYPE", "")
+    if content_type.startswith("multipart/form-data"):
+        return _form_fields(request)
+    if is_binary_content_type(content_type):
+        return None
+    try:
+        body = request.body
+    except Exception:  # streamed already, or over DATA_UPLOAD_MAX_MEMORY_SIZE
+        return None
+    return bytes(body[: client.max_body_bytes + 1]) if body else None
+
+
+def _response_body(response: Any, client: Client) -> bytes | None:
+    if getattr(response, "streaming", False):
+        return None
+    try:
+        content = response.content
+    except Exception:
+        return None
+    return bytes(content[: client.max_body_bytes + 1]) if content else None
+
+
+class TrailscopeMiddleware:
+    sync_capable = True
+    async_capable = True
+
+    def __init__(self, get_response: Callable[[Any], Any]) -> None:
+        self.get_response = get_response
+        self.client = _client_for_settings()
+        self._async = iscoroutinefunction(get_response)
+        if self._async:
+            markcoroutinefunction(self)
+
+    def __call__(self, request: Any) -> Any:
+        if self._async:
+            return self.__acall__(request)
+        if not self.client.enabled:
+            return self.get_response(request)
+        ctx, token, timestamp, t0 = self._start(request)
+        try:
+            response = self.get_response(request)
+        except Exception as e:
+            record_error(e, ctx)
+            reset_context(token)
+            raise
+        self._finish(request, response, ctx, timestamp, t0)
+        reset_context(token)
+        return response
+
+    async def __acall__(self, request: Any) -> Any:
+        get_response: Callable[[Any], Awaitable[Any]] = self.get_response
+        if not self.client.enabled:
+            return await get_response(request)
+        ctx, token, timestamp, t0 = self._start(request)
+        try:
+            response = await get_response(request)
+        except Exception as e:
+            record_error(e, ctx)
+            reset_context(token)
+            raise
+        self._finish(request, response, ctx, timestamp, t0)
+        reset_context(token)
+        return response
+
+    def process_exception(self, request: Any, exception: Exception) -> None:
+        """Called by Django for exceptions raised in views, before the 500 response."""
+        record_error(exception, getattr(request, _CTX_ATTR, None))
+
+    def _start(self, request: Any) -> tuple[TrailscopeContext, Any, float, float]:
+        headers = request.headers
+        ctx = self.client.context_from_headers(lambda name: headers.get(name))
+        setattr(request, _CTX_ATTR, ctx)
+        return ctx, set_context(ctx), time.time() * 1000, time.perf_counter()
+
+    def _finish(
+        self, request: Any, response: Any, ctx: TrailscopeContext, timestamp: float, t0: float
+    ) -> None:
+        client = self.client
+        try:
+            if not response.has_header(client.request_id_header):
+                response[client.request_id_header] = ctx.request_id
+            match = getattr(request, "resolver_match", None)
+            route = getattr(match, "route", None)
+            if ctx.user_id is None:
+                ctx.user_id = _user_id(request)
+            meta = request.META
+            xff = meta.get("HTTP_X_FORWARDED_FOR")
+            ip = xff.split(",")[0].strip() if xff else meta.get("REMOTE_ADDR")
+            res_headers = dict(response.headers.items())
+            length = res_headers.get("Content-Length")
+            duration_ms = (time.perf_counter() - t0) * 1000
+            status = int(response.status_code)
+            # Read bodies only when the capture policy keeps them.
+            bodies = should_capture_bodies(
+                client.capture_bodies, status, duration_ms, client.slow_ms
+            )
+            client.record_http(
+                ctx,
+                HttpExchange(
+                    timestamp=timestamp,
+                    duration_ms=duration_ms,
+                    method=request.method or "GET",
+                    url=request.get_full_path(),
+                    status=status,
+                    route=route_template(route) if isinstance(route, str) else None,
+                    req_headers=dict(request.headers.items()),
+                    res_headers=res_headers,
+                    req_body=_request_body(request, client) if bodies else None,
+                    res_body=_response_body(response, client) if bodies else None,
+                    ip=ip or None,
+                    req_size=int(meta["CONTENT_LENGTH"])
+                    if str(meta.get("CONTENT_LENGTH", "")).isdigit()
+                    else None,
+                    res_size=int(length) if length and str(length).isdigit() else None,
+                ),
+            )
+        except Exception:
+            log.exception("trailscope: could not record request")

trailscope/handler.py

@@ -0,0 +1,49 @@
+"""A ``logging`` handler that sends records to Trailscope as ``log`` events."""
+
+from __future__ import annotations
+
+import logging
+
+from .client import Client, Level, get_client
+
+_LEVELS: tuple[tuple[int, Level], ...] = (
+    (logging.ERROR, "error"),
+    (logging.WARNING, "warn"),
+    (logging.INFO, "info"),
+)
+
+
+class TrailscopeHandler(logging.Handler):
+    """Sends log records to Trailscope, linked to the current request or job.
+
+    ::
+
+        logging.getLogger().addHandler(TrailscopeHandler(level=logging.INFO))
+
+    The record's logger name becomes the event name, ``exc_info`` becomes the
+    error type, message and stack, and records from Trailscope's own logger are
+    skipped.
+    """
+
+    def __init__(self, level: int = logging.INFO, client: Client | None = None) -> None:
+        super().__init__(level)
+        self._client = client
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.name == "trailscope" or record.name.startswith("trailscope."):
+            return
+        client = self._client or get_client()
+        if client is None:
+            return
+        try:
+            level: Level = next((name for no, name in _LEVELS if record.levelno >= no), "debug")
+            error = record.exc_info[1] if record.exc_info and record.exc_info[1] else None
+            client.log(
+                level,
+                record.getMessage(),
+                name=record.name,
+                attributes={"module": record.module, "line": record.lineno},
+                error=error,
+            )
+        except Exception:
+            self.handleError(record)

trailscope-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: trailscope
+Version: 0.1.0
+Summary: Trailscope SDK for Python: non-blocking API request logging for Django, FastAPI/Starlette and Celery
+Project-URL: Homepage, https://trailscope.pro
+Project-URL: Source, https://github.com/karaa1122/trailscope
+Project-URL: Documentation, https://trailscope.pro/docs/sdk-python/
+Author: Trailscope contributors
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: celery>=5.6; extra == 'dev'
+Requires-Dist: django<6,>=5.2; (python_version < '3.12') and extra == 'dev'
+Requires-Dist: django>=6.1; (python_version >= '3.12') and extra == 'dev'
+Requires-Dist: fastapi>=0.162; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: mypy>=2.4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4; extra == 'dev'
+Requires-Dist: pytest>=9.1; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: starlette<1.9,>=1.0; (python_version < '3.11') and extra == 'dev'
+Requires-Dist: starlette>=1.9; (python_version >= '3.11') and extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.37; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# trailscope
+
+The [Trailscope](https://github.com/karaa1122/trailscope) SDK for Python 3.10+: logs every request with its route, timing, user, journey keys and (on errors) bodies and stack, plus Celery jobs and log lines, without blocking your request path. No dependencies beyond the standard library.
+
+```bash
+pip install trailscope
+```
+
+## FastAPI / Starlette
+
+```python
+import trailscope
+from trailscope.asgi import TrailscopeMiddleware
+
+trailscope.init(service="orders-api")  # reads TRAILSCOPE_ENDPOINT and TRAILSCOPE_INGEST_KEY
+app = FastAPI()
+app.add_middleware(TrailscopeMiddleware)  # add it last, so it runs first
+```
+
+## Django
+
+```python
+MIDDLEWARE = ["trailscope.django.TrailscopeMiddleware", ...]  # first
+TRAILSCOPE = {"service": "orders-api"}
+```
+
+## Celery and logging
+
+```python
+from trailscope.celery import instrument
+
+instrument()  # in the web process and the worker, after trailscope.init()
+logging.getLogger().addHandler(trailscope.TrailscopeHandler())
+```
+
+In request code: `trailscope.set_user(user_id)`, `trailscope.set_correlation("order_id", order_id)`.
+
+Full documentation: [docs/sdk-python.md](https://github.com/karaa1122/trailscope/blob/main/docs/sdk-python.md).
+
+## License
+
+Apache-2.0

trailscope-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+trailscope/__init__.py,sha256=AHPbiMXfmrsuH7etVMnVFO9kZ6XukuJ-FVm4gsOlESQ,1208
+trailscope/_capture.py,sha256=M_YVVJsrpNcxemBhktSk7sufZV8GGQp-QEGGW5KfDsA,3264
+trailscope/_context.py,sha256=0BpnXO40rUMExI1IDpXOQMZ3q19OXOWCtFVndushQps,3881
+trailscope/_ids.py,sha256=p8Sp7Fs36pvFePEFKJPC15tSHsIDYpMOAtbWsS5ju64,1524
+trailscope/_redact.py,sha256=V7Ro8Tf3UjsaGJan00QYG2yaLzsaRcsmyTdf2lHwnjk,5581
+trailscope/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+trailscope/asgi.py,sha256=jfeTQt7ZEjbaN2d8OT87W9uLGaj8_c3YwZszgu0Sfv4,6983
+trailscope/celery.py,sha256=cHumr1bGfRYINdGxYfKx_xOuK9l0QG9XY3fLc3Dqf9s,4617
+trailscope/client.py,sha256=0tlTlPO2e3CPFsyG6_zD6mmu-tavHKEG_723rJJrFGo,32558
+trailscope/django.py,sha256=28of7_BbithbL3_vVODOnilv9Gb70BbvWH2xtmhUvFM,7978
+trailscope/handler.py,sha256=riAZhYvKVrwPK5xCZUNHvc2OwGSH_WxP2Ma4RC59fK4,1605
+trailscope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trailscope-0.1.0.dist-info/METADATA,sha256=DX9IdHpLFL8KcB58fMOp9HcFQSfX-eYq80as0ZgVaSU,2883
+trailscope-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+trailscope-0.1.0.dist-info/RECORD,,

trailscope-0.1.0.dist-info/WHEEL

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