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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# 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)