SpringOpen
搜索 K

外观

Logging Starter ​

受众：开发者 摘要：HTTP 请求日志、TraceId、敏感字段脱敏、慢请求标记。后台可查询的业务运维日志（操作 / 登录 / 调度 / 通知 / 支付 / 开放平台等）由 IAM、Audit、Runtime、Scheduler 等核心模块负责。

何时使用 ​

场景建议
HTTP 请求链路记录（method / path / status / 耗时 / IP）默认启用 spring.open.logging.request.enabled，生产默认只输出异常、5xx 和慢请求
异常 / 5xx 错误追踪请求日志自动升级为 warn + 异常类型
链路追踪 / 跨服务 traceIdTraceIdContext.getOrCreate()
慢请求标记slow-threshold: 2s 配置阈值
后台可查询的业务日志（登录 / 操作 / 调度 / 通知等）用 spring-open-core-iam、spring-open-core-audit、spring-open-core-runtime 等底座运维入口
健康检查 / 应用信息 / 指标用 observability.md
OpenTelemetry / Prometheus / SkyWalking不在第一阶段范围

请求日志只记录元数据，不记录 request body，避免把密码、验证码、Token、私钥写入运行日志。

快速开始 ​

完整版聚合 starter 已包含 logging，无需额外配置即可获得生产友好的默认请求日志：普通 2xx 请求不刷屏，异常、5xx 和慢请求会输出；本地排查需要全量链路时，把 spring.open.logging.request.mode 改成 all。

bash
# 启动应用后请求任意 API
curl http://localhost:8000/api/v1/site

# 查看运行日志
tail -f storage/runtime/logs/app.log

控制台和文件日志的时间前缀默认使用 yyyy-MM-dd HH:mm:ss.SSS，比 Spring Boot 原生的 ISO 时间更适合本地开发阅读；需要对接日志平台时可通过 LOG_DATEFORMAT_PATTERN 覆盖。

按需引入：

xml
<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-logging</artifactId>
</dependency>

请求日志格式 ​

输出半结构化请求摘要：状态码、方法、路径、耗时和结果标签前置，traceId 及排障字段保留 key-value：

text
http_request 200 GET /api/v1/admin/iam/users 18ms OK traceId=... | query=page=1 clientIp=127.0.0.1 userAgent=Mozilla/5.0 failure=-

默认 error-and-slow 模式只记录异常、status ≥ 500 和慢请求；这些请求会使用 warn 级别并在行首显示 ERROR 或 SLOW：

text
http_request 500 GET /api/v1/admin/iam/users 12ms ERROR traceId=... | query=- clientIp=127.0.0.1 userAgent=- failure=IllegalStateException

只记录异常类型，不记录 message 和 body。

敏感参数脱敏 ​

text
/api/v1/auth/login?username=admin&password=******

默认脱敏参数：password / token / secret / api_key / authorization / credential / private_key / signature / captcha / code

配置项 ​

yaml
spring:
  open:
    logging:
      enabled: true
      request:
        enabled: true
        mode: error-and-slow
        logger-name: com.springopen.starter.logging.request
        include-query-string: true
        include-client-ip: true
        include-user-agent: true
        slow-threshold: 2s
        max-query-length: 512
        ignored-paths:
          - /favicon.ico
          - /admin/**
          - /app/**
          - /docs/**
          - /images/**
          - /webjars/**
          - /spring-open/view/**
        sensitive-query-parameters:
          - password
          - token
          - secret
          - api_key
配置默认值说明
enabledtrue启用开关
request.enabledtrueHTTP 请求日志开关
request.modeerror-and-slow请求日志输出模式：error-and-slow 只记录异常 / 5xx / 慢请求；all 记录所有未忽略请求；off 不输出请求日志
request.logger-namecom.springopen.starter.logging.request请求日志 logger 名（用于 logback 配置）
request.include-query-stringtrue是否记录脱敏后的 query string
request.include-client-iptrue是否记录客户端 IP
request.include-user-agenttrue是否记录 User-Agent
request.slow-threshold2s超过阈值输出 SLOW 标签
request.max-query-length512脱敏后 query 最大长度（非正数 = 不截断）
request.ignored-paths见示例不记录请求日志的路径 glob
request.sensitive-query-parameters见示例需要脱敏的 query 参数名

Provider ​

不提供 Provider 切换。扩展能力：

  • 自定义 logback / log4j2 配置接管日志格式和输出目标
  • 本地开发或 E2E 巡检需要全量链路时设置 spring.open.logging.request.mode=all
  • 通过 ignored-paths / sensitive-query-parameters 调整脱敏规则

源码机制骨架 ​

类职责
LoggingAutoConfiguration绑定 spring.open.logging.* 配置，并在 Servlet Web 应用中注册 query 脱敏器和请求日志过滤器
LoggingProperties定义请求日志开关、logger 名、query / IP / User-Agent 输出开关、慢请求阈值、忽略路径和敏感 query 参数
LoggingQueryMasker在写日志前按参数名脱敏 query string，并按最大长度截断
RequestLoggingFilter围绕 Servlet 请求记录 method、path、status、耗时、慢请求、IP、User-Agent、traceId 和失败类型
LoggingConstants维护请求日志 logger 名和脱敏占位值

运行流程：

  1. 应用启动时，LoggingAutoConfiguration 根据 spring.open.logging.enabled 和 spring.open.logging.request.enabled 决定是否装配。
  2. RequestLoggingFilter 先判断 ignored-paths，静态资源、后台视图资源和文档资源默认不进入请求日志。
  3. 请求进入业务链路前，过滤器检查当前线程是否已有 TraceIdContext；没有时从 X-Trace-Id 读取或生成临时 traceId。
  4. 业务链路执行结束后，过滤器输出请求摘要日志；行首固定为 http_request <status> <method> <path> <duration> <OK|SLOW|ERROR> traceId=...，异常或 status >= 500 使用 warn，其他请求使用 info。
  5. query string 只经过 LoggingQueryMasker 脱敏和截断，不做 URL 解码重编码，避免日志内容和原始请求不一致。
  6. 如果 traceId 是 Logging 临时创建的，请求结束后会恢复进入过滤器前的 TraceIdContext 和 MDC。

扩展边界 ​

  • Logging starter 只承载运行时请求日志，不承担业务操作日志、登录日志、调度执行日志、队列失败日志、支付回调日志或开放平台调用日志。
  • 请求日志只记录元数据，不记录 request body、response body、异常 message、完整手机号、完整邮箱或任何密钥类内容。
  • 需要新增日志字段时，第一阶段优先通过应用自定义 logback / log4j2、代理层日志或业务模块审计日志承载；Logging starter 暂不提供字段 Contributor SPI。
  • 需要采样、指标、链路追踪或日志采集时，优先接入 observability / OpenTelemetry / Loki / ELK 等观测链路，不在本 starter 内堆叠。

TraceId ​

Web MVC starter 默认启用 TraceId 过滤器。

请求头：

http
X-Trace-Id: your-trace-id

Web MVC 入口也兼容读取 X-Request-Id / X-Request-ID。框架标准响应头仍是 X-Trace-Id，外部 传入的值会经过长度和字符白名单校验，非法值会被丢弃并重新生成。

如果请求没有传入 TraceId，框架自动生成并写入：

  • 响应 Header X-Trace-Id
  • Result.traceId
  • SLF4J MDC（logback 模板可读）

业务代码读取：

java
String traceId = TraceIdContext.getOrCreate();

如果应用只引入 spring-open-starter-logging 而没有 Web MVC starter，Logging starter 在请求日志中兜底生成 traceId，请求结束后清理。

跨边界透传：

  • Web MVC 会为应用上下文中的 RestTemplate 自动追加当前线程 TraceId，且不覆盖调用方已显式设置的请求头。
  • Queue dispatcher 会在 handler 执行期间绑定消息 traceId 到 TraceIdContext 和 MDC，并在结束后恢复进入 dispatcher 前的上下文。
  • Event starter 的 publishAsync 会把提交任务时的 TraceIdContext 带到异步发布线程；为保持 starter 轻量，不额外引入 MDC 编译依赖。
  • Outbox 事件和补偿命令入队会优先使用显式 traceId，其次使用当前上下文，仍为空时生成安全 traceId，便于 Webhook 投递、重试和后台运维串联排查。

模块边界 ​

能力所属模块说明
请求运行日志spring-open-starter-logging本文档
TraceIdspring-open-starter-webmvc写入响应 Header / Result / MDC
操作日志spring-open-core-audit后台写操作审计
登录日志spring-open-core-iam登录成功 / 失败 / 退出 / token 操作
配置变更日志spring-open-core-config数据库配置新增 / 修改 / 启停 / 删除
调度执行日志spring-open-core-schedulerScheduler 任务执行 / 失败 / 重试
队列失败日志spring-open-core-queueQueue database provider 失败任务
通知发送日志spring-open-core-notificationNotification 发送结果和失败重试
支付回调日志spring-open-core-cashier支付异步通知 / 验签 / 原始事件
开放平台调用日志spring-open-module-open-platform开放 API 应用 / scope / 结果 / 耗时
Web3 扫描日志spring-open-core-web3链上事件扫描执行结果

文件位置 ​

默认运行日志目录：

text
storage/runtime/logs/

storage/runtime/ 与 storage/runtime/logs/ 不进入 Git。生产环境可接入外部日志平台（Loki / ELK / Splunk）。

后台运维日志入口 ​

对应模块提供后台运维日志入口：

日志API
操作日志/api/v1/admin/audit/operation-logs
登录日志/api/v1/iam/auth/audit/login-logs
配置变更日志/api/v1/config/change-logs
调度执行日志/api/v1/admin/scheduler/execution-logs
队列失败日志/api/v1/admin/queue/failed-jobs
通知发送日志/api/v1/notification-send-logs
支付回调日志/api/v1/admin/cashier/payment-callback-logs
开放平台调用日志/api/v1/admin/open-platform/call-logs
Web3 扫描日志/api/v1/admin/web3/scan-logs

核心原则 ​

  • 所有请求都有 traceId
  • 请求日志只记录元数据，不记录 request body
  • 日志中不输出密码、验证码、Token、私钥、密钥、证书、完整手机号、完整邮箱
  • 后台可查询的日志优先落数据库；普通运行日志走 SLF4J / Logback 文件输出
  • 日志保留、清理和重试由对应模块自己的运维入口处理

后续扩展 ​

  • 请求日志采样
  • 响应结果摘要
  • OpenTelemetry trace / metrics / logs
  • Micrometer + Prometheus
  • Loki / ELK 日志采集
  • SkyWalking / Zipkin 链路追踪

验证命令 ​

bash
./mvnw -pl spring-open-starters/spring-open-starter-logging -am test -DskipITs

相关 ​

Released under the Apache License 2.0.

Copyright © SpringOpen