mlog-util 2026.5.10

多进程安全的日志轮转工具，基于 Python logging 扩展

mlog-util

多进程安全的 Python 日志轮转工具，基于标准 logging 模块扩展。

特性

• 多进程安全 — 基于 portalocker 文件锁 + 临时文件机制，多进程同时写入不丢日志
• 大小轮转 — 文件达到阈值自动轮转，支持 "1 M"、"5K"、"2G" 等可读格式
• 时间轮转 — 按 S / M / H / D / MIDNIGHT 轮转，多进程共享轮转时间点
• 分级别输出 — 通过 HandlerConfig 为每个 handler 独立配置级别、格式、Filter
• 开箱即用 — setup_logging("project") 一行生成 task / detail / error 三文件日志体系
• Rich 控制台 — 默认彩色终端输出

安装

pip install mlog-util

快速开始

Tier 1：一行搞定（推荐）

from mlog_util import setup_logging

logger = setup_logging("my_project")
logger.info("任务开始")

自动生成 logs/my_project/ 目录：

logs/my_project/
├── task.log      # 任务流程日志
├── detail.log    # 全量日志（INFO+）
└── error.log     # 仅 ERROR

项目中的 logging.getLogger(__name__) 自动接入 detail.log 和 error.log，无需额外配置。

Tier 2：分级别 / Filter / 自定义格式

from mlog_util import get_logger, HandlerConfig, MultiProcessSafeSizeRotatingHandler
import logging

err_h = MultiProcessSafeSizeRotatingHandler("logs/error.log")
info_h = MultiProcessSafeSizeRotatingHandler("logs/info.log")

logger = get_logger("my_app", add_console=True, custom_handlers=[
    HandlerConfig(err_h, level=logging.ERROR),
    HandlerConfig(info_h, level=logging.INFO),
])

logger.info("进入 info.log")
logger.error("进入 error.log")

Tier 3：完全自由的日志拓扑

from mlog_util import get_logger, MultiProcessSafeTimeRotatingHandler, make_formatter, FORMAT_JSON
import logging

task_log = get_logger("task", log_file="logs/task.log", add_console=True)

root = logging.getLogger()
root.setLevel(logging.DEBUG)

detail_h = MultiProcessSafeSizeRotatingHandler("logs/detail.log", maxBytes=10*1024*1024)
detail_h.setFormatter(make_formatter())
root.addHandler(detail_h)

error_h = MultiProcessSafeTimeRotatingHandler("logs/error.log", when="D")
error_h.setFormatter(make_formatter(FORMAT_JSON))
error_h.setLevel(logging.ERROR)
root.addHandler(error_h)

Handler 类型

Handler	触发方式	默认参数	场景
MultiProcessSafeSizeRotatingHandler	文件大小	maxBytes=5MB	通用
MultiProcessSafeTimeRotatingHandler	时间间隔	when="D"	周期性任务

Formatter 预设

常量	输出示例
FORMAT_DETAIL	2026-05-10 21:00:00 | module | INFO | 消息
FORMAT_SIMPLE	2026-05-10 21:00:00 | 消息
FORMAT_PLAIN	module - INFO - 消息
FORMAT_JSON	{"time":"...","name":"module","level":"INFO","msg":"消息"}

开发

# 安装依赖
uv sync

# 运行测试
uv run python -m pytest tests/ -v

文档

• 使用指南 — 三层用法详解
• 测试计划

变更记录

v2026.05.10

• 新增 setup_logging 一站式三文件日志配置
• 新增 __init__.py 模块级文档和使用示例
• 新增 docs/usage.md 三层用法指南

v2026.04.28

• log_manager 优化
  • 新增预设 Formatter 常量：FORMAT_DETAIL、FORMAT_SIMPLE、FORMAT_PLAIN、FORMAT_JSON 和 make_formatter() 工厂函数
  • custom_handlers 支持列表和 HandlerConfig，可为每个 handler 单独配置级别、格式、过滤条件
  • HandlerConfig(handler, level=ERROR, formatter=fmt, filters=[...])
• handlers 修复
  • maxBytes 支持 G 单位（"2G"）
  • maxBytes 解析前自动去除空格
  • 修复极端并发下临时文件竞态导致的日志丢失
• 添加 pytest 测试套件（85 个测试），添加 dev/ 演示脚本

v0.1.7 - 2025-10-28

• 时间轮询基准时间从 UTC 改为本地时间
• 新增轮询时间和文件大小（默认 1 天 + 5MB）

v2025.12.03

• 删除时间轮询方式
• 修改文件大小轮询方式

v2025.12.11

• 重新添加时间轮询方式，添加测试

v2025.12.16

• 修改 format 为 %(asctime)s | %(name)-8s | %(levelname)-4s | %(message)s

v2025.12.23

• 调整时间轮询默认值为天

v0.1.6 - 2025-10-17

• 调整整体结构，修复 v0.1.4 不可用问题

v0.1.5 - 2025-10-17

v0.1.4 - 2025-10-17

• 调整 log_manager 模块结构