Implementation:Hiyouga LLaMA Factory V1 Logging

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

Overview

This module provides rank-aware logging infrastructure for the LLaMA-Factory v1 system, ensuring clean log output in distributed training by suppressing duplicate messages from non-primary processes.

Description

The module configures a library root logger (llamafactory.v1) with a stdout StreamHandler using a timestamped format ([LEVEL|YYYY-MM-DD HH:MM:SS] name:line >> message). It defines a custom _Logger class with info_rank0, warning_rank0, and warning_rank0_once convenience methods. These methods are also monkey-patched onto the standard logging.Logger class, gating log output on LOCAL_RANK=0 via the LOCAL_RANK environment variable. The warning_rank0_once function uses @lru_cache(None) to ensure warnings are emitted only once per unique message. Log verbosity can be controlled via the LLAMAFACTORY_VERBOSITY environment variable. Thread-safe configuration is ensured via a reentrant lock.

Usage

Use get_logger(__name__) to obtain a logger instance in any module within the v1 package. Use info_rank0 and warning_rank0 methods on the logger to emit messages only from the primary process in distributed training. Use add_handler and remove_handler to customize the logging pipeline.

Code Reference

Source Location

• Repository: Hiyouga_LLaMA_Factory
• File: src/llamafactory/v1/utils/logging.py
• Lines: 1-123

Signature

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: ...

# Monkey-patched onto logging.Logger:
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.v1.utils.logging import get_logger, add_handler, remove_handler

I/O Contract

Inputs

Name	Type	Required	Description
name (get_logger)	str or None	No	Logger name; defaults to the library root name ("llamafactory.v1")
handler (add_handler)	logging.Handler	Yes	Handler to add to the library root logger
handler (remove_handler)	logging.Handler	Yes	Handler to remove from the library root logger
LLAMAFACTORY_VERBOSITY	env var (str)	No	Environment variable to set log level (e.g., "DEBUG", "WARNING")
LOCAL_RANK	env var (str)	No	Environment variable indicating the local process rank; rank0 methods only log when this is "0"

Outputs

Name	Type	Description
get_logger	_Logger	Configured logger instance with rank-aware methods
add_handler	None	Side effect: adds handler to root logger
remove_handler	None	Side effect: removes handler from root logger

Usage Examples

from llamafactory.v1.utils.logging import get_logger

logger = get_logger(__name__)

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

# Rank-0 only logging (distributed training)
logger.info_rank0("This only prints on the primary process.")
logger.warning_rank0("Warning only on rank 0.")
logger.warning_rank0_once("This warning appears only once, on rank 0.")

# Controlling verbosity via environment variable
# export LLAMAFACTORY_VERBOSITY=DEBUG

Related Pages

• Hiyouga_LLaMA_Factory_V1_Plugin_System - Plugin system that uses this logging module
• Hiyouga_LLaMA_Factory_V1_Types - Type definitions used across the v1 module