logsetu 0.3.0__py3-none-any.whl

logsetu/handler.py

@@ -0,0 +1,191 @@
+"""``logging.Handler`` that ships records to LogSetu.
+
+Configure it through Django's ``LOGGING`` dict (or ``logging.config.dictConfig``)::
+
+    "handlers": {
+        "logsetu": {
+            "class": "logsetu.handler.LogSetuHandler",
+            "api_key": env("LOGSETU_API_KEY"),
+            "endpoint": env("LOGSETU_ENDPOINT"),
+            "environment": "production",
+            "source": "django-backend",
+            "level": "WARNING",
+            # optional:
+            # "get_tenant_id": "myapp.tenants.get_tenant_id",
+        },
+    },
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional, Union
+
+from .client import LogSetuClient, get_client
+from .conf import TenantGetter, django_settings, import_callable
+from .context import get_request_context
+
+LEVEL_MAP = {
+    logging.DEBUG: "debug",
+    logging.INFO: "info",
+    logging.WARNING: "warn",
+    logging.ERROR: "error",
+    logging.CRITICAL: "fatal",
+}
+
+# Attributes every LogRecord has; anything else came from ``extra=`` and is forwarded as meta.
+_STANDARD_ATTRS = frozenset(
+    {
+        "name", "msg", "args", "levelname", "levelno", "pathname", "filename", "module", "exc_info", "exc_text",
+        "stack_info", "lineno", "funcName", "created", "msecs", "relativeCreated", "thread", "threadName",
+        "processName", "process", "message", "asctime", "taskName",
+    }
+)
+
+
+def level_name(levelno: int) -> str:
+    if levelno >= logging.CRITICAL:
+        return "fatal"
+    if levelno >= logging.ERROR:
+        return "error"
+    if levelno >= logging.WARNING:
+        return "warn"
+    if levelno >= logging.INFO:
+        return "info"
+    return "debug"
+
+
+class LogSetuHandler(logging.Handler):
+    """Send Python logging records to a LogSetu server, batched on a background thread."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        *,
+        environment: Optional[str] = None,
+        source: Optional[str] = None,
+        level: Union[int, str] = logging.NOTSET,
+        get_tenant_id: Union[str, TenantGetter, None] = None,
+        include_extra: bool = True,
+        include_request_context: bool = True,
+        flush_interval: float = 2.0,
+        batch_size: int = 10,
+        max_queue_size: int = 1000,
+        max_retries: int = 3,
+        timeout: float = 5.0,
+        debug: bool = False,
+        client: Optional[LogSetuClient] = None,
+    ) -> None:
+        super().__init__(level)
+        cfg = django_settings()
+        self.api_key = api_key or cfg.get("API_KEY") or ""
+        self.endpoint = endpoint or cfg.get("ENDPOINT") or ""
+        self.environment = environment or cfg.get("ENVIRONMENT") or "production"
+        self.source = source or cfg.get("SOURCE") or "django"
+        self.include_extra = include_extra
+        self.include_request_context = include_request_context
+        self.get_tenant_id: Optional[Callable[[Any], Optional[str]]] = import_callable(
+            get_tenant_id or cfg.get("GET_TENANT_ID")
+        )
+        self.client = client or get_client(
+            self.api_key,
+            self.endpoint,
+            environment=self.environment,
+            source=self.source,
+            flush_interval=flush_interval,
+            batch_size=batch_size,
+            max_queue_size=max_queue_size,
+            max_retries=max_retries,
+            timeout=timeout,
+            debug=bool(debug or cfg.get("DEBUG", False)),
+        )
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            # Django's own ``django.request`` logger re-logs 5xx responses; skip those the
+            # middleware already reported with richer context.
+            req = record.__dict__.get("request")
+            if req is not None and getattr(req, "_logsetu_reported", False):
+                return
+            # Same for Flask's "Exception on /path" and uvicorn's "Exception in ASGI application".
+            if record.exc_info and getattr(record.exc_info[1], "_logsetu_reported", False):
+                return
+            self.client.enqueue(self.build_entry(record))
+        except Exception:
+            self.handleError(record)
+
+    def build_entry(self, record: logging.LogRecord) -> Dict[str, Any]:
+        meta: Dict[str, Any] = {
+            "logger": record.name,
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+            "process": record.process,
+            "thread": record.threadName,
+        }
+        if record.exc_info:
+            exc_type = record.exc_info[0]
+            meta["exception"] = exc_type.__name__ if exc_type else None
+            if not record.exc_text:
+                record.exc_text = logging.Formatter().formatException(record.exc_info)
+        if record.exc_text:
+            meta["stack"] = record.exc_text
+        if record.stack_info:
+            meta["stack_info"] = record.stack_info
+        if self.include_extra:
+            for key, value in record.__dict__.items():
+                if key not in _STANDARD_ATTRS and not key.startswith("_") and key not in meta:
+                    meta[key] = _summarize_request(value) if key == "request" else value
+        if self.include_request_context:
+            ctx = get_request_context()
+            if ctx:
+                meta["request"] = ctx
+                if "tenant_id" in ctx and "tenant_id" not in meta:
+                    meta["tenant_id"] = ctx["tenant_id"]
+        # Allow logger.info("...", extra={"source": "celery"}) to override per-record.
+        source = meta.pop("source", None) or self.source
+        environment = meta.pop("environment", None) or self.environment
+        return {
+            "level": level_name(record.levelno),
+            "message": self.format_message(record),
+            "source": str(source),
+            "environment": str(environment),
+            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "meta": _json_safe(meta),
+        }
+
+    def format_message(self, record: logging.LogRecord) -> str:
+        try:
+            msg = record.getMessage()
+        except Exception:
+            msg = str(record.msg)
+        return msg[:10_000]
+
+    def flush(self) -> None:
+        self.client.flush(timeout=5.0)
+
+    def close(self) -> None:
+        try:
+            self.client.flush(timeout=5.0)
+        finally:
+            super().close()
+
+
+def _summarize_request(value: Any) -> Any:
+    """``extra={"request": HttpRequest}`` (as Django does) → a small dict instead of a repr."""
+    meta = getattr(value, "META", None)
+    if not isinstance(meta, dict):
+        return value
+    return {
+        "method": getattr(value, "method", None),
+        "path": getattr(value, "path", None),
+        "query": meta.get("QUERY_STRING", "")[:2000],
+    }
+
+
+def _json_safe(meta: Dict[str, Any]) -> Dict[str, Any]:
+    from .client import to_json_safe
+
+    return {k: to_json_safe(v) for k, v in meta.items() if v is not None}

logsetu/middleware.py

@@ -0,0 +1,186 @@
+"""Django middleware: attaches request context to every log and reports unhandled exceptions.
+
+Add it to ``MIDDLEWARE`` (after ``AuthenticationMiddleware`` if you want user ids)::
+
+    MIDDLEWARE = [..., "logsetu.middleware.LogSetuMiddleware"]
+
+It reuses the client of a configured ``LogSetuHandler``; alternatively configure it directly::
+
+    LOGSETU = {
+        "API_KEY": env("LOGSETU_API_KEY"),
+        "ENDPOINT": env("LOGSETU_ENDPOINT"),
+        "ENVIRONMENT": "production",
+        "SOURCE": "django-backend",
+        "GET_TENANT_ID": "myapp.tenants.get_tenant_id",   # callable(request) -> str | None
+        "REDACT_HEADERS": ["authorization", "cookie"],     # default list already covers the usual suspects
+        "CAPTURE_5XX": True,                                # also log responses with status >= 500 that didn't raise
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+import uuid
+from typing import Any, Callable, Dict, Optional
+
+from django.utils.deprecation import MiddlewareMixin
+
+from .client import LogSetuClient, get_client
+from .conf import DEFAULT_REDACT_HEADERS, django_settings, import_callable
+from .context import get_request_context, reset_request_context, set_request_context
+from .handler import LogSetuHandler
+
+
+def _find_handler() -> Optional[LogSetuHandler]:
+    """The first LogSetuHandler attached to any configured logger (root first)."""
+    loggers = [logging.getLogger()] + [
+        lg for lg in logging.Logger.manager.loggerDict.values() if isinstance(lg, logging.Logger)
+    ]
+    for lg in loggers:
+        for h in lg.handlers:
+            if isinstance(h, LogSetuHandler):
+                return h
+    return None
+
+
+class LogSetuMiddleware(MiddlewareMixin):
+    """Capture request metadata for every log line and report unhandled exceptions with full context."""
+
+    def __init__(self, get_response: Callable[..., Any]) -> None:
+        super().__init__(get_response)
+        cfg = django_settings()
+        handler = _find_handler()
+        self.client: LogSetuClient = (
+            handler.client
+            if handler is not None
+            else get_client(
+                cfg.get("API_KEY", ""),
+                cfg.get("ENDPOINT", ""),
+                environment=cfg.get("ENVIRONMENT", "production"),
+                source=cfg.get("SOURCE", "django"),
+                debug=bool(cfg.get("DEBUG", False)),
+            )
+        )
+        self.source: str = cfg.get("SOURCE") or (handler.source if handler else "django")
+        self.environment: str = cfg.get("ENVIRONMENT") or (handler.environment if handler else "production")
+        self.get_tenant_id = import_callable(cfg.get("GET_TENANT_ID")) or (handler.get_tenant_id if handler else None)
+        self.redact_headers = {h.lower() for h in cfg.get("REDACT_HEADERS", DEFAULT_REDACT_HEADERS)}
+        self.capture_5xx: bool = bool(cfg.get("CAPTURE_5XX", True))
+
+    # ---------- request lifecycle ----------
+
+    def process_request(self, request: Any) -> None:
+        ctx: Dict[str, Any] = {
+            "request_id": request.META.get("HTTP_X_REQUEST_ID") or uuid.uuid4().hex[:16],
+            "method": request.method,
+            "path": request.path,
+        }
+        ip = self._client_ip(request)
+        if ip:
+            ctx["ip"] = ip
+        tenant = self._tenant(request)
+        if tenant is not None:
+            ctx["tenant_id"] = tenant
+        request._logsetu_token = set_request_context(ctx)  # noqa: SLF001
+        request.logsetu_request_id = ctx["request_id"]
+
+    def process_response(self, request: Any, response: Any) -> Any:
+        try:
+            status = getattr(response, "status_code", 0)
+            if self.capture_5xx and status >= 500 and not getattr(request, "_logsetu_reported", False):
+                self._report(
+                    request,
+                    level="error",
+                    message=f"HTTP {status} on {request.method} {request.path}",
+                    extra={"status": status},
+                )
+                request._logsetu_reported = True  # noqa: SLF001
+        finally:
+            token = getattr(request, "_logsetu_token", None)
+            if token is not None:
+                reset_request_context(token)
+        return response
+
+    def process_exception(self, request: Any, exception: BaseException) -> None:
+        stack = "".join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+        self._report(
+            request,
+            level="error",
+            message=f"{type(exception).__name__}: {exception}",
+            extra={"exception": type(exception).__name__, "stack": stack},
+        )
+        request._logsetu_reported = True  # noqa: SLF001
+        return None  # let Django produce the 500 response as usual
+
+    # ---------- helpers ----------
+
+    def _report(self, request: Any, *, level: str, message: str, extra: Dict[str, Any]) -> None:
+        try:
+            meta: Dict[str, Any] = {**get_request_context(), **extra, "request": self.request_info(request)}
+            user = self.user_info(request)
+            if user:
+                meta["user"] = user
+            self.client.log(level, message, meta, source=self.source, environment=self.environment)
+        except Exception:  # never break the response cycle
+            pass
+
+    def request_info(self, request: Any) -> Dict[str, Any]:
+        info: Dict[str, Any] = {
+            "method": request.method,
+            "path": request.path,
+            "query": request.META.get("QUERY_STRING", "")[:2000],
+            "headers": self.redacted_headers(request),
+        }
+        ip = self._client_ip(request)
+        if ip:
+            info["ip"] = ip
+        try:
+            view = request.resolver_match.view_name if request.resolver_match else None
+            if view:
+                info["view"] = view
+        except Exception:
+            pass
+        return info
+
+    def redacted_headers(self, request: Any) -> Dict[str, str]:
+        out: Dict[str, str] = {}
+        headers = getattr(request, "headers", None)
+        items = headers.items() if headers is not None else (
+            (k[5:].replace("_", "-"), v) for k, v in request.META.items() if k.startswith("HTTP_")
+        )
+        for name, value in items:
+            key = str(name).lower()
+            out[key] = "[REDACTED]" if key in self.redact_headers else str(value)[:500]
+        return out
+
+    def user_info(self, request: Any) -> Optional[Dict[str, Any]]:
+        user = getattr(request, "user", None)
+        if user is None:
+            return None
+        try:
+            if not getattr(user, "is_authenticated", False):
+                return None
+            info: Dict[str, Any] = {"id": getattr(user, "pk", None)}
+            username = getattr(user, "get_username", None)
+            if callable(username):
+                info["username"] = username()
+            return info
+        except Exception:
+            return None
+
+    def _tenant(self, request: Any) -> Optional[str]:
+        if self.get_tenant_id is None:
+            return None
+        try:
+            value = self.get_tenant_id(request)
+            return None if value is None else str(value)
+        except Exception:
+            return None
+
+    @staticmethod
+    def _client_ip(request: Any) -> Optional[str]:
+        forwarded = request.META.get("HTTP_X_FORWARDED_FOR")
+        if forwarded:
+            return forwarded.split(",")[0].strip()
+        return request.META.get("REMOTE_ADDR")

logsetu/web.py

@@ -0,0 +1,71 @@
+"""Framework-neutral helpers shared by the Flask and ASGI (FastAPI / Starlette) integrations."""
+
+from __future__ import annotations
+
+import logging
+import traceback
+import uuid
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from .client import LogSetuClient, get_client
+from .conf import DEFAULT_REDACT_HEADERS
+from .handler import LogSetuHandler
+
+
+def make_client(
+    api_key: Optional[str],
+    endpoint: Optional[str],
+    *,
+    environment: str,
+    source: str,
+    debug: bool = False,
+    client: Optional[LogSetuClient] = None,
+) -> LogSetuClient:
+    if client is not None:
+        return client
+    return get_client(api_key or "", endpoint or "", environment=environment, source=source, debug=debug)
+
+
+def attach_handler(client: LogSetuClient, level: int, logger: Optional[logging.Logger] = None) -> LogSetuHandler:
+    """Attach a ``LogSetuHandler`` sharing *client* to *logger* (root by default), once."""
+    target = logger or logging.getLogger()
+    for h in target.handlers:
+        if isinstance(h, LogSetuHandler) and h.client is client:
+            return h
+    handler = LogSetuHandler(client.api_key, client.endpoint, environment=client.environment, source=client.source,
+                             level=level, client=client)
+    target.addHandler(handler)
+    if target.level == logging.NOTSET or target.level > level:
+        target.setLevel(level)
+    return handler
+
+
+def request_id(headers: Dict[str, str]) -> str:
+    return headers.get("x-request-id") or uuid.uuid4().hex[:16]
+
+
+def client_ip(headers: Dict[str, str], remote_addr: Optional[str]) -> Optional[str]:
+    forwarded = headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return remote_addr
+
+
+def redact(headers: Iterable[Tuple[str, str]], redact_headers: Iterable[str] = DEFAULT_REDACT_HEADERS) -> Dict[str, str]:
+    hidden = {h.lower() for h in redact_headers}
+    return {k.lower(): ("[REDACTED]" if k.lower() in hidden else str(v)[:500]) for k, v in headers}
+
+
+def mark_reported(exc: BaseException) -> None:
+    """Flag *exc* so ``LogSetuHandler`` drops the framework's own log record for it (no duplicates)."""
+    try:
+        exc._logsetu_reported = True  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - exceptions with __slots__
+        pass
+
+
+def exception_meta(exc: BaseException) -> Dict[str, Any]:
+    return {
+        "exception": type(exc).__name__,
+        "stack": "".join(traceback.format_exception(type(exc), exc, exc.__traceback__)),
+    }

logsetu-0.3.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: logsetu
+Version: 0.3.0
+Summary: LogSetu SDK for Python — Django, DRF, Flask and FastAPI: ship logging records and request errors to your self-hosted LogSetu server
+Project-URL: Homepage, https://github.com/itsrajverma/logsetu
+Project-URL: Documentation, https://github.com/itsrajverma/logsetu/tree/main/docs
+Project-URL: Repository, https://github.com/itsrajverma/logsetu
+Project-URL: Issues, https://github.com/itsrajverma/logsetu/issues
+Author: Raj Verma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,django,drf,error-tracking,fastapi,flask,logging,logsetu,python,self-hosted,sentry-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: django>=3.2; extra == 'dev'
+Requires-Dist: fastapi>=0.95; extra == 'dev'
+Requires-Dist: flask>=2.2; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.2; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# logsetu (Python)
+
+Ship Django / DRF, **Flask** and **FastAPI** logs and unhandled errors to your self-hosted [LogSetu](https://github.com/itsrajverma/logsetu) server.
+Zero runtime dependencies, non-blocking (background thread + batching), and it never crashes your app if the log server is down.
+
+```bash
+pip install "logsetu[django]"    # Django / DRF
+pip install "logsetu[flask]"     # Flask
+pip install "logsetu[fastapi]"   # FastAPI / Starlette / any ASGI app
+pip install logsetu              # just the client + logging handler (zero dependencies)
+```
+
+The extras only pull in the framework itself; the SDK has no runtime dependencies. Integrations:
+[Django](#setup-2-minutes), [Flask](#flask) and [FastAPI / any ASGI app](#fastapi--starlette--asgi).
+
+> **Coming from `logsetu-django`?** The package was renamed to `logsetu` in 0.3.0. The import name (`import logsetu`)
+> and all settings are unchanged. Switch with `pip uninstall -y logsetu-django && pip install "logsetu[django]"` and
+> update your requirements file. Don't keep both installed: they contain the same `logsetu` module. `logsetu-django`
+> is still published with identical code for existing installs.
+
+## Setup (2 minutes)
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "logsetu"]  # optional, but nice for discoverability
+
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "handlers": {
+        "logsetu": {
+            "class": "logsetu.handler.LogSetuHandler",
+            "api_key": env("LOGSETU_API_KEY"),        # from the LogSetu dashboard → Projects
+            "endpoint": env("LOGSETU_ENDPOINT"),      # e.g. https://logs.example.com
+            "environment": env("ENVIRONMENT", default="production"),
+            "source": "django-backend",
+            "level": "WARNING",
+        },
+    },
+    "root": {"handlers": ["logsetu"], "level": "INFO"},
+}
+
+MIDDLEWARE = [
+    ...,
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "logsetu.middleware.LogSetuMiddleware",   # after auth middleware so user ids are captured
+]
+```
+
+That's it. Every `logging` call at or above the handler's level is sent to LogSetu, and the middleware
+reports unhandled exceptions (and 5xx responses) with the request path, method, view, user, redacted headers and full traceback.
+
+```python
+import logging
+log = logging.getLogger(__name__)
+
+log.warning("Checkout is slow", extra={"duration_ms": 1830, "cart_items": 12})
+try:
+    charge(card)
+except PaymentError:
+    log.exception("Payment failed")          # traceback is attached automatically
+```
+
+## Multi-tenant apps
+
+Tag every log with the current tenant by pointing the SDK at a callable `(request) -> str | None`:
+
+```python
+# settings.py
+LOGGING["handlers"]["logsetu"]["get_tenant_id"] = "myapp.tenants.get_tenant_id"
+
+# myapp/tenants.py
+def get_tenant_id(request):
+    return getattr(request, "tenant", None) and request.tenant.slug
+```
+
+Or, from anywhere inside a request (e.g. after you resolve the tenant in your own middleware):
+
+```python
+from logsetu import update_request_context
+update_request_context(tenant_id=tenant.slug, plan=tenant.plan)
+```
+
+## Handler options
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` / `endpoint` | — | Required (or set `LOGSETU = {"API_KEY": ..., "ENDPOINT": ...}` in settings) |
+| `environment` | `"production"` | Tag on every log |
+| `source` | `"django"` | Tag on every log; override per record with `extra={"source": "celery"}` |
+| `get_tenant_id` | `None` | Dotted path or callable `(request) -> str` |
+| `include_extra` | `True` | Forward `extra={...}` fields as metadata |
+| `include_request_context` | `True` | Attach request id / path / method / tenant set by the middleware |
+| `flush_interval` | `2.0` | Seconds between background flushes |
+| `batch_size` | `10` | Flush as soon as this many logs are queued |
+| `max_queue_size` | `1000` | Drop oldest logs beyond this |
+| `max_retries` | `3` | Retries with exponential backoff on 5xx / network errors |
+| `timeout` | `5.0` | HTTP timeout in seconds |
+| `debug` | `False` | Print every transport failure to stderr (otherwise only the first) |
+
+## Middleware options (`settings.LOGSETU`)
+
+The middleware reuses the client and options of a configured `LogSetuHandler`. Without a handler it can run standalone:
+
+```python
+LOGSETU = {
+    "API_KEY": env("LOGSETU_API_KEY"),
+    "ENDPOINT": env("LOGSETU_ENDPOINT"),
+    "ENVIRONMENT": "production",
+    "SOURCE": "django-backend",
+    "GET_TENANT_ID": "myapp.tenants.get_tenant_id",
+    "REDACT_HEADERS": ["authorization", "cookie", "x-api-key"],  # defaults already cover these
+    "CAPTURE_5XX": True,   # also report 5xx responses that didn't raise
+}
+```
+
+Every request gets a `request_id` (taken from `X-Request-ID` if present, otherwise generated) which is
+attached to all logs emitted during that request and exposed as `request.logsetu_request_id`.
+
+## Guarantees
+
+- **Never blocks** the request cycle: `emit()` only appends to an in-memory queue.
+- **Never raises** into your app: transport errors are printed once to stderr, then suppressed.
+- **Never leaks secrets**: `Authorization`, `Cookie`, `X-Api-Key`, `X-CSRFToken` and `Proxy-Authorization` are redacted.
+- **Never loses the last logs** on shutdown: the queue is flushed via `atexit`.
+
+## Celery / management commands
+
+Nothing special — the handler works anywhere Python's `logging` does. Set `extra={"source": "celery"}` to distinguish
+workers, or configure a second handler with a different `source`.
+
+## Flask
+
+```python
+import os
+from flask import Flask
+from logsetu.flask import LogSetu
+
+app = Flask(__name__)
+LogSetu(app, api_key=os.environ["LOGSETU_API_KEY"], endpoint=os.environ["LOGSETU_ENDPOINT"], source="flask-api")
+```
+
+App factory? Create `logsetu = LogSetu()` at module level and call `logsetu.init_app(app)`; options you don't pass are
+read from `app.config` (`LOGSETU_API_KEY`, `LOGSETU_ENDPOINT`, `LOGSETU_ENVIRONMENT`, `LOGSETU_SOURCE`).
+
+The extension reports unhandled exceptions and 5xx responses (route, endpoint, redacted headers, traceback), and attaches
+a `LogSetuHandler` to the root logger so `logging.warning(...)` and above is shipped with the request id, method and
+path of the current request. Flask's own `"Exception on /path"` log line is de-duplicated.
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` / `endpoint` | `app.config` | Project API key and server URL |
+| `environment` / `source` | `"production"` / `"flask"` | Tags on every log |
+| `get_tenant_id` | — | `callable(request) -> str \| None` or dotted path |
+| `capture_logging` | `True` | Attach a handler to the root logger |
+| `log_level` | `logging.WARNING` | Minimum level forwarded from `logging` |
+| `capture_5xx` | `True` | Report 5xx responses that didn't raise |
+| `log_requests` | `False` | One info/warn log per request |
+| `redact_headers` | auth / cookie / API-key headers | Header names replaced by `[REDACTED]` |
+| `client` | — | Use an existing `LogSetuClient` |
+
+## FastAPI / Starlette / ASGI
+
+```python
+import os
+from fastapi import FastAPI
+from logsetu.fastapi import LogSetuMiddleware   # alias of logsetu.asgi — works with any ASGI app
+
+app = FastAPI()
+app.add_middleware(
+    LogSetuMiddleware,
+    api_key=os.environ["LOGSETU_API_KEY"],
+    endpoint=os.environ["LOGSETU_ENDPOINT"],
+    source="fastapi",
+    ignore_paths=["/healthz"],
+)
+```
+
+A pure ASGI middleware (streaming responses aren't buffered). Same options as Flask plus `ignore_paths`;
+`get_tenant_id` receives the ASGI `scope`, and `api_key` / `endpoint` / `environment` / `source` fall back to the
+`LOGSETU_*` environment variables. Request context reaches logs from both `async def` endpoints and sync endpoints
+running in the threadpool. `HTTPException`s with 4xx status codes aren't reported as errors. The request id is
+available as `request.state.logsetu_request_id`.
+
+## License
+
+MIT