日志系统的设计：从 console.log 到结构化日志
一、console.log 在什么时候不够用
开发阶段,console.log是最直接的调试工具。打印请求参数、输出中间结果,在本地跑一下就知道发生了什么。这个习惯在部署到生产环境后,往往延续下来——生产代码里依然充斥着console.log('用户登录:', userId)。
console.log在生产环境中不够用的原因:
- 日志没有上下文。你不知道这条日志是哪个请求产生的、来自哪个用户、发生在哪个页面上。在多用户并发的服务器上,日志是交错输出的,无法区分哪些日志属于同一个请求。
- 日志无法搜索和聚合。当你的日志每天产生几万行,
console.log的输出只是一串原始文本,无法按「错误类型」「端点名称」「用户 ID」来做聚合统计。 - 日志无序,无法还原请求链路。一个请求可能经过多个中间件、调用了多次 AI API,
console.log无法把这些分散的日志串联起来。
graph TD A[应用代码] --> B[日志输出] B --> C{输出方式} C -->|console.log| D[原始文本<br/>无结构化<br/>无搜索能力<br/>无法聚合] C -->|结构化日志| E[JSON 格式<br/>按字段搜索<br/>按维度聚合<br/>请求链路追踪] D --> F[排查问题:<br/>grep 手动查找<br/>效率低] E --> G[排查问题:<br/>query+过滤器<br/>快速定位] style D fill:#ffcdd2 style E fill:#c8e6c9二、结构化日志的核心要素
结构化日志的本质:将每一条日志从「一段文本」变成「一个包含多个字段的 JSON 对象」。每条日志至少包含以下字段:
timestamp:日志产生的时间(ISO 8601 格式)。level:日志级别(info/warn/error/debug)。message:日志的简要描述(人类可读的摘要)。requestId:请求的唯一标识(用于关联同一请求的所有日志)。userId:当前用户 ID(如果已登录)。endpoint:当前请求的端点或功能名称。duration:操作耗时(如 API 调用耗时)。
graph TD A[请求进入] --> B[生成 requestId] B --> C[中间件: 日志记录<br/>info: 请求开始<br/>method/URL/IP] C --> D[业务逻辑] D --> E[数据库查询<br/>info: 查询耗时/duration] D --> F[AI API 调用<br/>info: Token/延迟/模型] D --> G[文件操作<br/>debug: 文件路径/大小] E --> H[中间件: 日志记录<br/>info: 请求完成<br/>statusCode/duration] F --> H G --> H H --> I[所有日志<br/>共享 requestId] style B fill:#e3f2fd style I fill:#c8e6c9三、日志级别的使用规范
结构化日志中,日志级别不是随意的,需要有明确的规范:
- error:发生了需要立即关注的问题。如 API 调用失败、数据库连接丢失、支付处理异常。error 级别的日志应该触发告警(如邮件、Slack 通知)。
- warn:发生了潜在的问题,但不影响当前功能。如调用重试成功(第一次失败了但重试后成功)、用户输入不合法(被校验拒绝)、缓存即将过期。warn 级日志在定期审查时需要关注。
- info:正常业务流程的关键节点。如用户登录、订单创建、API 调用成功、部署完成。info 级日志用于构建业务流程的可追溯性。
- debug:开发和调试信息(生产环境通常关闭)。如函数的参数和返回值、中间计算结果、缓存命中状态。
console.log最大的问题是所有输出都「同等级别」——无法区分「需要立即处理的错误」和「只是记录一下的正常信息」。使用结构化日志的级别,能在日志量大时快速聚焦到重要信息。
四、日志的存储与查询
结构化日志的存储,对于独立产品,不需要引入 ELK(Elasticsearch + Logstash + Kibana)这样的重型工具。
轻量方案一:文件存储 + 结构化 JSON。最简单的方案,每条日志一行 JSON,写入日志文件。查询时用jq(命令行 JSON 处理器)做过滤和聚合,或导入 SQLite 作进一步分析。
轻量方案二:使用现有的数据库。如果你的产品已经在用 PostgreSQL,可以用它的 JSON 字段存储日志。PostgreSQL 支持对 JSON 字段建索引和查询,可以用 SQL 做日志分析。注意:高频日志写入可能对数据库造成压力,需要控制写入速率。
轻量方案三:使用日志服务。如 Better Stack、Datadog Logs、或国产的日志服务。这些服务按月收费,价格不高,且提供了开箱即用的搜索、过滤和告警功能。
对于独立产品,推荐从方案一(文件 + JSON)开始。随着产品增长,再按需迁移到日志服务。
五、总结
日志系统的设计,核心转变是从「随手打印」到「有意识地记录」。每一条日志,不只是为了「现在调试用」,而是为了「将来排查问题时,能还原当时发生了什么」。
对于独立产品,从结构化的console.log替代品开始——用pino(Node.js)、structlog(Python)、或slog(Go)这类结构化日志库来替代原生的console.log。它们自动为每条日志加上时间戳、级别,并支持以 JSON 格式输出。
最少实践:(1)使用结构化日志库,输出 JSON 格式;(2)每个请求生成唯一的 requestId,传递到所有相关日志中;(3)区分 error/warn/info/debug 级别,为 error 设置告警;(4)日志输出到文件,用jq或 SQLite 在需要时查询分析。
 agent和组件)