SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场logging

logging

部署与运维

查看项目

更新于 10-15 10:20

技能介绍

用途

该技能是一份应用日志记录的综合指南，用于在项目中添加日志、搭建结构化日志、配置日志级别以及进行日志管理。当用户提出“add logging”“set up structured logging”“configure log levels”等需求时适用。内容覆盖结构化日志、日志级别、日志库选型、集中式聚合、安全注意事项，以及跨语言、跨框架的生产级实践模式。

日志级别

指南给出从最轻到最严重的标准日志级别对照：

  • TRACE（值 10）：超细粒度诊断细节，例如进入/退出函数、变量值。
  • DEBUG（值 20）：面向开发者的诊断信息，例如 SQL 查询、缓存查找、解析后的配置。
  • INFO（值 30）：正常运营事件，例如服务器启动、用户登录、任务完成。
  • WARN（值 40）：意外但可恢复的情况，例如使用了已弃用 API、重试尝试、慢查询。
  • ERROR（值 50）：特定操作失败，例如数据库连接失败、API 调用超时。
  • FATAL（值 60）：系统级不可恢复故障，例如内存耗尽、缺少关键配置、状态损坏。

级别选择建议：生产环境设为 INFO（高吞吐服务可设为 WARN）；预发布环境设为 DEBUG 以便在生产前发现问题；开发环境设为 TRACE 以获得最大可见性。此外支持按模块覆盖级别，让特定模块以更细粒度记录而不淹没整体日志；并支持运行时动态调整日志级别而无需重启（例如通过管理 API 或环境变量重载）。

结构化日志（JSON 格式）

指南强调生产环境应始终使用结构化日志，因为纯文本日志难以解析、过滤和聚合。给出的结构化日志条目示例包含字段：timestamp、level、logger、message、service、environment、version、host、correlationId、traceId、spanId、userId、error（含 type、message、stack）、duration_ms、metadata（如 db_host、retry_count）。

结构化日志的价值包括：可机器解析，日志聚合工具可直接索引和查询字段；模式一致，每条日志形状相同，便于可靠告警；上下文丰富，可为每条日志附加任意元数据（用户 ID、请求 ID、租户 ID）；可过滤，可按级别、服务、用户、时间范围或任意字段组合查询日志。

各语言日志库与配置

Node.js

  • Winston：最流行的 Node.js 日志库，基于 transport 架构。示例配置包含 level（默认取环境变量 LOG_LEVEL 或 info）、format 组合（timestamp、errors 带 stack、json）、defaultMeta（service、environment、version），以及多个 transport：错误日志文件（level 为 error，maxsize 10MB，maxFiles 5，tailable）、合并日志文件（maxsize 50MB，maxFiles 10，tailable）；非生产环境额外添加带颜色输出的 Console transport。
  • Pino：最快的 Node.js 日志器，针对生产环境低开销优化。示例配置包含 level、formatters（level、bindings）、ISO 时间戳、redact（对 authorization、cookie、password、ssn、creditCard、token、secret 等路径脱敏为 [REDACTED]）、serializers（err、req、res）。
  • Pino 与 Express 中间件：使用 pino-http，示例包含 autoLogging.ignore（忽略 /health、/ready）、customLogLevel（5xx 或错误为 error，4xx 为 warn，其余为 info）、customSuccessMessage、customErrorMessage、customProps（correlationId 取自 x-correlation-id 头或 req.id）。
  • Bunyan：示例配置包含 name、level、标准 serializers，以及多个 stream：info 输出到 stdout、error 写入 logs/error.log、debug 使用 rotating-file（period 1d，count 7）。

Python

  • 标准库 logging：示例定义 JSONFormatter 类，输出包含 timestamp、level、logger、message、module、function、line 的 JSON；当存在异常信息时附加 exception（type、message、traceback）；并将通过 extra 传入的额外字段合并进日志条目。随后给出 dictConfig 配置，包含 json 与 standard 两种 formatter，console（StreamHandler 输出到 stdout）、file（RotatingFileHandler，maxBytes 10MB，backupCount 5）、error_file（同样轮转，level 为 ERROR）三个 handler，root 级别 INFO。
  • structlog：示例配置 processors 链（merge_contextvars、add_log_level、StackInfoRenderer、set_exc_info、TimeStamper ISO、JSONRenderer），wrapper_class 为 make_filtering_bound_logger(INFO)，使用 PrintLoggerFactory，cache_logger_on_first_use 为 True；演示通过 log.bind 绑定 correlation_id、user_id、service 上下文后记录 info 与 error。
  • Loguru：示例移除默认 handler 后添加三个 sink：stdout（自定义格式，level INFO，serialize 为 JSON）、logs/app.log（rotation 100 MB，retention 30 days，compression gz，serialize，level DEBUG）、logs/error.log（rotation 50 MB，retention 90 days，compression gz，level ERROR，backtrace 与 diagnose 开启）；演示 logger.info 附带 user_id、ip 字段。

Java

  • SLF4J + Logback：logback.xml 示例包含 CONSOLE appender（使用 LogstashEncoder，包含 MDC 键 correlationId、userId，customFields 含 service、environment）与 FILE appender（RollingFileAppender，SizeAndTimeBasedRollingPolicy，fileNamePattern 含日期与索引并 gz 压缩，maxFileSize 100MB，maxHistory 30，totalSizeCap 3GB）；root 级别 INFO；并按包设置级别（com.myapp.repository 为 DEBUG、org.hibernate.SQL 为 DEBUG、org.springframework.web 为 WARN）。Java 用法示例通过 MDC.put 设置 userId 与 correlationId，记录 info 与 debug，异常时 log.error 并抛出，finally 中 MDC.clear。
  • Log4j2：log4j2.xml 示例包含 Console appender（JsonLayout，compact、eventEol、stacktraceAsString，KeyValuePair 含 service、environment）与 RollingFile appender（JsonLayout，SizeBasedTriggeringPolicy 100MB，TimeBasedTriggeringPolicy interval 1 modulate，DefaultRolloverStrategy max 30）；root 级别 info。

Go

  • slog（标准库，Go 1.21+）：示例 setupLogger 使用 HandlerOptions（Level 为 Info，AddSource 为 true，ReplaceAttr 对 password、token、secret 脱敏为 [REDACTED]），使用 NewJSONHandler 输出到 stdout；演示 slog.Info 以及 InfoContext 配合 slog.Group 记录 request（method、path、correlationId）与 user（id）。
  • Zap（Uber）：示例 NewLogger 使用 zap.Config，Level 为 InfoLevel，Encoding 为 json，EncoderConfig 指定 timestamp、level、logger、caller、message、stacktrace 等键及编码器，OutputPaths 为 stdout 与 logs/app.log，ErrorOutputPaths 为 stderr，InitialFields 含 service；演示 logger.Info 附带 method、path、latency、status 字段。
  • Zerolog：示例 init 设置 TimeFieldFormat 为 RFC3339Nano、全局级别 InfoLevel，log.Logger 使用 zerolog.New(os.Stdout) 并附加 Timestamp、service、version、Caller；演示 log.Info 链式附加 method、path、latency、status 后输出消息。

适用场景

适用于需要在 Node.js、Python、Java、Go 等语言项目中引入或改进日志记录、统一结构化日志格式、按环境配置日志级别、为请求链路附加关联 ID 与追踪 ID、对敏感字段脱敏，以及配置日志文件轮转与保留策略的工程场景。

限制

资料未提供集中式日志聚合的具体工具配置、日志采样策略、日志成本控制、日志保留合规要求等细节；也未提供各日志库的安装命令、版本兼容性说明与性能基准数据。上述内容暂未提供。