Python Logging库完全指南：从小白到熟练一、为什么要使用Logging？很多初学者喜欢用print()调试

一、为什么要使用Logging？

很多初学者喜欢用print()调试，但在实际项目中会遇到问题：

项目跑起来后，不能随意中断程序查看输出
需要区分不同重要程度的信息（错误、警告、普通信息）
需要将日志保存到文件方便后续分析
在生产环境中，需要动态调整日志详细程度

这就是Logging库存在的意义！

二、快速开始：5分钟上手

基础示例

import logging

# 最简单的使用方式
logging.basicConfig(level=logging.WARN)  # 设置日志级别

logging.debug('这是一条debug信息')      # 不会显示（默认级别更高）
logging.info('这是一条info信息')        # 不会显示
logging.warning('这是一条warning信息')  # 会显示√
logging.error('这是一条error信息')      # 会显示√
logging.critical('这是一条critical信息')# 会显示√

理解日志级别（从低到高）

DEBUG - 调试细节，开发时使用
INFO - 普通信息，确认事情按预期运行
WARNING - 警告，发生了意外但不影响运行
ERROR - 错误，部分功能受影响
CRITICAL - 严重错误，程序可能崩溃

重要规则： 只会显示设置级别及以上的日志！

三、核心配置：让日志更实用

1. 配置日志格式和输出

# 详细配置示例
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
    filename='app.log',  # 输出到文件
    filemode='a',         # 追加模式
    encoding='utf-8'     # 指定UTF-8编码，解决中文乱码问题
)


# 使用
logging.info("程序启动")
logging.warning("磁盘空间不足90%")
logging.error("数据库连接失败")

2. 常用格式化字段

%(name)s          Logger的名字
%(levelname)s     日志级别
%(message)s       日志内容
%(asctime)s       时间，可指定格式
%(filename)s      文件名
%(funcName)s      函数名
%(lineno)d        行号

四、进阶技巧：模块化使用

在实际项目中，我们通常不直接使用logging模块，而是创建自己的Logger：

1. 创建模块专用的Logger

# 在每个模块中这样做
import logging


# 创建logger实例，通常以模块名命名
logger = logging.getLogger(__name__)  # 这是最佳实践！


def process_data(data):
    logger.debug(f"开始处理数据，长度: {len(data)}")
    try:
        # 你的业务逻辑
        result = data * 2
        logger.info(f"数据处理成功，结果: {result}")
        return result
    except Exception as e:
        logger.error(f"数据处理失败: {str(e)}", exc_info=True)
        return None

什么是 __name__？

__name__ 是一个特殊的Python变量
当直接运行一个Python文件时，__name__ 的值为 "__main__"
当文件被作为模块导入时，__name__ 的值是模块的路径

例如：

# file: my_module.py
print(__name__)
# 直接运行: "__main__"
# 被导入时: "my_module"

getLogger() 的作用

logging.getLogger(name) 创建或获取指定名称的logger对象
相同名称返回同一个logger实例（单例模式）
logger名称通常使用 __name__，这样：
1. 自动模块化：每个模块有自己的logger
2. 层级结构：logger名称有层级，便于配置

为什么用 __name__ 而不是硬编码？

优点：

# 不好的做法 - 硬编码名称
logger1 = logging.getLogger("database")    # 数据库模块
logger2 = logging.getLogger("web")        # Web模块
logger3 = logging.getLogger("api")        # API模块


# 好的做法 - 使用 __name__
# file: database/connection.py
logger = logging.getLogger(__name__)      # logger名: "database.connection"


# file: web/routes.py
logger = logging.getLogger(__name__)       # logger名: "web.routes"


# file: api/auth.py  
logger = logging.getLogger(__name__)       # logger名: "api.auth"

logger层级结构

root  # 根logger
├── database
│   ├── database.connection
│   └── database.models
├── web
│   ├── web.routes
│   └── web.views
└── api
    ├── api.auth
    └── api.users

这样可以通过配置父logger来影响所有子logger：

# 设置 database 模块的日志级别
logging.getLogger("database").setLevel(logging.DEBUG)
# 所有 database.* 的子logger都会受到影响

实际应用示例

项目结构：
project/
├── main.py
├── database/
│   ├── __init__.py
│   └── connection.py
└── api/
    ├── __init__.py
    └── auth.py

main.py:

import logging
from database.connection import connect_db
from api.auth import authenticate_user


# 配置日志
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)


# 不同模块的logger会自动记录不同名称
connect_db()
authenticate_user()

database/connection.py:

import logging


# logger名称将是 "database.connection"
logger = logging.getLogger(__name__)


def connect_db():
    logger.info("开始连接数据库...")
    # 连接逻辑
    logger.debug("连接参数: host=localhost, port=5432")
    logger.info("数据库连接成功")

api/auth.py:

import logging


# logger名称将是 "api.auth"
logger = logging.getLogger(__name__)


def authenticate_user():
    logger.debug("用户认证开始")
    # 认证逻辑
    logger.info("用户认证成功")

输出示例

2024-01-15 10:30:00 - database.connection - INFO - 开始连接数据库...
2024-01-15 10:30:00 - database.connection - DEBUG - 连接参数: host=localhost, port=5432
2024-01-15 10:30:01 - database.connection - INFO - 数据库连接成功
2024-01-15 10:30:02 - api.auth - DEBUG - 用户认证开始
2024-01-15 10:30:02 - api.auth - INFO - 用户认证成功

在你的代码中如何用好

2. 项目级别的配置

# config_logging.py - 日志配置文件
import logging
import logging.handlers
import os


def setup_logging():
    """配置项目日志系统"""
    
    # 创建formatter（定义日志格式）
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
    )
    
    # 创建logger
    logger = logging.getLogger()  # 根logger
    logger.setLevel(logging.DEBUG)  # 设置最低级别
    
    # 控制台处理器
    console_handler = logging.StreamHandler()
    console_handler.setLevel(logging.INFO)  # 控制台只显示INFO及以上
    console_handler.setFormatter(formatter)
    
    # 文件处理器
    file_handler = logging.FileHandler('app.log')
    file_handler.setLevel(logging.DEBUG)  # 文件记录所有DEBUG及以上
    file_handler.setFormatter(formatter)
    
    # 按时间切分的文件处理器（推荐生产环境使用）
    time_handler = logging.handlers.TimedRotatingFileHandler(
        'app.log',
        when='midnight',  # 每天午夜切分
        interval=1,
        backupCount=7     # 保留7天
    )
    time_handler.setFormatter(formatter)
    
    # 添加处理器
    logger.addHandler(console_handler)
    logger.addHandler(file_handler)
    # logger.addHandler(time_handler)  # 使用这个替换上面的file_handler

五、实用场景示例

场景1：Web应用日志

import logging
from logging.handlers import RotatingFileHandler


# 创建logger
logger = logging.getLogger('webapp')
logger.setLevel(logging.INFO)


# 按大小滚动日志文件（最大10MB，保留5个备份）
handler = RotatingFileHandler(
    'webapp.log',
    maxBytes=10*1024*1024,  # 10MB
    backupCount=5
)


formatter = logging.Formatter(
    '%(asctime)s - %(clientip)s - %(user)s - %(message)s'
)
handler.setFormatter(formatter)
logger.addHandler(handler)


# 使用（假设在请求处理中）
def handle_request(request, user):
    # 添加额外信息
    extra = {'clientip': request.client_ip, 'user': user}
    logger.info('用户登录成功', extra=extra)

场景2：不同级别日志分开存储

import logging


# 配置不同的处理器
logger = logging.getLogger('myapp')


# 错误日志单独保存
error_handler = logging.FileHandler('errors.log')
error_handler.setLevel(logging.ERROR)


# 所有日志保存
all_handler = logging.FileHandler('all.log')
all_handler.setLevel(logging.DEBUG)


# 设置格式
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
error_handler.setFormatter(formatter)
all_handler.setFormatter(formatter)


logger.addHandler(error_handler)
logger.addHandler(all_handler)

六、最佳实践和小贴士

✅ 应该这样做：

尽早配置日志：在程序入口处配置，不要多处配置
使用getLogger(__name__) ：自动获取模块名作为logger名
合理使用级别：
- DEBUG：调试信息
- INFO：关键流程节点
- WARNING：可预料的问题
- ERROR：需要关注的错误
包含上下文信息：logger.error(f"用户{user_id}操作失败")

避免这样做：

不要在所有地方都用根logger
不要在日志中记录敏感信息（密码、密钥）
不要过度记录，避免日志过大

总结

Logging库看似复杂，但核心只有几个概念：

Logger - 记录器（谁在记录）
Handler - 处理器（记录到哪里）
Formatter - 格式化器（怎么记录）
Level - 级别（记录什么）