logsetu-django 0.1.0__tar.gz

logsetu_django-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# deps
+node_modules/
+.pnpm-store/
+
+# builds
+dist/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+apps/server/generated/
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# env / secrets
+.env
+.env.*
+!.env.example
+
+# data
+data/
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+*.sqlite-*
+
+# editors / os
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# generated by next
+next-env.d.ts

logsetu_django-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raj Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logsetu_django-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: logsetu-django
+Version: 0.1.0
+Summary: LogSetu SDK for Django & DRF — ship Python 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: django,drf,error-tracking,logging,logsetu,self-hosted,sentry-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+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: 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'
+Description-Content-Type: text/markdown
+
+# logsetu-django
+
+Ship Django / DRF 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
+```
+
+## 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`.
+
+## License
+
+MIT

logsetu_django-0.1.0/README.md

@@ -0,0 +1,123 @@
+# logsetu-django
+
+Ship Django / DRF 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
+```
+
+## 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`.
+
+## License
+
+MIT

logsetu_django-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "logsetu-django"
+version = "0.1.0"
+description = "LogSetu SDK for Django & DRF — ship Python logging records and request errors to your self-hosted LogSetu server"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Raj Verma" }]
+requires-python = ">=3.9"
+keywords = ["logging", "django", "drf", "error-tracking", "self-hosted", "sentry-alternative", "logsetu"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Logging",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+django = ["Django>=3.2"]
+dev = ["Django>=3.2", "pytest>=8", "pytest-django>=4.8", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/itsrajverma/logsetu"
+Documentation = "https://github.com/itsrajverma/logsetu/tree/main/docs"
+Repository = "https://github.com/itsrajverma/logsetu"
+Issues = "https://github.com/itsrajverma/logsetu/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/logsetu"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/logsetu", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src", "."]

logsetu_django-0.1.0/src/logsetu/__init__.py

@@ -0,0 +1,41 @@
+"""LogSetu SDK for Django & DRF.
+
+Quick start (settings.py)::
+
+    LOGGING = {
+        "version": 1,
+        "handlers": {
+            "logsetu": {
+                "class": "logsetu.handler.LogSetuHandler",
+                "api_key": env("LOGSETU_API_KEY"),
+                "endpoint": env("LOGSETU_ENDPOINT"),
+                "environment": "production",
+                "source": "django-backend",
+                "level": "WARNING",
+            },
+        },
+        "root": {"handlers": ["logsetu"], "level": "INFO"},
+    }
+    MIDDLEWARE = [..., "logsetu.middleware.LogSetuMiddleware"]
+"""
+
+from .client import LogSetuClient, get_client, __version__
+from .context import get_request_context, update_request_context
+
+__all__ = [
+    "LogSetuClient",
+    "get_client",
+    "get_request_context",
+    "update_request_context",
+    "capture_exception",
+    "__version__",
+]
+
+default_app_config = "logsetu.apps.LogSetuConfig"
+
+
+def capture_exception(exc: BaseException, message: str = "", **meta: object) -> None:
+    """Report an exception through the configured ``LogSetuHandler`` (via the stdlib logger)."""
+    import logging
+
+    logging.getLogger("logsetu.capture").error(message or f"{type(exc).__name__}: {exc}", exc_info=exc, extra=meta)

logsetu_django-0.1.0/src/logsetu/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class LogSetuConfig(AppConfig):
+    name = "logsetu"
+    verbose_name = "LogSetu"

logsetu_django-0.1.0/src/logsetu/client.py

@@ -0,0 +1,250 @@
+"""Thread-safe, batching HTTP client for the LogSetu ingestion API.
+
+Uses only the standard library so the package has zero runtime dependencies.
+Never raises into the host application: transport failures are reported once on
+stderr and the affected batch is dropped.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import queue
+import random
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional, Tuple
+
+__version__ = "0.1.0"
+
+LogDict = Dict[str, Any]
+
+_MAX_BATCH = 500
+_FLUSH: Any = object()  # queue sentinel: send whatever is buffered now
+_STOP: Any = object()  # queue sentinel: send and exit
+
+
+def to_json_safe(value: Any, depth: int = 0) -> Any:
+    """Coerce arbitrary values into something ``json.dumps`` accepts."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if depth > 6:
+        return repr(value)
+    if isinstance(value, dict):
+        return {str(k): to_json_safe(v, depth + 1) for k, v in list(value.items())[:200]}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [to_json_safe(v, depth + 1) for v in list(value)[:200]]
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")[:2000]
+    if hasattr(value, "isoformat"):
+        try:
+            return value.isoformat()
+        except Exception:  # pragma: no cover
+            pass
+    return repr(value)
+
+
+class LogSetuClient:
+    """Queues log dicts and ships them in batches from a background daemon thread."""
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str,
+        *,
+        environment: str = "production",
+        source: str = "django",
+        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,
+        enabled: bool = True,
+    ) -> None:
+        self.api_key = api_key or ""
+        self.endpoint = (endpoint or "").rstrip("/")
+        self.ingest_url = f"{self.endpoint}/api/v1/ingest"
+        self.environment = environment
+        self.source = source
+        self.flush_interval = max(0.05, float(flush_interval))
+        self.batch_size = max(1, min(int(batch_size), _MAX_BATCH))
+        self.max_queue_size = max(1, int(max_queue_size))
+        self.max_retries = max(0, int(max_retries))
+        self.timeout = float(timeout)
+        self.debug = debug
+        self.enabled = bool(enabled and self.api_key and self.endpoint)
+
+        self._queue: "queue.Queue[Any]" = queue.Queue(maxsize=self.max_queue_size + 2)
+        self._dropped = 0
+        self._warned = False
+        self._lock = threading.Lock()
+        self._idle = threading.Event()
+        self._idle.set()
+        self._stopped = False
+        self._thread: Optional[threading.Thread] = None
+
+        if not self.enabled:
+            if enabled:
+                self._warn("api_key/endpoint not configured; logs will not be sent")
+            return
+        self._thread = threading.Thread(target=self._run, name="logsetu-worker", daemon=True)
+        self._thread.start()
+        atexit.register(self.close)
+
+    # ---------- public ----------
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        meta: Optional[Dict[str, Any]] = None,
+        *,
+        timestamp: Optional[str] = None,
+        source: Optional[str] = None,
+        environment: Optional[str] = None,
+    ) -> None:
+        if not self.enabled or self._stopped:
+            return
+        entry: LogDict = {
+            "level": level,
+            "message": str(message)[:10_000],
+            "source": source or self.source,
+            "environment": environment or self.environment,
+        }
+        if timestamp:
+            entry["timestamp"] = timestamp
+        if meta:
+            entry["meta"] = to_json_safe(meta)
+        self.enqueue(entry)
+
+    def enqueue(self, entry: LogDict) -> None:
+        if not self.enabled or self._stopped:
+            return
+        self._idle.clear()
+        with self._lock:
+            if self._queue.qsize() >= self.max_queue_size:
+                # Drop the oldest to make room; a log SDK must never block the request cycle.
+                try:
+                    self._queue.get_nowait()
+                except queue.Empty:  # pragma: no cover
+                    pass
+                self._dropped += 1
+            try:
+                self._queue.put_nowait(entry)
+            except queue.Full:  # pragma: no cover
+                self._dropped += 1
+
+    def flush(self, timeout: Optional[float] = 10.0) -> bool:
+        """Block until everything currently queued has been sent (or *timeout* elapses)."""
+        if not self.enabled or self._stopped:
+            return True
+        self._idle.clear()
+        try:
+            self._queue.put_nowait(_FLUSH)
+        except queue.Full:  # pragma: no cover
+            pass
+        return self._idle.wait(timeout)
+
+    def close(self) -> None:
+        if not self.enabled or self._stopped:
+            return
+        self._stopped = True
+        self._queue.put(_STOP)
+        if self._thread is not None:
+            self._thread.join(timeout=10.0)
+
+    @property
+    def dropped(self) -> int:
+        return self._dropped
+
+    # ---------- worker ----------
+
+    def _run(self) -> None:
+        batch: List[LogDict] = []
+        deadline = time.monotonic() + self.flush_interval
+        while True:
+            try:
+                item = self._queue.get(timeout=max(0.0, deadline - time.monotonic()))
+            except queue.Empty:
+                item = _FLUSH
+            if item is _STOP:
+                self._send(batch + self._drain())
+                self._idle.set()
+                return
+            if item is not _FLUSH:
+                batch.append(item)
+            if batch and (len(batch) >= self.batch_size or item is _FLUSH):
+                self._send(batch + self._drain(_MAX_BATCH - len(batch)))
+                batch = []
+            if item is _FLUSH or not batch:
+                deadline = time.monotonic() + self.flush_interval
+            if not batch and self._queue.empty():
+                self._idle.set()
+
+    def _drain(self, limit: int = _MAX_BATCH) -> List[LogDict]:
+        out: List[LogDict] = []
+        while len(out) < limit:
+            try:
+                more = self._queue.get_nowait()
+            except queue.Empty:
+                break
+            if more is _STOP:
+                self._queue.put_nowait(_STOP)
+                break
+            if more is not _FLUSH:
+                out.append(more)
+        return out
+
+    def _send(self, batch: List[LogDict]) -> None:
+        if not batch:
+            return
+        body = json.dumps(batch, default=str).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"logsetu-django/{__version__}",
+        }
+        last_error = "unknown error"
+        for attempt in range(self.max_retries + 1):
+            try:
+                req = urllib.request.Request(self.ingest_url, data=body, headers=headers, method="POST")
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:  # noqa: S310 - user-configured URL
+                    if 200 <= res.status < 300:
+                        return
+                    last_error = f"HTTP {res.status}"
+            except urllib.error.HTTPError as e:
+                if e.code < 500 and e.code != 429:
+                    self._warn(f"server rejected batch (HTTP {e.code}); dropped {len(batch)} logs")
+                    return
+                last_error = f"HTTP {e.code}"
+            except Exception as e:  # network errors, timeouts, DNS
+                last_error = repr(e)
+            if attempt < self.max_retries:
+                time.sleep(min(30.0, 0.5 * (2**attempt)) + random.random() * 0.25)
+        self._warn(f"giving up after {self.max_retries + 1} attempts ({last_error}); dropped {len(batch)} logs")
+
+    def _warn(self, msg: str) -> None:
+        # Deliberately bypass the logging module: the LogSetu handler may be attached to the root logger.
+        if self.debug or not self._warned:
+            self._warned = True
+            suffix = "" if self.debug else " (further transport warnings suppressed; set debug=True to see them)"
+            sys.stderr.write(f"[logsetu] {msg}{suffix}\n")
+
+
+_registry: Dict[Tuple[str, str], LogSetuClient] = {}
+_registry_lock = threading.Lock()
+
+
+def get_client(api_key: str, endpoint: str, **kwargs: Any) -> LogSetuClient:
+    """Return a shared client per (api_key, endpoint) so the handler and middleware use one queue."""
+    key = (api_key or "", (endpoint or "").rstrip("/"))
+    with _registry_lock:
+        client = _registry.get(key)
+        if client is None or client._stopped:
+            client = LogSetuClient(api_key, endpoint, **kwargs)
+            _registry[key] = client
+        return client