Skip to content

Commit 2786a02

Browse files
committed
docs(log): 重构日志文档结构并优化内容表述
移除章节编号,简化标题层级,统一术语表述,提升文档可读性。 调整内容组织结构,增强逻辑连贯性,完善日志系统的设计理念阐述。
1 parent 3f1a44e commit 2786a02

1 file changed

Lines changed: 24 additions & 42 deletions

File tree

  • doc/软件工程/架构/系统设计

doc/软件工程/架构/系统设计/日志.md

Lines changed: 24 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,45 +4,39 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
44

55
# 日志
66

7-
> 面向长期演进的软件系统,将日志从"调试手段"升级为"系统认知与组织治理工具"。
7+
## 原理层
88

9-
---
10-
11-
## 一、原理层(First Principles)
9+
### 日志的本质
1210

13-
### 1. 日志的本质
14-
15-
**日志不是文本,而是事件(Event)的时间化持久表达。**
11+
**日志是事件(Event)的时间化持久表达。**
1612

1713
> 日志 = 系统在时间维度上,对**状态变化、决策行为与异常事实**的不可变记录。
1814
19-
其核心价值不在于“打印了什么字符串”,而在于
15+
其核心在于
2016

2117
* 事实留存(What happened)
2218
* 上下文还原(Who / When / Where / Why)
2319
* 因果追溯(Before / After / Impact)
2420

25-
### 2. 日志在可观测性中的位置
21+
### 日志在可观测性中的位置
2622

2723
可观测性的三大支柱:
2824

2925
* **Logs(事件)**:离散、不可逆、语义最强
3026
* **Metrics(度量)**:聚合、趋势、宏观健康度
3127
* **Traces(链路)**:因果路径、调用拓扑
3228

33-
> 日志解决的是“发生了什么”,而不是“发生得多快”
29+
> 日志解决的是“发生了什么”。
3430
35-
### 3. 稳定认知
31+
### 稳定认知
3632

3733
* 日志是**事件事实源**,不是临时调试输出
3834
* 日志一经写入,应被视为**不可修改的历史**
3935
* 日志的价值随时间衰减,但不会归零
4036

41-
---
42-
43-
## 二、架构层(Architecture Model)
37+
## 架构层
4438

45-
### 1. 日志系统的参考抽象模型
39+
### 日志系统的参考抽象模型
4640

4741
```
4842
事件源(应用)
@@ -60,7 +54,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
6054

6155
该模型在单体与分布式系统中保持稳定,仅实现方式不同。
6256

63-
### 2. 单体日志架构
57+
### 单体日志架构
6458

6559
特征:
6660

@@ -73,7 +67,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
7367
* 早期系统
7468
* 低并发内部系统
7569

76-
### 3. 分布式日志架构
70+
### 分布式日志架构
7771

7872
核心思想:**日志写入与业务执行解耦**
7973

@@ -84,11 +78,9 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
8478
* 结构化处理
8579
* 冷热数据分层
8680

87-
---
88-
89-
## 三、设计层(Design Philosophy)
81+
## 设计层
9082

91-
### 1. 日志级别的治理语义(而非技术语义)
83+
### 日志级别的治理语义
9284

9385
| 级别 | 本质含义 | 组织责任 |
9486
| ----- | ------------- | ------- |
@@ -100,7 +92,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
10092

10193
> 日志级别 = 组织对事件严重性的态度声明。
10294
103-
### 2. 系统日志 vs 操作日志(责任边界)
95+
### 系统日志 vs 操作日志
10496

10597
| 类型 | 本质 | 受众 |
10698
| ---- | ------- | ------------ |
@@ -113,7 +105,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
113105
* 业务语义完整
114106
* 可追责性
115107

116-
### 3. 日志上下文设计
108+
### 日志上下文设计
117109

118110
稳定上下文字段:
119111

@@ -124,11 +116,9 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
124116

125117
> 没有上下文的日志,几乎不可用。
126118
127-
---
119+
## 工程方法层
128120

129-
## 四、工程方法层(Engineering Practices)
130-
131-
### 1. 日志与业务解耦
121+
### 日志与业务解耦
132122

133123
* 使用 AOP / 注解
134124
* 使用模板与表达式
@@ -138,7 +128,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
138128

139129
> 日志是对业务事实的“旁观式记录”,而非业务流程的一部分。
140130
141-
### 2. 性能与成本意识
131+
### 性能与成本意识
142132

143133
核心原则:
144134

@@ -151,7 +141,7 @@ tags: ['运维', '性能', '架构设计', '计算机系统']
151141
* 避免大对象与大文本
152142
* 高频场景使用采样
153143

154-
### 3. 错误日志的严格使用
144+
### 错误日志的严格使用
155145

156146
ERROR 日志必须满足:
157147

@@ -161,11 +151,9 @@ ERROR 日志必须满足:
161151

162152
否则应使用 WARN 或 INFO。
163153

164-
---
165-
166-
## 五、选型原则层(Technology-Neutral)
154+
## 选型原则层
167155

168-
### 1. 日志系统选型维度
156+
### 日志系统选型维度
169157

170158
| 维度 | 关注点 |
171159
| ---- | ------------ |
@@ -175,26 +163,20 @@ ERROR 日志必须满足:
175163
| 成本 | 存储 / 计算 |
176164
| 治理能力 | 权限 / 审计 / 合规 |
177165

178-
> 技术会变化,选型原则应长期稳定。
166+
## 组织与文化层
179167

180-
---
181-
182-
## 六、组织与文化层(Organizational Impact)
183-
184-
### 1. 日志的三类受众
168+
### 日志的三类受众
185169

186170
* 开发:诊断与改进
187171
* 运维:稳定性与响应
188172
* 业务/审计:事实与责任
189173

190-
### 2. 日志即制度
174+
### 日志即制度
191175

192176
* 日志定义了什么是“异常”
193177
* 日志决定了谁需要被通知
194178
* 日志影响团队对系统的认知方式
195179

196-
> 一个成熟团队,其日志风格往往高度一致。
197-
198180
## 关联内容(自动生成)
199181

200182
- [/软件工程/架构/系统设计/可观测性.md](/软件工程/架构/系统设计/可观测性.md) 日志作为可观测性三支柱之一,与指标(metrics)和链路追踪(tracing)共同构成完整的系统可观测性体系,理解日志在整体可观测性架构中的位置和作用

0 commit comments

Comments
 (0)