{"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-03-24T15:32:30+08:00","author":"MY","message":"docs(log): 重构日志文档结构并优化内容表述","hash":"2786a023912229c7d9791c80c7723b65b5a173de"},{"date":"2026-02-12T14:07:03+08:00","author":"MY","message":"doc: 整理标签","hash":"290b3e8ad18f48832ac282290238d020fc030a88"},{"date":"2025-12-23T14:06:29+08:00","author":"MY","message":"docs(log): 重构日志文档，从技术规范升级为系统性架构指导","hash":"1b072aee8caaaeddbdb73ef3d25816eeaf29e17f"},{"date":"2023-09-18T17:03:32+08:00","author":"MY","message":"📦日志","hash":"e78cec26d3d3c8f6c8cfa91a61617966a1a32326"},{"date":"2023-09-18T16:45:47+08:00","author":"MY","message":"📦可观测性","hash":"dc41fbd6c25605121476afab59bd674b5ca59ca2"},{"date":"2022-06-09T21:51:44+08:00","author":"MY","message":"📦整理 Java","hash":"34c01b44e7566fa54773149765e3dd8420235279"},{"date":"2022-01-21T20:36:16+08:00","author":"MY","message":"✏️更新 日志","hash":"a29d316785926ef4faf14ec4827bed54fe9c8927"},{"date":"2022-01-07T11:10:57+08:00","author":"cjiping","message":"✏️更新 日志","hash":"7079edc98d7aaf0e5810e1c56585a5bc66f09007"},{"date":"2020-09-19T11:54:17+08:00","author":"MY","message":"➕增加 Java 日志","hash":"b2a835859602194159bde9e2d88f5642266f58e5"}],"createTime":"2020-09-19T11:54:17+08:00"}