日志系统的设计：从 console.log 到结构化日志

日志系统的设计从 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 在需要时查询分析。