boxfusion-log 0.1.0__py3-none-any.whl

boxfusion_log-0.1.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: boxfusion-log
+Version: 0.1.0
+Summary: Structured JSON logging with request tracing, secret redaction, pluggable storage and a built-in web log viewer.
+Author: Boxfusion
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,fastapi,json,log-viewer,logging,structured-logging,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: redis>=4.5; extra == 'all'
+Requires-Dist: uvicorn>=0.23; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=4.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Requires-Dist: uvicorn>=0.23; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=4.5; extra == 'redis'
+Provides-Extra: web
+Requires-Dist: uvicorn>=0.23; extra == 'web'
+Description-Content-Type: text/markdown
+
+# boxlog
+
+Structured JSON logging for Python, with request and job tracing, secret redaction,
+pluggable storage and a built-in web log viewer.
+
+```bash
+pip install boxfusion-log              # core: stdlib only, no dependencies
+pip install "boxfusion-log[redis]"     # + Redis storage
+pip install "boxfusion-log[web]"       # + the standalone `boxlog serve` viewer
+pip install "boxfusion-log[all]"
+```
+
+```python
+import boxlog   # the package installs as boxfusion-log but imports as boxlog
+```
+
+boxlog builds on the standard `logging` module, so it needs no new logger API. Your existing
+`logging.getLogger(__name__)` calls, and every third-party library's logs, flow through it
+unchanged.
+
+## Quick start
+
+```python
+import logging
+import boxlog
+
+boxlog.setup(service="billing", backend="sqlite:///logs/billing.db")
+log = logging.getLogger(__name__)
+
+log.info("Service started", extra={"event": "app.startup", "version": "1.4.2"})
+```
+
+Output on stdout, one JSON object per line:
+
+```json
+{"ts": "2026-09-29T09:16:21.180+00:00", "level": "INFO", "logger": "__main__",
+ "message": "Service started", "event": "app.startup", "service": "billing",
+ "extra": {"version": "1.4.2"}}
+```
+
+Use `stdout="text"` for readable lines during development.
+
+## Logging a unit of work: `log_step`
+
+One `with` block logs the start of the work, then either its success (with duration and
+any result fields) or its failure (with the traceback), and re-raises the error:
+
+```python
+with boxlog.log_step(log, "payment.charge", customer="c-42", amount=1999) as step:
+    receipt = gateway.charge(...)
+    step["receipt_id"] = receipt.id
+```
+
+| outcome | event                   | level | extras                                                  |
+|---------|-------------------------|-------|---------------------------------------------------------|
+| start   | `payment.charge.start`  | DEBUG | `customer`, `amount`                                    |
+| success | `payment.charge.ok`     | INFO  | `customer`, `amount`, `receipt_id`, `duration_ms`       |
+| failure | `payment.charge.failed` | ERROR | the fields, `duration_ms`, `error_type` and a traceback |
+
+It works around `await` too. Nested steps log each traceback only once, in the innermost
+step; outer steps still log `.failed`, so you see the chain of work that broke without
+reading the same traceback five times. In your own `except` blocks, check
+`boxlog.already_logged(exc)` for the same effect.
+
+## Tracing: `bind`
+
+Fields you bind are added to every record logged inside the block, including records
+from awaited code and from asyncio tasks started inside it:
+
+```python
+with boxlog.bind(job_id=job.id, tenant="acme"):
+    process(job)          # every record in here carries job_id and tenant
+```
+
+Field names must be lower_snake_case. The web middleware binds `request_id` for you.
+
+## Web frameworks
+
+**FastAPI / Starlette (ASGI):**
+
+```python
+import os
+from fastapi import FastAPI
+import boxlog
+
+boxlog.setup(service="api", backend="redis://localhost:6379/0?key=api:logs")
+
+app = FastAPI()
+app.add_middleware(boxlog.RequestIdMiddleware, quiet_paths=("/health", "/logs"))
+app.mount("/logs", boxlog.create_viewer(
+    boxlog.backend_from_url("redis://localhost:6379/0?key=api:logs"),
+    token=os.environ["LOGS_TOKEN"],
+    title="API logs",
+))
+```
+
+**Flask / Django (WSGI):**
+
+```python
+app.wsgi_app = boxlog.WSGIRequestIdMiddleware(app.wsgi_app)            # Flask
+application = boxlog.WSGIRequestIdMiddleware(get_wsgi_application())    # Django
+```
+
+Then view logs with the standalone viewer (below).
+
+The middleware:
+- reuses an incoming `X-Request-ID` if it's well-formed, and otherwise generates one;
+- echoes the id back on the response;
+- logs one `http.request` record per request (method, path, status and duration);
+- logs any unhandled exception with its traceback.
+
+## The web viewer
+
+The viewer has:
+- a level filter (including "Failures only");
+- service and source filters, populated from your data;
+- an event-prefix filter and text search;
+- click-to-trace on any `request_id` or `job_id`;
+- live tail;
+- an expandable view of every record and its traceback.
+
+- **Mounted** inside an ASGI app: `create_viewer(backend, token=...)`, as above.
+- **Standalone**, for any app, including non-web workers and scripts:
+
+  ```bash
+  export BOXLOG_TOKEN="$(boxlog token)"
+  boxlog serve sqlite:///logs/billing.db          # http://127.0.0.1:8765/
+  boxlog serve "redis://localhost:6379/0?key=api:logs" --port 9000 --title "API logs"
+  ```
+
+**Security.** Logs contain whatever your users send you, so treat the viewer like an admin
+console:
+- It requires a bearer token of **at least 32 characters**. Generate one with `boxlog token`.
+- If the token is unset, the mounted viewer answers 404 everywhere.
+- The page renders log content only as text, never as HTML, and ships under a strict
+  Content-Security-Policy with no inline script.
+- Serve it over HTTPS. The standalone server binds to `127.0.0.1` unless you pass `--host`.
+
+`create_viewer` also takes callables for `backend` and `token`. That's useful when they're
+only known at startup (for example, inside a lifespan).
+
+## Storage backends
+
+| backend         | URL                                                  | good for                                                                   |
+|-----------------|------------------------------------------------------|----------------------------------------------------------------------------|
+| `MemoryBackend` | `memory://?max=5000`                                 | tests and scripts; lost on restart                                         |
+| `SQLiteBackend` | `sqlite:///logs/app.db?max=100000`                   | one machine, no server; indexed queries; processes on one host can share the file |
+| `RedisBackend`  | `redis://host:6379/0?key=app:logs&max=10000`         | several processes or machines; survives restarts                           |
+
+```python
+boxlog.setup(service="worker", backend=boxlog.SQLiteBackend("logs/worker.db"))
+# or attach later, once settings are known:
+boxlog.attach_backend("redis://cache:6379/0?key=worker:logs")
+```
+
+Records reach the backend from a background thread, in batches, so logging never blocks
+your code or an event loop. If the backend is down, records are dropped (with one warning
+on stderr) and your app carries on; stdout logging is unaffected. Several services can
+share one backend, and the viewer shows a service filter when it finds more than one.
+
+A custom backend needs three methods, `append(entries)`, `query(query)` and `close()`. See
+`boxlog.backends.base.LogBackend`.
+
+## Redaction
+
+Before any output, boxlog masks:
+- values of sensitive keys in `extra=` and bound fields: `password`, `token`, `api_key`,
+  `secret`, `authorization`, `cookie`, … (as whole names or `_` suffixes, so `access_token`
+  is masked but `total_tokens` isn't);
+- `Bearer …` and `Basic …` credentials in text;
+- `password=…` and `"token": "…"` pairs in text;
+- passwords inside URLs (`redis://user:secret@host`);
+- all of the above in exception messages and tracebacks.
+
+You can add your own keys and patterns:
+
+```python
+boxlog.setup(redact_keys=["national_id"], redact_patterns=[r"\b\d{13}\b"])
+```
+
+Redaction is a safety net. Don't log secrets or whole request bodies on purpose.
+
+## `setup()` reference
+
+```python
+boxlog.setup(
+    service=None,              # tagged on every record
+    level="INFO",
+    stdout="json",             # "json", "text" or None
+    backend=None,              # LogBackend or URL
+    redact_keys=(), redact_patterns=(),
+    promoted_fields=("request_id", "job_id", "source"),  # extra= keys lifted to top level
+    quiet_loggers=("httpx", "httpcore", "urllib3", "openai", "botocore", "redis", "asyncio"),
+    capture_uvicorn=True,      # route uvicorn's logs through boxlog, drop its access log
+)
+```
+
+To quiet more libraries while keeping the defaults, pass
+`quiet_loggers=(*boxlog.DEFAULT_QUIET_LOGGERS, "pinecone")`.
+
+You can call it again to change settings. It only replaces the handlers it installed
+itself. `boxlog.shutdown()` (also registered with `atexit`) flushes queued records.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -m build && .venv/bin/python -m twine check dist/*
+```
+
+## License
+
+MIT

boxfusion_log-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+boxlog/__init__.py,sha256=JTFfGawbKXgZSR1zxMw41Vfz_fYYptJgmQmwXymCVgw,1785
+boxlog/__main__.py,sha256=YwHfeAqB5e375f-y8_feGWX2W_l7TQdIfsHTzrAZFSM,58
+boxlog/_record.py,sha256=i4OTvz2N6TAMEniStWMAK9PPHGsdapn5XfMhIruIm48,1272
+boxlog/cli.py,sha256=w6ufISiw36YifzhMGklKlOAn_K3l2BokivVJ0iWTIuk,2850
+boxlog/configure.py,sha256=0OHMrcLruRAy5AIviLFPp1-E-Ck98fwq-Ro-cpG1-b4,5997
+boxlog/context.py,sha256=GvD9Vx1YIIndGq6JOXY4sgNgUnAELm0CTDWf3PdKdAs,1998
+boxlog/formatter.py,sha256=bU6VzAvvgbXsiR1eZ2Pyk_d7Km1W_4P7SVQSTQfgoK4,3380
+boxlog/handler.py,sha256=6FUgsoFwTuJpunvTVJbg8NWpGwl5uIIa1NBIVABPjUs,4733
+boxlog/middleware.py,sha256=DjmtQ7i5PzJXDBA2H-IS_hCSod_7Ue_ZEAfCXUdNM2c,6139
+boxlog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boxlog/query.py,sha256=o5GVzQSfoSFaYTwSFHhU2Ni6QSvR3KE5WkjDSMvHWCc,5555
+boxlog/redaction.py,sha256=3Wa08PQbBXTfeKV2CvS4VHfyGXbSvgTDXdU1aMCxSik,4565
+boxlog/timing.py,sha256=Wc709daB-DOxd3l7GdE_5FR7y-54Q4NrzVM27ooDKOY,3507
+boxlog/backends/__init__.py,sha256=QZJvoUY0Q7am4rIveDK3ouh6bRE-OEenufw_HOJskeQ,2393
+boxlog/backends/base.py,sha256=s0LD9rs5rQQ8JXYW9Sr32bkdsxuUCtARd5IramXM6p4,892
+boxlog/backends/memory.py,sha256=IsxiAUExh1zFeFbklYq0DodnbBvf1dCSBcymtOlaKOs,906
+boxlog/backends/redis.py,sha256=6Z9q5JK966evO71fx-oJEDDQzCaa7ex8lAR8jcnCKpI,1954
+boxlog/backends/sqlite.py,sha256=K7J5eht4QxvoP0_58AzPX3rJI1G3cakNO4N_iMBsNC0,6284
+boxlog/viewer/__init__.py,sha256=WStKSfwXb9OLS1mBKhBEQQu_-KZquggKnrmWaMAItXc,9186
+boxlog/viewer/static/index.html,sha256=vOWLZuhHeqMoGxlF6FfZNWUxu-EcoXOMz9o3vrrSwts,2835
+boxlog/viewer/static/logs.css,sha256=RPVBDetg_aHsGkgro7ZPuReurpIf5DtozkBxDVbUvVM,5799
+boxlog/viewer/static/logs.js,sha256=hlgbDIsLHJObTMbH--8NTrGBbS-1XtIrDJIvJ4aPGbI,11380
+boxfusion_log-0.1.0.dist-info/METADATA,sha256=zyt8qCs_1QH5w54_BUhr8S7CdL_FjpzSpU23bmg_Pf0,9830
+boxfusion_log-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+boxfusion_log-0.1.0.dist-info/entry_points.txt,sha256=XZJ-vIgYibicvdhseh_fyevzfkEKufU80wVVL8j23ps,43
+boxfusion_log-0.1.0.dist-info/licenses/LICENSE,sha256=Xz2lCy18SXQLSsNYV_oXO7wd-Pfe-HzxgSLlBKmICu0,1066
+boxfusion_log-0.1.0.dist-info/RECORD,,

boxfusion_log-0.1.0.dist-info/WHEEL

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

boxfusion_log-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+boxlog = boxlog.cli:main

boxfusion_log-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boxfusion
+
+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.

boxlog/__init__.py

@@ -0,0 +1,69 @@
+"""boxlog - structured JSON logging with request tracing, secret redaction, pluggable
+storage and a built-in web log viewer.
+
+    import logging, boxlog
+
+    boxlog.setup(service="billing", backend="sqlite:///logs/billing.db")
+    log = logging.getLogger(__name__)
+
+    with boxlog.bind(request_id="abc"):
+        with boxlog.log_step(log, "invoice.create", customer="c-1") as step:
+            step["invoice_id"] = create_invoice()
+
+It builds on the standard `logging` module: existing `logging.getLogger(...)` calls,
+and third-party libraries' logs, all flow through it unchanged.
+"""
+
+from boxlog.backends import (
+    LogBackend,
+    MemoryBackend,
+    RedisBackend,
+    SQLiteBackend,
+    backend_from_url,
+)
+from boxlog.configure import (
+    DEFAULT_QUIET_LOGGERS,
+    attach_backend,
+    detach_backend,
+    set_level,
+    setup,
+    shutdown,
+)
+from boxlog.context import bind, current
+from boxlog.formatter import JsonFormatter, TextFormatter
+from boxlog.handler import BackendHandler
+from boxlog.middleware import RequestIdMiddleware, WSGIRequestIdMiddleware
+from boxlog.query import LogQuery
+from boxlog.redaction import Redactor
+from boxlog.timing import already_logged, log_step, mark_logged
+from boxlog.viewer import create_viewer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_QUIET_LOGGERS",
+    "BackendHandler",
+    "JsonFormatter",
+    "LogBackend",
+    "LogQuery",
+    "MemoryBackend",
+    "Redactor",
+    "RedisBackend",
+    "RequestIdMiddleware",
+    "SQLiteBackend",
+    "TextFormatter",
+    "WSGIRequestIdMiddleware",
+    "__version__",
+    "already_logged",
+    "attach_backend",
+    "backend_from_url",
+    "bind",
+    "create_viewer",
+    "current",
+    "detach_backend",
+    "log_step",
+    "mark_logged",
+    "set_level",
+    "setup",
+    "shutdown",
+]

boxlog/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from boxlog.cli import main
+
+sys.exit(main())

boxlog/_record.py

@@ -0,0 +1,39 @@
+"""Helpers for telling a LogRecord's own attributes apart from `extra=` fields."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+STANDARD_RECORD_ATTRS = frozenset(
+    vars(logging.LogRecord("", 0, "", 0, "", None, None)).keys()
+) | {"message", "asctime", "taskName"}
+
+# Attributes boxlog's own filters attach to a record.
+CONTEXT_ATTR = "boxlog_context"
+EXC_ATTR = "boxlog_exc"
+INTERNAL_ATTRS = frozenset({CONTEXT_ATTR, EXC_ATTR})
+
+# Extras other libraries attach that carry no information (uvicorn adds an ANSI-coloured
+# copy of every message).
+IGNORED_EXTRA_KEYS = frozenset({"color_message"})
+
+
+def extra_fields(record: logging.LogRecord) -> dict[str, Any]:
+    return {
+        key: value
+        for key, value in vars(record).items()
+        if key not in STANDARD_RECORD_ATTRS
+        and key not in INTERNAL_ATTRS
+        and key not in IGNORED_EXTRA_KEYS
+        and not key.startswith("_")
+    }
+
+
+def safe_extra(fields: dict[str, Any]) -> dict[str, Any]:
+    """`extra=` keys that collide with LogRecord attributes make logging raise KeyError -
+    prefix them instead of crashing the caller."""
+    return {
+        (f"field_{key}" if key in STANDARD_RECORD_ATTRS else key): value
+        for key, value in fields.items()
+    }

boxlog/backends/__init__.py

@@ -0,0 +1,65 @@
+"""Where records are persisted for the viewer.
+
+    MemoryBackend    in-process ring buffer          (tests, scripts)
+    SQLiteBackend    a local file, indexed queries    (single machine, no server)
+    RedisBackend     a capped Redis list              (several processes / machines)
+
+`backend_from_url()` builds one from a URL, which is handy for configuration:
+    memory://                   memory://?max=5000
+    sqlite:///logs/app.db       sqlite:///C:/logs/app.db     sqlite:///:memory:
+    redis://host:6379/0?key=myapp:logs&max=20000     rediss://...
+"""
+
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlsplit
+
+from boxlog.backends.base import LogBackend, LogEntry
+from boxlog.backends.memory import MemoryBackend
+from boxlog.backends.redis import RedisBackend
+from boxlog.backends.sqlite import SQLiteBackend
+
+__all__ = [
+    "LogBackend",
+    "LogEntry",
+    "MemoryBackend",
+    "RedisBackend",
+    "SQLiteBackend",
+    "backend_from_url",
+]
+
+
+def backend_from_url(url: str) -> LogBackend:
+    parts = urlsplit(url)
+    scheme = parts.scheme.lower()
+    params = {k: v[-1] for k, v in parse_qs(parts.query).items()}
+
+    def max_records(default: int) -> int:
+        raw = params.get("max")
+        if raw is None:
+            return default
+        value = int(raw)
+        if value < 1:
+            raise ValueError("max must be positive")
+        return value
+
+    if scheme == "memory":
+        return MemoryBackend(max_records=max_records(10_000))
+    if scheme == "sqlite":
+        path = parts.path
+        # sqlite:///C:/x.db arrives as "/C:/x.db"; sqlite:///rel.db as "/rel.db".
+        if len(path) >= 3 and path[0] == "/" and path[2] == ":":
+            path = path[1:]
+        elif path.startswith("//"):
+            path = path[1:]  # sqlite:////abs/path.db -> /abs/path.db
+        elif path.startswith("/"):
+            path = path[1:]  # relative to the working directory
+        if not path:
+            raise ValueError("sqlite URL needs a path, e.g. sqlite:///logs.db")
+        return SQLiteBackend(path, max_records=max_records(100_000))
+    if scheme in ("redis", "rediss", "unix"):
+        clean = url.split("?", 1)[0]
+        return RedisBackend(
+            clean, key=params.get("key", "boxlog"), max_records=max_records(10_000)
+        )
+    raise ValueError(f"Unsupported backend URL scheme {scheme!r} (memory, sqlite, redis)")

boxlog/backends/base.py

@@ -0,0 +1,29 @@
+"""The backend protocol.
+
+Backends are synchronous. append() is only ever called from the handler's shipper
+thread, and the viewer runs query() in a worker thread, so a backend never blocks an
+event loop.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple, Protocol, runtime_checkable
+
+from boxlog.query import LogQuery
+
+
+class LogEntry(NamedTuple):
+    record: dict[str, Any]  # the structured record (for backends that index columns)
+    line: str  # the same record as a JSON line (for backends that store text)
+
+
+@runtime_checkable
+class LogBackend(Protocol):
+    def append(self, entries: list[LogEntry]) -> None: ...
+
+    def query(self, query: LogQuery) -> dict[str, Any]:
+        """Return {"records": [...newest first], "latest": id|None, "count": n,
+        "facets": {"services": [...], "sources": [...]}}."""
+        ...
+
+    def close(self) -> None: ...

boxlog/backends/memory.py

@@ -0,0 +1,32 @@
+"""In-process ring buffer. Zero setup, lost on restart - good for tests and scripts."""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import Any
+
+from boxlog.backends.base import LogEntry
+from boxlog.query import LogQuery, filter_lines
+
+
+class MemoryBackend:
+    def __init__(self, max_records: int = 10_000) -> None:
+        self._lines: deque[str] = deque(maxlen=max_records)
+        self._lock = threading.Lock()
+
+    def append(self, entries: list[LogEntry]) -> None:
+        with self._lock:
+            for entry in entries:
+                self._lines.appendleft(entry.line)
+
+    def lines(self) -> list[str]:
+        """Newest first."""
+        with self._lock:
+            return list(self._lines)
+
+    def query(self, query: LogQuery) -> dict[str, Any]:
+        return filter_lines(self.lines(), query)
+
+    def close(self) -> None:
+        pass

boxlog/backends/redis.py

@@ -0,0 +1,59 @@
+"""A capped Redis list: LPUSH + LTRIM, newest first. Shared across processes and
+machines, survives restarts. Needs `pip install boxfusion-log[redis]`."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from boxlog.backends.base import LogEntry
+from boxlog.query import LogQuery, filter_lines
+
+DEFAULT_KEY = "boxlog"
+DEFAULT_MAX_RECORDS = 10_000
+
+
+class RedisBackend:
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        *,
+        client: Any = None,
+        key: str = DEFAULT_KEY,
+        max_records: int = DEFAULT_MAX_RECORDS,
+    ) -> None:
+        if client is None:
+            if url is None:
+                raise ValueError("RedisBackend needs either url or client")
+            try:
+                from redis import Redis
+            except ImportError as exc:  # pragma: no cover - depends on the environment
+                raise ImportError(
+                    "RedisBackend needs the redis package: pip install 'boxfusion-log[redis]'"
+                ) from exc
+            client = Redis.from_url(
+                url, decode_responses=True, socket_timeout=5, socket_connect_timeout=5
+            )
+        self._redis = client
+        self._key = key
+        self._max = max_records
+
+    def append(self, entries: list[LogEntry]) -> None:
+        if not entries:
+            return
+        pipe = self._redis.pipeline(transaction=False)
+        pipe.lpush(self._key, *(entry.line for entry in entries))
+        pipe.ltrim(self._key, 0, self._max - 1)
+        pipe.execute()
+
+    def query(self, query: LogQuery) -> dict[str, Any]:
+        lines = self._redis.lrange(self._key, 0, self._max - 1)
+        return filter_lines(
+            (line.decode("utf-8", "replace") if isinstance(line, bytes) else line for line in lines),
+            query,
+        )
+
+    def close(self) -> None:
+        try:
+            self._redis.close()
+        except Exception:  # noqa: BLE001
+            pass