Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

16.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Structlog config: JSON logs in prod, console in dev, ISO timestamps, context vars, level filter."""

import logging
import os
import sys
import threading
from typing import Optional

import structlog

from loggers.handlers import filter_sensitive_data


class _DropTorchDtypeDeprecation(logging.Filter):
    """Drop transformers' once-per-run "`torch_dtype` is deprecated" warning_once.
    It is emitted via logging (not warnings), so a warnings filter cannot catch it."""

    def filter(self, record: logging.LogRecord) -> bool:
        msg = record.getMessage()
        return not ("torch_dtype" in msg and "deprecated" in msg)


def _env_int(name: str, default: int) -> int:
    try:
        raw = (os.environ.get(name) or "").strip()
        return int(raw) if raw else default
    except ValueError:
        return default


# Exception messages can embed whole request bodies, so their length is capped.
_MAX_EXC_CHARS = _env_int("UNSLOTH_STUDIO_MAX_EXCEPTION_CHARS", 16384)
_EXC_TAIL_CHARS = 2048
# The middleware logs the same exception twice, rendered as a traceback and as str(exc), so bound both.
_MAX_ERROR_CHARS = 2048


def _truncate_middle(text: str, limit: int, tail: int) -> str:
    """Clamp tail to limit // 4 so a small cap cannot make head negative and return the whole text."""
    if limit <= 0 or len(text) <= limit:
        return text
    tail = max(1, min(tail, limit // 4))
    head = limit - tail
    dropped = len(text) - limit
    return (
        text[:head] + f"\n... [{dropped} chars omitted; "
        "raise UNSLOTH_STUDIO_MAX_EXCEPTION_CHARS to see it all] ...\n" + text[-tail:]
    )


def truncate_exception(event_dict: dict) -> dict:
    """Structlog processor: bound the rendered exception, its message and the event."""
    if _MAX_EXC_CHARS <= 0:
        return event_dict
    text = event_dict.get("exception")
    if isinstance(text, str):
        event_dict["exception"] = _truncate_middle(text, _MAX_EXC_CHARS, _EXC_TAIL_CHARS)
    message_cap = min(_MAX_ERROR_CHARS, _MAX_EXC_CHARS)
    error = event_dict.get("error")
    if isinstance(error, str):
        event_dict["error"] = _truncate_middle(error, message_cap, _EXC_TAIL_CHARS)
    # f-string log calls put the exception into the event, a third copy that can carry the payload.
    event = event_dict.get("event")
    if isinstance(event, str):
        event_dict["event"] = _truncate_middle(event, message_cap, _EXC_TAIL_CHARS)
    # No PositionalArgumentsFormatter in the chain, so render and cap "%s" args here.
    args = event_dict.get("positional_args")
    if isinstance(args, (list, tuple)) and args:
        event_dict["positional_args"] = [
            _truncate_middle(a, message_cap, _EXC_TAIL_CHARS)
            if isinstance(a, str)
            else _truncate_middle(str(a), message_cap, _EXC_TAIL_CHARS)
            for a in args
        ]
    return event_dict


def _truncate_exception_processor(logger, method_name, event_dict):
    return truncate_exception(event_dict)


def _plain_tracebacks_enabled() -> bool:
    """Echo readable tracebacks? ``UNSLOTH_STUDIO_PLAIN_TRACEBACKS=0`` turns it off."""
    return (os.environ.get("UNSLOTH_STUDIO_PLAIN_TRACEBACKS") or "").strip().lower() not in (
        "0",
        "off",
        "no",
        "false",
    )


# '| ' cannot begin a JSON value; leading whitespace would let a message forge a record (CWE-117).
_TRACEBACK_ECHO_PREFIX = "| "


# Bidi_Control set (CVE-2021-42574); not all of Cf since ZWSP, SHY, BOM occur in normal text.
_BIDI_CONTROLS = frozenset("؜‎‏‪‫‬‭‮⁦⁧⁨⁩")


def _escape_unprintable(text: str) -> str:
    """Escape lone surrogates (UnicodeEncodeError on UTF-8 stdout loses the traceback), terminal
    controls (ESC rewrites output; backspace erases the prefix forgery depends on) and bidi
    controls; keep tab."""
    out = []
    for ch in text:
        code = ord(ch)
        if ch == "\t":
            out.append(ch)
        elif (
            code < 0x20
            or code == 0x7F
            or 0x80 <= code <= 0x9F
            or 0xD800 <= code <= 0xDFFF
            or ch in _BIDI_CONTROLS
        ):
            out.append(f"\\u{code:04x}")
        else:
            out.append(ch)
    return "".join(out)


def _echoable(exception: str) -> str:
    """Cap after escaping, since each escaped control character grows to six characters."""
    lines = [
        f"{_TRACEBACK_ECHO_PREFIX}{_escape_unprintable(part)}"
        for part in exception.rstrip().splitlines()
    ]
    return _cap_echoed_lines(lines, _MAX_EXC_CHARS)


def _cap_echoed_lines(lines: list[str], limit: int) -> str:
    """Cut an over-long line rather than drop it, so the tail with the exception type survives."""
    if limit <= 0:
        return "\n".join(lines)
    total = sum(len(line) + 1 for line in lines)
    if total <= limit:
        return "\n".join(lines)
    tail_budget = max(1, limit // 4)
    head_budget = limit - tail_budget
    head: list[str] = []
    used = 0
    for line in lines:
        if used + len(line) + 1 > head_budget:
            break
        head.append(line)
        used += len(line) + 1
    tail: list[str] = []
    used = 0
    for line in reversed(lines[len(head) :]):
        if used + len(line) + 1 > tail_budget:
            # Truncate the boundary line rather than drop it; a traceback's last line holds the reason.
            room = tail_budget - used - 1
            if room > 0:
                tail.append(line[:room])
            break
        tail.append(line)
        used += len(line) + 1
    tail.reverse()
    if not head and not tail:
        head = [lines[0][:head_budget]]
    # A cut boundary line counts as kept, so say "cut" rather than claim zero lines went.
    dropped = len(lines) - len(head) - len(tail)
    what = f"{dropped} lines omitted" if dropped else "cut here"
    notice = (
        f"{_TRACEBACK_ECHO_PREFIX}... [{what}; raise "
        "UNSLOTH_STUDIO_MAX_EXCEPTION_CHARS to see it all] ..."
    )
    return "\n".join([*head, notice, *tail])


def with_readable_traceback(renderer):
    """Echo tracebacks as readable lines after the JSON record, prefixed so they never parse as records."""

    def _render(logger, method_name, event_dict):
        exception = event_dict.get("exception")
        line = renderer(logger, method_name, event_dict)
        if (
            isinstance(exception, str)
            and exception.strip()
            and isinstance(line, str)
            and _plain_tracebacks_enabled()
        ):
            return f"{line}\n{_echoable(exception)}"
        return line

    return _render


# Set with HF_HUB_DISABLE_PROGRESS_BARS only if Unsloth chose it, to tell it from the operator's.
_PROGRESS_BARS_DEFAULTED = "UNSLOTH_STUDIO_PROGRESS_BARS_DEFAULTED"

# huggingface_hub's ENV_VARS_TRUE_VALUES, so 'off'/'no' mean keep the bars.
_ENV_TRUE = frozenset({"1", "on", "yes", "true"})

# Latched once bars are restored, so quiet_third_party_progress_bars() cannot flip back.
_BARS_RESTORED = False


def _env_is_true(value: str) -> bool:
    return (value or "").strip().lower() in _ENV_TRUE


def _verbose_logging_requested() -> bool:
    """True when `unsloth studio --verbose` asked for every line back. The CLI signals
    it by zeroing both access-log dedup windows, which is what the workers inherit."""

    def _zero(name: str) -> bool:
        raw = (os.environ.get(name) or "").strip()
        try:
            return raw != "" and int(raw) <= 0
        except ValueError:
            return False

    return _zero("UNSLOTH_STUDIO_ACCESS_LOG_DEDUP_MS") and _zero(
        "UNSLOTH_STUDIO_ACCESS_LOG_POLL_DEDUP_MS"
    )


def verbose_logging_requested() -> bool:
    """Return whether Studio verbose logging is enabled."""
    return _verbose_logging_requested()


class _NullStream:
    """Somewhere for a progress bar to write that is not the log."""

    def write(self, _data):
        return 0

    def flush(self):
        pass

    def isatty(self):
        return False


def _silence_datasets_bar_output() -> None:
    """Drop only the datasets bar output; the bar stays in tqdm._instances for the chat template poller."""
    if "datasets" not in sys.modules:
        # Operator asked to keep them; leave every library alone.
        return
    try:
        from datasets.utils.tqdm import tqdm as bar_cls

        if getattr(bar_cls, "_unsloth_output_silenced", False):
            return
        original_init = bar_cls.__init__

        def _quiet_init(self, *args, **kwargs):
            kwargs.setdefault("file", _NullStream())
            original_init(self, *args, **kwargs)

        bar_cls.__init__ = _quiet_init
        bar_cls._unsloth_output_silenced = True
    except Exception:  # noqa: BLE001 - a datasets build without it just stays noisy
        pass


def _redirect_every_bar_output() -> None:
    """Point every tqdm bar at a null stream, disabling none of them. tqdm.std.tqdm.__init__ is the one
    funnel: huggingface_hub's, datasets' and transformers' bar classes all subclass it and reach it
    through super()."""
    try:
        from tqdm.std import tqdm as bar_cls

        if getattr(bar_cls, "_unsloth_every_output_silenced", False):
            return
        original_init = bar_cls.__init__

        def _quiet_init(self, *args, **kwargs):
            kwargs.setdefault("file", _NullStream())
            # disable=None means TTY detection; our stream is not a TTY but the UI needs counts.
            if kwargs.get("disable") is None:
                kwargs["disable"] = False
            original_init(self, *args, **kwargs)

        bar_cls.__init__ = _quiet_init
        bar_cls._unsloth_every_output_silenced = True
    except Exception:  # noqa: BLE001 - an unfamiliar tqdm just stays noisy
        pass


def keep_progress_bars_countable() -> None:
    """Undo Unsloth's own HF_HUB_DISABLE_PROGRESS_BARS default before huggingface_hub is imported."""
    value = os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS")
    if value is None or not _env_is_true(value):
        return
    if not os.environ.get(_PROGRESS_BARS_DEFAULTED):
        # The operator turned them off; that is not ours to undo.
        return
    _redirect_every_bar_output()
    allow_progress_bars()
    # Hub may already be imported: undo its cached copy of OUR default, never an operator opt-out.
    for name in ("huggingface_hub.constants", "huggingface_hub.utils.tqdm"):
        module = sys.modules.get(name)
        if module is not None and getattr(module, "HF_HUB_DISABLE_PROGRESS_BARS", None) is True:
            module.HF_HUB_DISABLE_PROGRESS_BARS = None
    bars = sys.modules.get("huggingface_hub.utils.tqdm")
    enable = getattr(bars, "enable_progress_bars", None)
    if callable(enable):
        enable()


def quiet_bar_kwargs() -> dict:
    """tqdm kwargs keep bars counting but off the log, for Unsloth's own bars no library switch reaches."""
    value = os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS")
    if value is None or not _env_is_true(value):
        return {}
    return {"file": _NullStream()}


def allow_progress_bars() -> None:
    """Export worker needs its Hub upload bar, so undo Unsloth's HF_HUB_DISABLE_PROGRESS_BARS default."""
    global _BARS_RESTORED
    _BARS_RESTORED = True
    if os.environ.pop(_PROGRESS_BARS_DEFAULTED, None):
        os.environ.pop("HF_HUB_DISABLE_PROGRESS_BARS", None)


def quiet_third_party_progress_bars() -> None:
    """Silence the transformers, diffusers and Hub tqdm bars that break JSON log lines; --verbose skips."""
    if _BARS_RESTORED:
        # The training worker reads bars from tqdm._instances, where a disabled bar never registers.
        return
    if _verbose_logging_requested() and os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS") is None:
        # --verbose must not install this default either; the flag is inherited by the workers.
        return
    if os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS") is None:
        os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
        # Marks the value as ours rather than the operator's; inherited by child processes.
        os.environ[_PROGRESS_BARS_DEFAULTED] = "1"
    elif not _env_is_true(os.environ["HF_HUB_DISABLE_PROGRESS_BARS"]):
        # Operator asked to keep them; leave every library alone.
        return

    # Only touch Hub if already imported, else it caches the base env copy before sidecar sys.path.
    if "huggingface_hub" in sys.modules:
        try:
            from huggingface_hub.utils import disable_progress_bars
            disable_progress_bars()
        except Exception:  # noqa: BLE001 - quieting logs must never break startup
            pass

    # transformers reads the hub flag at import, so already-imported modules need the explicit call.
    for _mod in ("transformers", "diffusers"):
        module = sys.modules.get(_mod)
        if module is None:
            continue
        try:
            module.utils.logging.disable_progress_bar()
        except Exception:  # noqa: BLE001
            pass
    _silence_datasets_bar_output()
    # Direct tqdm users bypass diffusers' toggle; preserve counters but discard redraws.
    _redirect_every_bar_output()


_STDOUT_LOCK = threading.Lock()


class _CurrentStdoutLogger:
    """A structlog logger that resolves ``sys.stdout`` per record, since ``PrintLogger`` binds the stream at build time and loses records once a tee or capture replaces stdout."""

    def msg(self, message: str) -> None:
        stream = sys.stdout
        if stream is None:
            return
        with _STDOUT_LOCK:
            stream.write(message + "\n")
            stream.flush()

    log = debug = info = warn = warning = msg
    fatal = failure = err = error = critical = exception = msg

    def __repr__(self) -> str:
        return "<CurrentStdoutLogger>"


def _current_stdout_logger_factory(*args) -> _CurrentStdoutLogger:
    return _CurrentStdoutLogger()


class LogConfig:
    """Structured logging configuration for the application."""

    @staticmethod
    def setup_logging(
        service_name: str = "unsloth-studio-backend",
        env: Optional[str] = None,
        quiet_progress_bars: bool = True,
    ) -> structlog.BoundLogger:
        """Configure structured logging; pass quiet_progress_bars=False for a process that streams
        progress."""
        log_level_name = os.getenv("LOG_LEVEL", "INFO").upper()
        log_level = getattr(logging, log_level_name, logging.INFO)

        # Key off the stream encoding, not the platform (Windows, LANG=C).
        for stream in (sys.stdout, sys.stderr):
            if getattr(stream, "encoding", "") and not str(stream.encoding).lower().replace(
                "-", ""
            ).startswith("utf8"):
                if hasattr(stream, "reconfigure"):
                    try:
                        stream.reconfigure(encoding = "utf-8", errors = "replace")
                    except Exception:
                        pass

        structlog.configure(
            processors = [
                # Ordered to control output field order.
                structlog.processors.TimeStamper(fmt = "iso"),
                structlog.processors.add_log_level,
                structlog.contextvars.merge_contextvars,
                structlog.processors.format_exc_info,
                filter_sensitive_data,
                # After redaction: truncating first could leave half a path the redactor misses.
                _truncate_exception_processor,
                # Flatten the extra field into the main dict.
                lambda logger, method_name, event_dict: {
                    "timestamp": event_dict.get("timestamp"),
                    "level": event_dict.get("level"),
                    "event": event_dict.get("event"),
                    **(event_dict.get("extra", {})),
                    **{
                        k: v
                        for k, v in event_dict.items()
                        if k not in ["timestamp", "level", "event", "extra"]
                    },
                },
                (
                    # Preserve order; the wrapper adds the human-readable traceback copy.
                    with_readable_traceback(structlog.processors.JSONRenderer(sort_keys = False))
                    if env == "production"
                    else structlog.dev.ConsoleRenderer()
                ),
            ],
            wrapper_class = structlog.make_filtering_bound_logger(log_level),
            logger_factory = _current_stdout_logger_factory,
            cache_logger_on_first_use = True,
        )

        # Silence third-party tqdm bars; they carry no signal and corrupt JSON records.
        if quiet_progress_bars:
            quiet_third_party_progress_bars()

        # Drop transformers' cosmetic "`torch_dtype` is deprecated" warning_once (see filter).
        _dtype_filter = _DropTorchDtypeDeprecation()
        for _name in (
            "transformers.configuration_utils",
            "transformers.modeling_utils",
            "transformers.pipelines.base",
        ):
            logging.getLogger(_name).addFilter(_dtype_filter)

        return structlog.get_logger(service_name)