Python使用colorlog库为日志添加色彩编码_Python

还在看单调的黑白日志吗？给日志加点颜色，让调试变得更高效！

前言：为什么需要彩色日志？

在日常开发和调试中，日志是我们最亲密的伙伴。但是，面对密密麻麻的黑白日志文本，快速定位错误、警告或关键信息往往如同大海捞针。这时候，colorlog 库就能大显身手了！它能为不同级别的日志信息添加不同的颜色，让日志输出一目了然，大大提升调试效率。

使用 colorlog 为日志添加色彩编码，能让不同严重级别的信息一目了然，从而提升调试体验。

什么是 colorlog？

colorlog 是一个 python 日志格式化工具，它扩展了 python 标准库中的 logging 模块，专门用于在终端输出带颜色的日志。通过为不同日志级别配置不同颜色，我们可以快速区分 debug、info、warning、error 等级别的信息。

安装 colorlog

安装 colorlog 非常简单，只需使用 pip：

pip install colorlog

基础用法：快速上手

让我们先来看一个简单的例子，了解 colorlog 的基本使用方法：

import colorlog
import logging

# 创建 logger 实例
logger = colorlog.getlogger('example')

# 创建 streamhandler
handler = colorlog.streamhandler()

# 设置格式化器
handler.setformatter(colorlog.coloredformatter(
    '%(log_color)s%(levelname)s:%(name)s:%(message)s'
))

# 添加 handler 到 logger
logger.addhandler(handler)

# 设置日志级别
logger.setlevel(logging.debug)

# 测试不同级别的日志输出
logger.debug("这是一条 debug 级别的日志")
logger.info("这是一条 info 级别的日志")
logger.warning("这是一条 warning 级别的日志")
logger.error("这是一条 error 级别的日志")
logger.critical("这是一条 critical 级别的日志")

运行上面的代码，你将在终端中看到不同颜色的日志输出，默认情况下：

debug：青色
info：绿色
warning：黄色
error：红色
critical：红色背景白色文字

核心组件详解

coloredformatter 类

coloredformatter 是 colorlog 的核心类，它继承自 python 标准的 logging.formatter，专门用于生成带颜色的日志输出。

主要参数说明：

format：用于输出日志的格式化字符串（必需）
datefmt：可选的日期格式，传递给基类
reset：默认为 true，表示在消息输出结束时添加颜色重置代码
log_colors：日志级别到颜色名称的映射
secondary_log_colors：定义在格式化字符串中可用的其他颜色
style：在 python 3.2 以上版本可用

颜色配置详解

colorlog 支持丰富的颜色配置选项：

基本颜色名称： black, red, green, yellow, blue, purple, cyan, white

颜色前缀：

fg_{color}：设置前景色（文字颜色）
bg_{color}：设置背景色
bold、bold_{color}：设置粗体/亮色

特殊代码：

reset：清除所有格式（包括前景色和背景色）

高级配置技巧

1. 自定义日志颜色

你可以完全自定义每个日志级别的颜色：

from colorlog import coloredformatter

formatter = coloredformatter(
    "%(log_color)s%(levelname)-8s%(reset)s %(blue)s%(message)s",
    datefmt=none,
    reset=true,
    log_colors={
        'debug': 'cyan',
        'info': 'green',
        'warning': 'yellow',
        'error': 'red',
        'critical': 'red,bg_white',
    },
    secondary_log_colors={},
    style='%'
)

handler = logging.streamhandler()
handler.setformatter(formatter)

logger = logging.getlogger('custom_example')
logger.addhandler(handler)
logger.setlevel(logging.debug)

2. 使用辅助颜色

secondary_log_colors 允许你为同一日志消息的不同部分设置不同的颜色规则：

formatter = coloredformatter(
    "%(log_color)s%(levelname)-8s%(reset)s %(message_log_color)s%(message)s",
    secondary_log_colors={
        'message': {
            'error': 'red',
            'critical': 'red'
        }
    }
)

这个配置会让 error 和 critical 级别的日志消息本身显示为红色，而其他级别的消息保持默认颜色。

3. 使用字典配置

对于大型项目，推荐使用 dictconfig 进行配置：

import logging.config

logging.config.dictconfig({
    'formatters': {
        'colored': {
            '()': 'colorlog.coloredformatter',
            'format': "%(log_color)s%(levelname)-8s%(reset)s %(blue)s%(message)s"
        }
    },
    'handlers': {
        'stream': {
            'class': 'logging.streamhandler',
            'formatter': 'colored',
        },
    },
    'root': {
        'handlers': ['stream'],
        'level': 'debug',
    }
})

logger = logging.getlogger('dict_config_example')

4. 配置文件方式

你也可以使用 .ini 格式的配置文件：

[loggers]
keys=root

[logger_root]
handlers=stream
level=debug

[formatters]
keys=color

[formatter_color]
class=colorlog.coloredformatter
format=%(log_color)s%(levelname)s:%(name)s:%(message)s
datefmt=%h:%m:%s

[handlers]
keys=stream

[handler_stream]
class=streamhandler
formatter=color
args=()

然后在代码中加载配置：

import logging
import logging.config

logging.config.fileconfig('logging_config.ini')
logger = logging.getlogger('config_file_example')

实际应用示例

在 fastapi 项目中使用 colorlog

让我们看看如何在 fastapi 项目中使用 colorlog 来美化日志输出：

import colorlog
import logging
from fastapi import fastapi, httpexception
from pydantic import basemodel

# 配置日志
handler = colorlog.streamhandler()
formatter = colorlog.coloredformatter(
    "%(log_color)s%(asctime)s - %(levelname)-8s%(reset)s %(blue)s%(name)-15s %(message)s",
    datefmt="%y-%m-%d %h:%m:%s",
    log_colors={
        'debug': 'cyan',
        'info': 'bold_green',
        'warning': 'bold_yellow',
        'error': 'bold_red',
        'critical': 'bold_red,bg_white',
    }
)
handler.setformatter(formatter)

# 为 fastapi 相关日志器配置 colorlog
uvicorn_logger = logging.getlogger("uvicorn")
uvicorn_logger.handlers = []
uvicorn_logger.addhandler(handler)
uvicorn_logger.setlevel(logging.debug)

uvicorn_access = logging.getlogger("uvicorn.access")
uvicorn_access.handlers = []
uvicorn_access.addhandler(handler)

app = fastapi(title="colorful api", version="1.0.0")
logger = colorlog.getlogger("api")
logger.addhandler(handler)
logger.setlevel(logging.debug)

class item(basemodel):
    name: str
    description: str = none
    price: float

@app.get("/")
async def read_root():
    logger.info("访问根路径")
    return {"message": "欢迎使用彩色日志 api！"}

@app.post("/items/")
async def create_item(item: item):
    logger.debug(f"创建商品: {item.name}, 价格: {item.price}")
    
    if item.price <= 0:
        logger.warning(f"商品价格无效: {item.price}")
        raise httpexception(status_code=400, detail="价格必须大于0")
    
    logger.info(f"成功创建商品: {item.name}")
    return {"status": "success", "item": item}

@app.get("/error-test")
async def error_test():
    try:
        # 模拟一个错误
        result = 1 / 0
    except exception as e:
        logger.error(f"发生错误: {str(e)}", exc_info=true)
        raise httpexception(status_code=500, detail="内部服务器错误")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, log_config=none)

同时输出到控制台和文件

有时候，我们既想要在控制台看到彩色日志，又希望将日志保存到文件中（不包含颜色代码）：

import colorlog
import logging

# 创建 logger
logger = colorlog.getlogger('multi_handler')

# 控制台 handler（带颜色）
console_handler = colorlog.streamhandler()
console_formatter = colorlog.coloredformatter(
    "%(log_color)s%(asctime)s %(levelname)-8s%(reset)s %(blue)s%(message)s",
    datefmt="%h:%m:%s"
)
console_handler.setformatter(console_formatter)

# 文件 handler（无颜色）
file_handler = logging.filehandler('app.log')
file_formatter = logging.formatter(
    "%(asctime)s %(levelname)-8s %(message)s",
    datefmt="%y-%m-%d %h:%m:%s"
)
file_handler.setformatter(file_formatter)

# 添加两个 handler
logger.addhandler(console_handler)
logger.addhandler(file_handler)
logger.setlevel(logging.debug)

# 测试日志
logger.info("这条消息会同时显示在控制台（带颜色）和文件（无颜色）中")

自定义日志级别

你甚至可以创建自定义的日志级别并为其指定颜色：

import logging
import colorlog

# 创建自定义日志级别
trace = 5
logging.addlevelname(trace, 'trace')

# 添加 trace 方法到 logger
def trace(self, message, *args, **kws):
    if self.isenabledfor(trace):
        self._log(trace, message, args, **kws)

logging.logger.trace = trace

# 配置 colorlog 包含自定义级别
formatter = colorlog.coloredformatter(
    log_colors={
        'trace': 'yellow',
        'debug': 'cyan',
        'info': 'green',
        'warning': 'yellow',
        'error': 'red',
        'critical': 'red,bg_white',
    },
    format='%(log_color)s%(levelname)-8s%(reset)s %(message)s'
)

handler = logging.streamhandler()
handler.setformatter(formatter)

logger = colorlog.getlogger('custom_level')
logger.addhandler(handler)
logger.setlevel(trace)

# 使用自定义级别
logger.trace("这是一条 trace 级别的日志")