如何在Python日志中优雅地打印Pandas DataFrame？

为什么直接把DataFrame对象传给logging.info()后，日志文件里经常出现一长串省略号？原因不在于logging库，而在于pandas的显示策略与日志场景并不匹配。DataFrame在交互式环境中的输出会依据终端宽度自动折叠行和列，这套逻辑在写入日志时仍然生效，最终造成关键字段被截断、表格结构难以辨认。

日志记录和Notebook展示的目的不同：前者需要可追溯、可搜索的结构化文本，后者需要适应屏幕的概览。因此，直接在日志中打印DataFrame需要额外的格式控制。接下来从pandas自身的to_string()方法入手，逐步介绍更完整的实践方案。

一、问题根源：DataFrame的显示逻辑与日志场景不匹配

在Jupyter或终端里打印df时，pandas会根据当前终端宽度自动裁剪列和行，并生成带省略号的概览。这个行为由display.max_rows、display.max_columns和display.width等选项控制。当你在日志中执行logging.info(df)时，pandas仍然使用同一套显示选项，日志输出没有固定宽度，结果就是列方向被强制截断，某些关键字段只剩前几个字符。

更麻烦的是，DataFrame的字符串表示本质上是一个多行文本。logging会把它作为单条消息写入，若你配置了%(message)s之外的前缀，只有第一行能对齐前缀，后续行会顶格出现。在多线程或多进程环境下，多个DataFrame的多行日志还可能交叉写入，导致数据分析时完全无法还原现场。

下面的代码可以直观看到默认行为：

import pandas as pd
import logging

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

df = pd.DataFrame({
    "user_id": [1001, 1002, 1003, 1004, 1005],
    "score": [89.5, 92.0, 78.3, 85.1, 90.0],
    "city": ["Shanghai", "Beijing", "Guangzhou", "Shenzhen", "Hangzhou"],
})

logging.info(df)

当日志输出被重定向到文件时，列可能会被压缩成类似 city ... 的形式，行数较多时还会出现中间行省略号。这不是程序错误，而是显示选项在起作用。要解决这个问题，需要主动指定输出格式，而不是依赖DataFrame的默认字符串表示。

二、基础方案：用to_string控制输出并交给logging

直接使用df.to_string()可以绕开部分显示选项，生成完整表格。注意不要写logging.info(df.to_string())这样提前格式化，而应该使用logging.info("%s", df.to_string())，让logging在真正需要输出时才进行字符串格式化。当日志级别被过滤时，参数化方式可以避免无意义的DataFrame转字符串开销。

to_string()支持多个参数：line_width控制每行最大宽度，max_colwidth控制单元格截断长度，index=False能隐藏索引。例如，宽表可以把单元格内容限制在80个字符，避免日志单行过长：

import logging

logging.info(
    "DataFrame preview:\n%s",
    df.head(20).to_string(index=False, line_width=120, max_colwidth=80),
)

对于超宽表，不要把整个DataFrame完整展开，可以组合使用df.head(20).to_string()以及列名列表。列名本身也需要单独记录，否则只看表格可能无法知道哪些字段被截断。下面是一个更稳妥的写法：

logging.info("DataFrame shape: %s, columns: %s", df.shape, list(df.columns))
logging.info("Sample rows:\n%s", df.head(5).to_string(index=False))

需要留意的是，pd.set_option("display.max_columns", None)这类全局设置虽然也能让df的默认输出变完整，但它会影响整个进程中的其他pandas输出，包括终端展示和第三方库的打印。所以更推荐在使用日志的地方通过to_string()参数做局部控制，避免副作用扩散。

三、引入tabulate获得更紧凑的日志表格

pandas原生的to_string()生成的表格比较宽，列与列之间用空格对齐，在日志文件中会占用大量横向空间。如果希望日志里的表格更紧凑，可以引入tabulate库。安装方式很简单：pip install tabulate。它可以把DataFrame转换成多种纯文本表格格式，例如PostgreSQL风格的psql、网格风格的grid、简单分隔的simple等。

下面的代码使用tabulate输出适合日志的紧凑表格：

from tabulate import tabulate
import logging

table = tabulate(df, headers="keys", tablefmt="psql", showindex=False)
logging.info("DataFrame table:\n%s", table)

不同格式适合不同场景。psql在纯文本日志中边界清晰，而且字符数较少；grid更接近Excel风格，但横线和竖线更多；simple只有简单的横线分隔，适合日志内容已经很多的情况。实际使用时可以先把几种格式各输出一次，对比一下单行宽度和可读性。也可以给tabulate()传入floatfmt=".2f"控制浮点位数，或者用missingval="NULL"统一缺失值显示。

不过要清楚，tabulate生成的字符串同样包含换行。如果只是像上面那样传给logging，仍然可能出现后续行顶格的问题。因此，它需要配合下一节的Formatter一起使用，才能真正做到日志格式统一。

四、自定义Formatter解决多行前缀错位

多行DataFrame写入日志后，常见的问题是只有第一行带有时间戳、级别等前缀，后续行紧跟着从左边界开始。排查日志时很难把这几行归到同一条记录。解决思路是自定义logging.Formatter，在输出前对包含换行的消息做缩进处理，让每一行都遵守相同的对齐规则。

下面是一个简单的缩进Formatter实现：

import logging

class IndentFormatter(logging.Formatter):
    def format(self, record):
        message = record.getMessage()
        if "\n" in message:
            lines = message.split("\n")
            indented = "\n".join("    " + line for line in lines[1:])
            record.msg = lines[0] + "\n" + indented
            record.args = None
        return super().format(record)

这个Formatter先检查消息是否包含换行，如果包含，只对第二行及之后的行添加四个空格缩进，第一行保留原来的日志前缀。这样日志记录在视觉上就形成了清晰的层级。配合RotatingFileHandler使用时，也不用担心多行交叉会被拆断，因为单个handler的写入过程是同步的。

除了缩进，还可以在DataFrame字符串前后加上明显的分隔标记，例如----- DataFrame Begin -----和----- DataFrame End -----。这样即使日志被其他工具采集，也能方便地用脚本定位表格内容。需要注意性能：不要在Formatter内部反复调用df.to_string()，应把转换放在调用侧，Formatter只做轻量的字符串处理。

五、生产环境实践：摘要、采样与结构化日志

日志的目的是排障，不是备份数据。对于行数超过阈值的DataFrame，建议只记录shape、columns、dtypes、缺失率和前五行样本。完整打印一个百万行的DataFrame不仅会写满磁盘，还可能让日志采集管道卡住。封装一个摘要函数是更合理的选择：

def log_dataframe_summary(logger, df, max_rows=10):
    logger.info("DataFrame shape: %s", df.shape)
    logger.info("Column types:\n%s", df.dtypes.to_string())
    logger.info("Missing value count:\n%s", df.isna().sum().to_string())
    if len(df) > max_rows:
        logger.info("Sample rows (first %s):\n%s", max_rows, df.head(max_rows).to_string(index=False))
    else:
        logger.info("Full content:\n%s", df.to_string(index=False))

如果要输出JSON结构化日志，可以使用logging的extra字段，配合支持JSON的Formatter，将DataFrame元数据作为独立字段写入。这样日志分析系统可以按字段查询，而不是解析自由文本表格：

logger.info(
    "DataFrame summary",
    extra={
        "df_shape": df.shape,
        "df_columns": list(df.columns),
        "df_missing": int(df.isna().sum().sum()),
    },
)

最后还需要考虑采样策略。对于小表可以全量记录；对于大表只记录结构信息和少量样例；对于需要频繁打印的监控DataFrame，可以把样本行数降到3到5行，并且只在异常分支中输出。这样既能保留必要的上下文，又不会给日志系统带来不必要的负担。

Python日志Pandas DataFramelogging格式化修改时间：2026-09-26 19:54:36