日志基础：级别、结构化与采集架构
日志是可观测性的三大支柱之一，也是故障排查最直接的线索。在生产环境中，日志并非简单的文本输出，而是需要从级别控制、结构化格式和可靠采集三个维度进行工程化设计。本节将围绕这三个核心要素展开，为后续的日志-链路-指标联动修复打下基础。
2.1 日志级别：DEBUG / INFO / WARN / ERROR
日志级别定义了日志的严重程度和用途。合理使用级别可以控制日志输出量，并在故障时快速过滤关键信息。以下是标准级别及其含义：
| 级别 | 用途 | 生产环境建议 | 典型场景 |
|---|---|---|---|
| DEBUG | 开发调试，记录详细执行路径 | 关闭（除非临时排查） | 变量值、函数调用栈、SQL 参数 |
| INFO | 系统正常运行状态 | 开启 | 服务启动、请求完成、定时任务执行 |
| WARN | 潜在问题，不影响当前功能 | 开启 | 磁盘使用率超过阈值、重试次数、降级策略触发 |
| ERROR | 功能异常，需要人工介入 | 开启 | 数据库连接失败、请求超时、业务逻辑异常 |
最佳实践：生产环境默认开启 INFO 及以上级别。DEBUG 日志仅在特定服务或链路追踪中临时开启，并通过动态配置开关控制，避免磁盘写满。
2.2 结构化日志
传统非结构化日志（如 User login failed）难以被机器解析和检索。结构化日志将日志内容组织为键值对或 JSON 格式，使日志成为可查询、可聚合的数据。
结构化日志的核心优势：
- 可解析性：日志分析工具可直接提取字段，无需正则匹配。
- 可查询性：支持按
user_id、request_id、duration_ms等字段快速过滤。 - 可关联性：通过
trace_id字段与链路追踪系统联动。
示例：非结构化 vs 结构化
# 非结构化（难以解析）
2025-03-21 10:00:00 ERROR User 1001 login failed from IP 192.168.1.1
# 结构化 JSON（机器友好）
{
"timestamp": "2025-03-21T10:00:00.000Z",
"level": "ERROR",
"logger": "com.example.AuthService",
"message": "User login failed",
"user_id": 1001,
"source_ip": "192.168.1.1",
"trace_id": "abc-123-def",
"duration_ms": 120
}
关键字段设计：每个结构化日志至少应包含
timestamp（ISO 8601 格式）、level、service、trace_id、message。业务字段按需添加，避免冗余。
2.3 日志采集架构：Filebeat → Logstash
在微服务和容器化环境中，日志采集需要轻量、可靠、可扩展。业界主流方案采用 Filebeat（轻量采集器） + Logstash（集中处理管道）的组合架构。
组件职责对比：
| 组件 | 定位 | 核心功能 | 资源消耗 |
|---|---|---|---|
| Filebeat | 轻量日志采集器 | 读取日志文件、发送到下游（Kafka/Logstash/ES） | 低（Go 编写） |
| Logstash | 数据处理管道 | 解析、过滤、转换、丰富日志数据 | 中高（JVM 运行） |
典型采集流程：
- Filebeat 采集：部署在每个节点上，监控日志文件变化，读取新增行。
- 传输缓冲：Filebeat 将日志发送到 Kafka（可选，用于削峰填谷）或直接发送到 Logstash。
- Logstash 处理：通过 filter 插件解析 JSON、提取字段、转换时间格式、添加地理信息等。
- 输出存储：处理后的日志写入 Elasticsearch 或其他存储系统。
避坑提示：Filebeat 的
close_inactive 和 scan_frequency 参数需要根据日志写入频率调整。设置过短会导致日志文件被提前关闭，造成数据丢失；设置过长则增加内存占用。
2.4 本节小结
- 日志级别是控制日志输出量的第一道阀门，生产环境默认开启 INFO 及以上。
- 结构化日志将文本转化为可查询的数据，是自动化分析的基础。
- Filebeat + Logstash 是经典的轻量采集 + 集中处理架构，适用于大多数生产场景。