elegant-log 0.1.2

现代化的Python日志库

ElegantLog

现代化的 Python 日志库，重点解决这几类问题：

• 多进程场景下的文件日志
• 按大小 / 按服务器本地时间跨午夜轮转
• 父子 logger 重复输出
• JSON 结构化日志
• print() 增强与全局异常捕获
• Web 框架中的日志恢复与稳定性

安装

pip install elegant-log

要求：

• Python >= 3.12

文档

• 文档入口
• 进阶指南
• JSON 日志指南
• 开发者指南
• 示例代码

快速开始

最小示例

import elegantlog

logger = elegantlog.get_logger("myapp")
logger.info("应用已启动")
logger.warning("这是一条警告")
logger.error("这是一条错误")

输出到文件

logger = elegantlog.get_logger(
    name="myapp",
    file=True,
    log_dir="./logs",
    console=True,
)

logger.info("日志将写入 ./logs/myapp_{pid}.log")

说明：

• 活动文件命名：myapp_{pid}.log
• 每个进程独立文件，避免多进程锁竞争

启用日志轮转

rotation_by_date=False：只按大小轮转

logger = elegantlog.get_logger(
    name="myapp_size_only",
    file=True,
    log_dir="./logs",
    rotation_by_size=True,
    max_file_size=50 * 1024 * 1024,
    rotation_by_date=False,
    backup_count=7,
)

适用场景：

• 只关心控制单个日志文件大小
• 不需要按天切分日志

rotation_by_date=True：按服务器本地时间跨午夜轮转

logger = elegantlog.get_logger(
    name="myapp_daily",
    file=True,
    log_dir="./logs",
    rotation_by_size=True,
    max_file_size=50 * 1024 * 1024,
    rotation_by_date=True,
    backup_count=7,
)

归档文件命名示例：

• myapp_{pid}_20240115_143025_0001.log

日期轮转说明：

• rotation_by_date=True 时，按服务器本地时间在跨午夜时轮转
• 迟到日志不会回写历史日期文件
• 如果需要按事件发生日期归档，应交给外部日志收集或归档系统处理

性能相关配置

logger = elegantlog.get_logger(
    name="high_performance",
    file=True,
    batch_size=500,
    flush_interval=2.0,
    async_mode=True,
)

Print 增强

from elegantlog import enable_print_enhancement

enable_print_enhancement()
print("带时间戳和调用位置的输出")

异常捕获

from elegantlog import enable_exception_capture

logger = elegantlog.get_logger("myapp", file=True)
enable_exception_capture(logger)

JSON 日志

import elegantlog
from elegantlog import JsonFormatter

logger = elegantlog.get_logger("myapp", file=True)
formatter = JsonFormatter(
    static_fields={"service": "myapp", "environment": "production"}
)

for handler in logger.handlers:
    handler.setFormatter(formatter)

logger.info("用户登录", extra={"user_id": "user123", "ip": "192.168.1.1"})

更多内容：

• JSON 输出结构、配置项和接入方式见 docs/JSON_LOGGING.md
• JSON 内部设计与维护说明见 docs/JSON_INTERNALS.md

常用 API

elegantlog.get_logger(name, **kwargs)
elegantlog.configure(config)
elegantlog.set_exclusive_handler(name, handler_type, **kwargs)
elegantlog.clear_handlers(name)
elegantlog.replace_handler(name, old_handler_type, new_handler_type, **kwargs)

下一步看什么

如果你已经完成基础接入，建议按这个顺序继续阅读：

1. docs/ADVANCED_GUIDE.md
2. 如果使用 JSON 输出，再看 docs/JSON_LOGGING.md
3. 如果你要参与仓库开发，再看 docs/DEVELOPER_GUIDE.md