在 Python 中建立 log（日志）系统，**最推荐的方式是使用标准库 logging 模块，通过创建 Logger、Handler 与 Formatter，实现分级记录、格式化输出和多渠道保存**。相比简单的 print 输出，日志系统支持级别控制、文件持久化、滚动切分、异常追踪与生产环境调优，是构建稳定应用和可维护系统的基础能力。本文将系统讲解 Python 日志的完整搭建方法、配置策略与企业级最佳实践。

## 一、为什么 Python 项目必须建立日志系统

在任何 Python 应用开发中，无论是 Web 服务、数据处理脚本，还是自动化运维程序，日志系统（logging system）都是保障稳定性和可观测性的核心基础设施。相比 print 输出，日志记录不仅能够区分不同严重程度，还能将日志写入文件、控制台甚至远程系统，从而形成可审计、可追踪的运行记录。

**建立标准化日志体系的核心价值在于：提升可维护性、支持问题排查、增强系统可观测性。** 在生产环境中，如果没有结构化的日志输出，当程序出现异常时往往难以定位问题源头。尤其在多线程、多进程或分布式场景下，日志系统是唯一可靠的行为记录方式。

根据 Python 官方文档（Python Docs, Logging HOWTO, 2024），logging 模块自 Python 2.3 起就成为标准库的一部分，设计目标就是提供灵活、可扩展的日志框架。因此，掌握 logging 的正确用法，是 Python 开发者的基础能力之一。

---

## 二、Python logging 模块核心结构详解

Python 建立 log 系统的核心是 logging 模块，其架构主要由四个核心组件组成：Logger、Handler、Formatter 和 Filter。这四个模块共同组成完整的日志系统架构。

**Logger（记录器）** 是日志系统的入口。开发者通过 logger.info()、logger.error() 等方法输出日志信息。每个模块通常使用独立的 Logger，从而实现模块级日志隔离。

**Handler（处理器）** 决定日志输出位置，比如输出到控制台（StreamHandler）、文件（FileHandler）、滚动文件（RotatingFileHandler）等。

**Formatter（格式器）** 决定日志显示格式，比如时间、模块名、等级、行号等信息。

**Filter（过滤器）** 用于进一步筛选日志内容或级别。

下面是 logging 核心组件关系对比：

| 组件 | 作用 | 是否必须 | 常见类型 |
|------|------|----------|----------|
| Logger | 产生日志 | 是 | root logger、自定义 logger |
| Handler | 决定输出位置 | 是 | StreamHandler、FileHandler |
| Formatter | 定义输出格式 | 否 | 自定义格式字符串 |
| Filter | 日志过滤 | 否 | 自定义过滤逻辑 |

理解这四个组件后，我们才能构建完整的 Python 日志系统。

---

## 三、Python 建立最基础的日志系统

在 Python 中建立 log 的最简单方式是使用 basicConfig() 方法。它适用于小型脚本或简单项目。

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

logging.info("程序启动")
logging.error("发生错误")
```

这段代码实现了最基础的 Python 日志系统。核心配置包括：

- level：日志级别
- format：日志格式
- 默认输出到控制台

Python logging 的默认日志等级如下：

| 等级 | 数值 | 使用场景 |
|------|------|----------|
| DEBUG | 10 | 调试信息 |
| INFO | 20 | 正常运行信息 |
| WARNING | 30 | 潜在问题 |
| ERROR | 40 | 错误 |
| CRITICAL | 50 | 严重错误 |

**日志级别控制是日志系统的核心能力。** 如果设置 level=logging.INFO，则 DEBUG 级别日志不会输出。

但在实际项目中，basicConfig 通常不够灵活，因此我们需要更高级配置方式。

---

## 四、Python 如何建立文件日志（FileHandler）

在真实项目中，日志通常需要保存到文件中，便于后续排查问题。这时就需要使用 FileHandler。

```python
import logging

logger = logging.getLogger("my_logger")
logger.setLevel(logging.INFO)

file_handler = logging.FileHandler("app.log", encoding="utf-8")
formatter = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

file_handler.setFormatter(formatter)
logger.addHandler(file_handler)

logger.info("日志写入文件")
```

这段代码展示了完整的 Python 建立日志流程：

1. 创建 Logger
2. 设置日志级别
3. 创建 FileHandler
4. 设置 Formatter
5. 添加 Handler

**相比 basicConfig，这种方式更加灵活，可支持多 Handler 输出。**

---

## 五、Python 日志滚动机制（防止日志文件过大）

在生产环境中，如果日志文件不断增长，可能会占满磁盘空间。因此，Python logging 提供了滚动日志机制。

常用的有：

- RotatingFileHandler（按大小滚动）
- TimedRotatingFileHandler（按时间滚动）

示例：

```python
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    "app.log",
    maxBytes=1024*1024,
    backupCount=3
)
```

参数说明：

- maxBytes：文件最大字节数
- backupCount：保留历史文件数量

滚动策略对比如下：

| 类型 | 控制方式 | 适用场景 |
|------|----------|----------|
| RotatingFileHandler | 文件大小 | 高并发系统 |
| TimedRotatingFileHandler | 时间周期 | 定期归档系统 |

**合理设置日志滚动，是企业级 Python 日志系统的重要优化点。**

---

## 六、Python 多模块项目如何建立统一日志体系

在中大型项目中，每个模块都应该使用独立 logger，但统一配置。

推荐写法：

```python
logger = logging.getLogger(__name__)
```

使用 `__name__` 可以自动根据模块名创建 logger，实现分模块日志记录。

在主程序中统一配置：

```python
logging.config.dictConfig(config_dict)
```

这种方式适合大型系统。

根据 Python 官方文档（Python Logging Cookbook, 2024），推荐在大型项目中使用 dictConfig 或 fileConfig 来管理日志配置，而不是在各模块重复配置。

**统一配置、模块独立，是 Python 日志架构的最佳实践。**

---

## 七、Python 日志格式优化与结构化输出

默认日志是字符串格式，但现代系统更推荐结构化日志（JSON 格式），便于日志分析系统处理。

例如：

```python
'%(asctime)s %(levelname)s %(name)s %(message)s'
```

企业环境中常加入：

- 进程ID
- 线程ID
- 文件名
- 行号

```python
'%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d'
```

结构化日志的优势：

| 维度 | 普通文本日志 | 结构化日志 |
|------|--------------|------------|
| 可读性 | 高 | 中 |
| 机器解析 | 低 | 高 |
| 数据分析 | 困难 | 容易 |

**结构化日志是现代 Python 日志系统的趋势。**

---

## 八、Python 异常日志记录最佳实践

异常记录是日志系统最重要的用途之一。

推荐写法：

```python
try:
    1 / 0
except Exception:
    logger.exception("发生异常")
```

logger.exception 会自动记录 traceback 信息。

**相比 logger.error，exception 会附带完整堆栈信息，更利于排查问题。**

---

## 九、企业级 Python 日志系统搭建完整示例

下面是一个完整企业级日志配置示例：

```python
import logging
from logging.handlers import TimedRotatingFileHandler

def setup_logger():
    logger = logging.getLogger("project")
    logger.setLevel(logging.INFO)

    handler = TimedRotatingFileHandler(
        "project.log",
        when="midnight",
        backupCount=7,
        encoding="utf-8"
    )

    formatter = logging.Formatter(
        '%(asctime)s - %(levelname)s - %(name)s - %(message)s'
    )

    handler.setFormatter(formatter)
    logger.addHandler(handler)

    return logger
```

该配置具备：

- 日志分级
- 时间滚动
- 编码支持
- 格式规范
- 可扩展性

---

## 十、总结：Python 建立日志系统的未来趋势

随着系统复杂度提升，Python 建立 log 系统不再只是简单输出，而是演变为可观测性体系的一部分。未来趋势包括：

- 结构化日志
- 日志与监控整合
- 分布式日志追踪
- 可视化分析平台集成

**标准 logging 模块依然是最稳定、可靠的选择。** 掌握 Logger、Handler、Formatter 架构，是构建高质量 Python 应用的关键。

无论是小型脚本还是大型服务，建立规范的 Python 日志系统，都能大幅提升系统稳定性和问题排查效率。

---

参考与资料来源：

Python 官方文档 – Logging HOWTO（2024）  
Python 官方文档 – Logging Cookbook（2024）

Python提供了内置的logging模块，可以方便地创建日志。通过导入logging模块，使用logging.basicConfig()函数设置日志级别、日志格式和输出位置。然后调用logging.debug()、logging.info()、logging.warning()等方法记录不同级别的日志信息。

使用Python内置logging模块设置日志

我刚开始学习Python，想知道如何简单地创建和配置日志系统来跟踪程序运行状态。

Python中如何开始设置日志记录？

Python的logging模块中常用的日志级别有DEBUG、INFO、WARNING、ERROR和CRITICAL。DEBUG用于调试信息，INFO表示运行状态信息，WARNING代表潜在问题，ERROR记录错误事件，CRITICAL表明严重错误。选择日志级别时，应根据信息的重要性和用途来决定。

Python日志级别及其适用场景说明

我想了解在Python中记录日志时，不同的日志级别分别代表什么含义，方便我选择正确的级别进行记录。

Python日志中的不同日志级别有哪些？

可以在logging.basicConfig()函数中通过filename参数指定日志文件路径，这样日志信息会写入指定文件。此外，还可以使用FileHandler对象实现更灵活的日志文件管理，比如按大小或时间切割日志文件。确保配置适当的日志格式和级别以满足需求。

将Python日志输出到文件的方法

我想把Python程序运行时的日志信息保存到文件中以便后续查看，具体怎么做？

在Python中如何将日志保存到文件？

PingCodeDocs

在 Python 中建立日志系统最推荐使用标准库 logging 模块，通过 Logger、Handler 与 Formatter 组合实现分级输出、文件持久化和滚动管理。相比简单的 print 输出，日志系统支持异常追踪、模块隔离和生产环境优化，是构建稳定应用的基础能力。通过合理设置日志级别、文件滚动机制和统一配置方式，可以搭建适用于企业级项目的高可维护日志体系。未来趋势包括结构化日志与可观测性整合，掌握 logging 架构是 Python 开发的重要能力。

python怎么建立log

用户关注问题