AWS ECS部署的NestJS应用CloudWatch日志拆分异常如何排查解决

核心根因逻辑 #

CloudWatch日志（不管是awslogs驱动还是FireLens透传）默认按换行符\n切分单条日志，只要应用输出的单条日志里被插入了额外换行、或者输出缓冲被切碎，就会出现完整JSON被拆成多条独立日志的问题，按以下优先级排查即可：

1. 优先排查NestJS应用侧日志配置（90%的问题出在这） #

• 立刻检查生产环境日志是否开启了pretty print格式化：Nest默认Logger、Pino、Winston等常用日志库的pretty模式为了本地可读性，会把结构化JSON拆成带换行、颜色标记的多行文本，直接输出到stdout就会被CloudWatch按换行切分。
  生产环境必须关闭pretty输出，强制输出单行JSON：
  • 用Nest默认Logger：生产初始化时关闭pretty选项
  • 用Pino：生产环境移除pino-pretty transport配置，仅本地开发时启用
  • 用Winston：生产环境不要用带换行格式化的Console transport，直接输出原始JSON
• 检查异常日志打印逻辑：不要直接裸打带原生换行的错误栈console.log(error.stack)，要把错误栈作为字符串字段塞进JSON结构里输出，避免裸换行混入日志流。
• 本地先做验证：执行生产构建后运行NODE_ENV=production node dist/main.js > log_test.txt 2>&1，查看生成的log_test.txt，确认每一行都是一个完整可JSON.parse的对象，没有单条JSON拆成多行的情况，本地验证通过再推镜像部署。

2. 排查ECS任务日志驱动配置 #

• 如果用默认awslogs驱动：该驱动本身不支持多行日志合并规则，只要碰到换行就切分新日志。如果业务必须输出带换行的内容（比如固定要打印原生格式错误栈），要么在应用侧把所有换行替换为转义符\\n再输出，要么替换为FireLens日志驱动做多行合并。
• 如果用FireLens（Fluent Bit）驱动：检查是否缺少多行解析规则，需要在Fluent Bit配置里添加JSON多行匹配规则，确保仅当碰到{开头、}结尾的完整块时才识别为单条日志，参考配置：

[MULTILINE_PARSER]
    name          nest_json_log
    type          regex
    rule          "start_state"      /(^\{)/  "cont"
    rule          "cont"             /(^\})/  "start_state"

配置后把日志输入的parser绑定该多行解析器即可。

3. 排查运行时缓冲与进程层配置 #

• 检查任务定义是否开启了容器TTY：ECS容器默认是非TTY环境，如果任务定义里把terminal: true（旧版控制台叫tty开启）打开，会导致Node.js stdout的缓冲逻辑异常，日志会按固定块大小flush而非按整行输出，直接导致日志被切碎，关闭该配置即可。
• 给Node启动参数加--unbuffered，启动命令改为node --unbuffered dist/main.js，强制关闭stdout/stderr缓冲，日志生成后立刻输出，避免缓冲切碎日志。
• 如果用PM2、supervisor这类进程管理器托管Nest进程：检查进程管理器的日志配置，关闭自带的日志格式化、日志自动切分功能，确保应用原始日志直接透传到stdout，不要被进程管理器额外插入换行或拆分。

内容的提问来源于stack exchange，提问作者Renato Souza