Implementation:Hiyouga LLaMA Factory Logging

Knowledge Sources	Hiyouga_LLaMA_Factory
Domains	Infrastructure, Distributed Training
Last Updated	2026-02-06 19:00 GMT

Overview

Custom logging framework with rank-aware distributed logging support and asynchronous file-based log output for LLaMA Board.

Description

This module configures a library root logger with a stdout stream handler and a structured format including level, timestamp, filename, and line number. It provides LoggerHandler, a specialized handler that writes log entries to a file asynchronously via a single-threaded ThreadPoolExecutor, designed for the LLaMA Board web UI. The module monkey-patches Python's logging.Logger class with three rank-aware methods: info_rank0, warning_rank0, and warning_rank0_once (LRU-cached). These methods check the LOCAL_RANK environment variable and only emit log messages on the main process (rank 0) in distributed training, preventing duplicate log output across multiple GPUs. The logging level can be configured via the LLAMAFACTORY_VERBOSITY environment variable.

Usage

Use get_logger(__name__) at the top of any module to obtain a logger instance. Use info_rank0 and warning_rank0 instead of standard info and warning methods when logging in code that runs across distributed processes. Use LoggerHandler when running the LLaMA Board to redirect logs to a file for the web UI.

Code Reference

Source Location

• Repository: Hiyouga_LLaMA_Factory
• File: src/llamafactory/extras/logging.py
• Lines: 1-160

Signature

class LoggerHandler(logging.Handler):
    def __init__(self, output_dir: str) -> None
    def emit(self, record) -> None
    def close(self) -> None

class _Logger(logging.Logger):
    def info_rank0(self, *args, **kwargs) -> None
    def warning_rank0(self, *args, **kwargs) -> None
    def warning_rank0_once(self, *args, **kwargs) -> None

def get_logger(name: str | None = None) -> "_Logger"
def add_handler(handler: "logging.Handler") -> None
def remove_handler(handler: logging.Handler) -> None
def info_rank0(self: "logging.Logger", *args, **kwargs) -> None
def warning_rank0(self: "logging.Logger", *args, **kwargs) -> None
def warning_rank0_once(self: "logging.Logger", *args, **kwargs) -> None

Import

from llamafactory.extras.logging import get_logger, LoggerHandler, add_handler, remove_handler

I/O Contract

Inputs

Name	Type	Required	Description
name	None	No	Logger name; defaults to the library root name if None (for get_logger)
output_dir	str	Yes	Directory where the running log file will be written (for LoggerHandler)
LLAMAFACTORY_VERBOSITY	env var	No	Environment variable to set the logging level (e.g., "DEBUG", "INFO", "WARNING")
LOCAL_RANK	env var	No	Environment variable indicating the local process rank in distributed training; rank-aware methods only log when this is "0"

Outputs

Name	Type	Description
logger	_Logger	A configured logger instance with rank-aware logging methods
running_log	file	Log file written by LoggerHandler at <output_dir>/running_log.txt

Usage Examples

from llamafactory.extras.logging import get_logger

logger = get_logger(__name__)

# Standard logging (appears on all ranks)
logger.info("This message appears on all ranks.")

# Rank-aware logging (only on LOCAL_RANK=0)
logger.info_rank0("This message only appears on the main process.")
logger.warning_rank0("Warning from main process only.")
logger.warning_rank0_once("This warning appears only once, on the main process.")

from llamafactory.extras.logging import LoggerHandler, add_handler

# Add a file handler for LLaMA Board
handler = LoggerHandler(output_dir="/path/to/output")
add_handler(handler)

Related Pages

• Hiyouga_LLaMA_Factory_Ploting - Uses the logging framework for warning messages when plotting metrics
• Hiyouga_LLaMA_Factory_Evaluator - Uses rank-aware logging during evaluation
• Hiyouga_LLaMA_Factory_Supervised_Processor - Uses warning_rank0 for dropped example warnings
• Hiyouga_LLaMA_Factory_Feedback_Processor - Uses warning_rank0 for validation warnings