如何提高 Debian Node.js 日志质量

提升 Debian 上 Node.js 日志质量的可落地方案

一 核心原则

• 使用结构化日志（优先 JSON），便于检索、聚合与可视化；日志应包含：timestamp、level、pid、msg、trace_id/span_id、req/res 关键字段、错误堆栈 等。
• 合理设置日志级别：trace/debug/info/warn/error/fatal，开发环境可用 debug，生产建议 info/warn，错误单独落盘。
• 多目标输出与异步写入：同时输出到 控制台 与 文件，必要时发送到 远程，并尽量采用异步以减小对主线程影响。
• 日志轮转与保留策略：按 大小/时间 轮转、压缩与清理，避免磁盘被占满。
• 集中式日志与监控告警：接入 ELK/Graylog/Fluentd，用 Kibana/Grafana 分析，结合 Prometheus 做异常告警。

二 推荐技术选型与最小可用配置

• 选型建议：通用首选 Winston（多传输、灵活）；高性能与生态可选 Pino；HTTP 请求日志用 morgan；需要按天/按大小轮转可用 winston-daily-rotate-file 或 pino-rotate。
• Winston 最小可用配置（JSON、按级别分流、开发态控制台美化）：

// npm i winston
const winston = require('winston');

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' })
  ]
});

if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.combine(
      winston.format.colorize(),
      winston.format.simple()
    )
  }));
}

// 使用示例
logger.info({ msg: 'user login', userId: 42 }, 'login success');
logger.error({ err: new Error('boom') }, 'operation failed');

• Express + Morgan（仅记录错误请求示例）：

// npm i morgan
const express = require('express');
const morgan = require('morgan');
const app = express();

app.use(morgan('combined', {
  skip: (req, res) => res.statusCode < 400
}));

• Pino 高性能配置（开发态美化，生产态 JSON）：

// npm i pino pino-pretty
const pino = require('pino');

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport: process.env.NODE_ENV !== 'production'
    ? { target: 'pino-pretty', options: { colorize: true } }
    : undefined
});

• 按天轮转（Winston 示例）：

// npm i winston-daily-rotate-file
const DailyRotateFile = require('winston-daily-rotate-file');

const rotateTransport = new DailyRotateFile({
  filename: 'logs/app-%DATE%.log',
  datePattern: 'YYYY-MM-DD',
  zippedArchive: true,
  maxSize: '20m',
  maxFiles: '14d'
});

• 环境变量控制级别（跨库通用做法）：

LOG_LEVEL=debug node app.js
# 部分库也支持库级变量：WINSTON_LEVEL、PINO_LEVEL

以上做法覆盖库选型、级别控制、结构化输出、异步与轮转等关键要点。

三 系统与运维实践

• 使用 logrotate 管理 Node.js 日志（适用于文件输出场景）：
  1. 安装：sudo apt-get install logrotate
  2. 新建配置：/etc/logrotate.d/myapp

/path/to/your/nodejs/app/logs/*.log {
  daily
  missingok
  rotate 7
  compress
  notifempty
  create 0640 root adm
  sharedscripts
  postrotate
    # 若你的进程支持信号重载，例如使用 SIGUSR1 触发重新打开日志
    if [ -f /var/run/myapp.pid ]; then
      kill -USR1 $(cat /var/run/myapp.pid)
    fi
  endscript
}

• 保留策略建议：本地日志至少保留 24 小时，结合转存可达 7 天；线上精简低级别日志，核心业务日志持久化。
• 性能与可靠性：优先异步写入；关注磁盘空间与日志丢失率，必要时引入远程聚合与持久化。

四 集中式日志与监控告警

• 集中式日志：将日志发送到 ELK Stack（Elasticsearch, Logstash, Kibana） 或 Graylog，便于检索、分析与可视化；也可使用 Fluentd 统一采集。
• 示例（Winston → Elasticsearch）：

// npm i winston-elasticsearch
const { ElasticsearchTransport } = require('winston-elasticsearch');

const esTransport = new ElasticsearchTransport({
  client: new require('@elastic/elasticsearch').Client({ node: 'http://localhost:9200' }),
  index: 'nodejs-logs-%DATE%'
});
logger.add(esTransport);

• 监控与告警：结合 Prometheus + Grafana 对关键错误、延迟、吞吐等指标做可视化与阈值告警，缩短 MTTR。

五 落地检查清单

以上清单覆盖格式、级别、输出、轮转、聚合、告警与可运维性，可直接用于上线前自检与日常巡检。