{"name":"日志","id":"软件工程-架构-系统设计-日志","content":"# 日志\n\n## 原理层\n\n### 日志的本质\n\n**日志是事件（Event）的时间化持久表达。**\n\n> 日志 = 系统在时间维度上，对**状态变化、决策行为与异常事实**的不可变记录。\n\n其核心在于：\n\n* 事实留存（What happened）\n* 上下文还原（Who / When / Where / Why）\n* 因果追溯（Before / After / Impact）\n\n### 日志在可观测性中的位置\n\n可观测性的三大支柱：\n\n* **Logs（事件）**：离散、不可逆、语义最强\n* **Metrics（度量）**：聚合、趋势、宏观健康度\n* **Traces（链路）**：因果路径、调用拓扑\n\n> 日志解决的是“发生了什么”。\n\n### 稳定认知\n\n* 日志是**事件事实源**，不是临时调试输出\n* 日志一经写入，应被视为**不可修改的历史**\n* 日志的价值随时间衰减，但不会归零\n\n## 架构层\n\n### 日志系统的参考抽象模型\n\n```\n事件源（应用）\n   ↓\n事件记录（Logger）\n   ↓\n采集与缓冲（Agent / MQ）\n   ↓\n加工与结构化（Processor）\n   ↓\n存储（冷热分层）\n   ↓\n查询与分析（Search / Analytics）\n```\n\n该模型在单体与分布式系统中保持稳定，仅实现方式不同。\n\n### 单体日志架构\n\n特征：\n\n* 同进程写入\n* 文件或本地存储\n* 人工或简单工具分析\n\n适用阶段：\n\n* 早期系统\n* 低并发内部系统\n\n### 分布式日志架构\n\n核心思想：**日志写入与业务执行解耦**\n\n关键能力：\n\n* 异步采集\n* 流量削峰（缓冲层）\n* 结构化处理\n* 冷热数据分层\n\n## 设计层\n\n### 日志级别的治理语义\n\n| 级别    | 本质含义          | 组织责任    |\n| ----- | ------------- | ------- |\n| ERROR | 系统或业务进入不可接受状态 | 必须人工介入  |\n| WARN  | 偏离设计预期但可继续运行  | 需要评估    |\n| INFO  | 关键状态或行为记录     | 用于审计与回溯 |\n| DEBUG | 诊断辅助信息        | 临时存在    |\n| TRACE | 细粒度运行细节       | 高成本、短期  |\n\n> 日志级别 = 组织对事件严重性的态度声明。\n\n### 系统日志 vs 操作日志\n\n| 类型   | 本质      | 受众           |\n| ---- | ------- | ------------ |\n| 系统日志 | 系统行为与异常 | 开发 / 运维      |\n| 操作日志 | 用户或业务行为 | 产品 / 审计 / 风控 |\n\n操作日志必须满足：\n\n* 可读性\n* 业务语义完整\n* 可追责性\n\n### 日志上下文设计\n\n稳定上下文字段：\n\n* 时间（发生 / 记录）\n* 身份（用户 / 系统）\n* 关联（TraceId / BizId）\n* 来源（服务 / 模块）\n\n> 没有上下文的日志，几乎不可用。\n\n## 工程方法层\n\n### 日志与业务解耦\n\n* 使用 AOP / 注解\n* 使用模板与表达式\n* 日志逻辑不侵入业务逻辑\n\n目标：\n\n> 日志是对业务事实的“旁观式记录”，而非业务流程的一部分。\n\n### 性能与成本意识\n\n核心原则：\n\n* 日志不是免费的\n* IO、序列化、存储都需要成本\n\n工程策略：\n\n* 占位符而非字符串拼接\n* 避免大对象与大文本\n* 高频场景使用采样\n\n### 错误日志的严格使用\n\nERROR 日志必须满足：\n\n* 影响业务或系统正确性\n* 需要人工处理\n* 能触发告警或工单\n\n否则应使用 WARN 或 INFO。\n\n## 选型原则层\n\n### 日志系统选型维度\n\n| 维度   | 关注点          |\n| ---- | ------------ |\n| 写入模型 | 吞吐 / 顺序写     |\n| 查询模型 | 实时 / 离线      |\n| 生命周期 | 冷热分层 / 保留策略  |\n| 成本   | 存储 / 计算      |\n| 治理能力 | 权限 / 审计 / 合规 |\n\n## 组织与文化层\n\n### 日志的三类受众\n\n* 开发：诊断与改进\n* 运维：稳定性与响应\n* 业务/审计：事实与责任\n\n### 日志即制度\n\n* 日志定义了什么是“异常”\n* 日志决定了谁需要被通知\n* 日志影响团队对系统的认知方式\n\n## 关联内容（自动生成）\n\n- [/软件工程/架构/系统设计/可观测性.md](/软件工程/架构/系统设计/可观测性.md) 日志作为可观测性三支柱之一，与指标(metrics)和链路追踪(tracing)共同构成完整的系统可观测性体系，理解日志在整体可观测性架构中的位置和作用\n- [/软件工程/架构/系统设计/监控系统设计.md](/软件工程/架构/系统设计/监控系统设计.md) 监控系统设计涵盖了从数据收集到告警治理的完整体系，日志是监控系统的重要数据源，了解监控系统的架构和设计原则对构建有效的日志体系至关重要\n- [/运维/SRE.md](/运维/SRE.md) SRE体系强调通过工程化手段管理系统的稳定性，日志在故障发现、认知和恢复过程中起关键作用，是SLI/SLO实现和错误预算管理的重要数据基础\n- [/软件工程/架构/系统设计/前端监控.md](/软件工程/架构/系统设计/前端监控.md) 前端监控涵盖了客户端的性能指标、异常收集等，与后端日志体系共同构成端到端的可观测性，有助于全链路问题排查\n","metadata":"tags: ['运维', '性能', '架构设计', '计算机系统']","hasMoreCommit":false,"totalCommits":9,"commitList":[{"date":"2026-10-22T22:01:43+08:00","author":"0xcaffebabe","message":"fix: persist hidden preview state across reloads","hash":"377c1b3e0d4a64ac559123da8dfd70920a85224c"},{"date":"2026-10-22T17:14:19+08:00","author":"Codex","message":"fix: restore pinned document previews after refresh","hash":"267bd582422c704067b4b904be948bc04367ad0b"},{"date":"2026-10-22T15:09:08+08:00","author":"Codex","message":"fix: prevent word cloud tooltips leaking into document pages","hash":"60b0fadab47a1aad1ed637dc0c10990b668b5fda"},{"date":"2026-10-22T14:05:48+08:00","author":"My","message":"Merge pull request #637 from 0xcaffebabe/codex/ultrawide-panel-gap-636","hash":"adbac4bad6689e7f56d350f75704a500eed4ac61"},{"date":"2026-10-22T12:19:31+08:00","author":"Codex","message":"fix: remove duplicate mobile bottom-bar search","hash":"afd1e0fab2df539c3e7572878ae8d1e095b09a71"},{"date":"2026-10-22T10:16:53+08:00","author":"My","message":"Merge pull request #639 from 0xcaffebabe/codex/merge-toolbox-sitenav-638","hash":"cb23b5902093c28879a7dc0ba79747f0b38faf02"},{"date":"2026-10-22T01:20:43Z","author":"renovate[bot]","message":"chore(deps): update dependency jsdom to v30","hash":"e364e185b9e8f10adcdb98370342f808d4c5a2fd"},{"date":"2026-10-21T18:58:02+08:00","author":"My","message":"test: distinguish node labels from cluster titles","hash":"4068d9aed488792cf0fa5eb5e175ed7dc27e3f79"},{"date":"2026-10-21T18:07:48+08:00","author":"My","message":"Merge pull request #635 from 0xcaffebabe/codex/contributing-no-images","hash":"49153a716ef494bb51a2d73f54a96f65ad0fe9d5"}],"createTime":"2026-10-21T18:07:48+08:00"}