shoulder-specs-doc/src/main/asciidoc/specs/base/log.asciidoc

// tag::main[]

## 术语定义：
- 日志
    - 运行日志/系统日志
        - 开发人员为了方便定位错误而打的日志，该部分较为自由
    - 追踪日志/调用链日志
        - 分布式系统中为了追踪某个调用链流程相关的日志，该部分一般遵循一定的规范如 link:https://opentracing.io/docs/overview/[OpenTracing]。
    - 特殊日志
        - 面向某特定领域，具有统一格式约束的日志，以在特定场景实现某一功能的日志。如操作日志/业务日志、审计日志；比如：操作日志统一使用json格式，并且要求特定字段。
- 级别
    - 用于日志分类：描述日志重要程度、统一处理某一级别的日志（如控制输出路径、文件名、保存时间、是否输出等）。
- 日志服务
    - 拥有处理日志的能力的软件系统，通常具有采集、存储、检索、日志的能力，典型如 `ELK`

## 规范约束

### 日志文件规范

#### 日志文件输出目录
- 每种程序日志必须统一路径，通常以软件标识命名目录，如 `order` 服务的所有日志输出到 `xxx/order` 文件夹下
- 一个的软件系统下的不同程序统一输出到特定目录，如 `/logs/shoulder/`

#### 日志文件存留时间、切分、压缩
- 该部分按照软件定义和日志级别来确定，如每天的日志压缩一次，最多保留十天或总大小最大允许200M。

#### 日志文件命名
- 按照日志级别区分，如包含 debug、error、other、dts 日志文件
    - debug 包含 debug 级别及以上的日志
    - error 包含 error 级别及以上的日志
    - other 非本软件代码打印的日志
    - dts 分布式链路追踪日志，而非单指 trace 级别
- 当前日志文件命名
    - `软件标识.日志级别.log`，如 `xxx.debug.20200101.log`
- 压缩日志文件命名（历史日志文件）
    - `软件标识.日志级别.日期.log`，如 `xxx.debug.20200101.log.zip`

### 通用日志输出格式规范

为了便于日志服务统一分析，单条日志格式需要统一，如：
```text
日志时间SP日志级别SP程序标识SP[代码位置]SP[线程标识]SP<调用链标识>SP[错误码]SP-SP日志输出正文
```
注意事项
- SP
    表示一个空格。
- []、<>
    表示内容可选，并且需要输出到对应括号内，如果没有则使用字符`-`代替之。

- 基本值特殊字符约束
    - 除了开发者在代码中写的`日志输出`不允许有 空格、`[`、`]`、`<`、`>`

- 日志时间
    日志产生的时间，格式为“年-月-日T时:分:秒.毫秒时区”或“年-月-日SP时:分:秒.毫秒”。
    - 示例
        - 带时区 `2020-01-01T00:00:00.000+08:00`、`2020-01-01T00:00:00.000Z`。
        - 不带时区 `2020-01-01 00:00:00.000`。
- 日志级别
    - 包含 6 个级别（`TRACE - DEBUG - INFO - WARN - ERROR - FATAL`）
    - ~~统一按5个字符长度输出，以保持一致~~

- 程序标识
    - 输出日志的代码所属程序标识，可为模块名称也可为服务名，目的便于区分哪里产生的，与类名、方法名组合定位到具体代码。
    - 示例
        - `spring-aop`、`spring-boot-redis`、`shoulder-core`、`shoulder-crypto`

- 代码位置
    - 打印日志的代码位置，具体可为代码文件路径，类路径、方法名、代码行号等。

- 线程标识
    - 由于获取堆栈信息较耗费性能，一般不打印该值，使用 `-` 来代替，但有时为了方便追踪，需要加上该内容，一般为线程名称/ID。

- 调用链标识
    - 即 `traceId` ，用于快速定位一次调用链，没有则使用 `-` 来代替。

- 错误码
    - 记录错误日志时（WARN 级别及以上），需要同时记录错误码，以 `0x` 开头，十六进制格式输出。没有则使用 `-` 来代替。

- SP日志输出正文
    - 开发人员自定义的日志内容，推荐使用英文（优化压缩率、避免乱码、避免歧义）；记录参数时推荐使用`[param1=value1,param2=value2..]其他内容`这种形式。


### 日志级别规范
- 完整调用信息约束
    - 记录 WARN 级别及以上的日志时，需要记录触发端点（接口地址、定时任务标识、消息事件类型）参数、触发用户标识、若存在异常则需要包含调用栈信息，以便排查、复现问题。
- TRACE
    - 一般不记录参数、变量值，仅用于调试、测试期间标记记录程序执行到此，在其他级别日志记录未开发或缺失时来判断程序是否执行至此，程序正常运行时一般不打印该级别日志。
    - 举例：发起远程调用、完成远程调用、收到调用请求、完成调用请求、方法开始前、方法完成后。
- DEBUG
    - 记录出入参数值、关键变量值、接口响应值等。
- INFO
    - 程序自身状态变更、配置参数值变更、意料之中的异常、定时任务、通知变更、API接口被调用、特殊数据的初始化、关键的数据变更等，一般用于调试、测试期间以及复现问题时打印。
- WARN
    - 程序抛异常，导致一次功能失效，但设计了人性化的提示，单次发生不影响再次操作、其他操作、其他用户。
    - 举例：程序启动无法读取到配置文件而使用默认值；调用其他服务接口时失败；程序性能达到上限无法继续处理新的请求；意料之中的特定异常。
- ERROR
    - 程序触发意料之外的异常、状态，导致业务失败，可能导致后续相同功能失败或影响其他功能，程序无法自身解决该类问题，需要产生告警，告知维护人员解决该问题，常常是软件依赖的其他软件或基础设施不正常。
    - 举例：关键业务（功能、定时任务、通知处理）失败；出现程序功能部分不可用（关键配置项缺少、关键中间件连接失败、系统内存、硬盘等上限）。
- FATAL
    - 程序崩溃，接近所有功能不能使用，后续操作无法进行，必须重启或由专人来排查，发生概率极低。
    - 举例：程序所占有资源被其他软件或工具篡改而导致的系统无法按照软件的指令继续执行（检测到非法外挂）、文件损坏无法启动；





// end::main[]


// tag::dts[]
追踪日志描述
// end::dts[]


// tag::op[]

特殊日志

操作日志描述
给使用软件的管理员看的

审计日志
用于数据安全审计，自动化报警等

// end::op[]