etcd 日志规范全解：zap 日志等级约定、配置参数与源码实现

etcd 使用 zap 库输出应用日志，并为每种日志等级（Debug、Info、Warning、Error、Panic、Fatal）定义了严格的判定约定。本文以 etcd 官方贡献者指南中的日志规范为核心，结合 client/pkg/logutil、server/embed/config_logging.go 等源码，完整讲解 etcd 日志等级的语义边界、对应的命令行配置参数（--log-level、--log-format、--log-outputs、--logger）及日志轮转机制，帮助你在生产环境中正确配置日志级别、排查日志输出问题，并理解贡献代码时如何选对日志等级。

一、为什么日志等级约定如此重要

etcd 承载分布式系统最关键的数据，其日志是运维排障与审计的第一现场。官方日志约定文档明确了 etcd 使用 zap 库，并将日志消息的等级划分依据写成了贡献者规范。这意味着两件事：

• 对运维人员：日志等级本身携带语义——看到 warn 和看到 error，应采取的行动完全不同；
• 对贡献者：提交代码时若日志等级不符合约定，会破坏下游基于日志告警的自动化运维体系。

下面逐条展开各等级的定义与典型场景，并对照源码说明 etcd 如何落地这些约定。

二、六种日志等级的语义与典型示例

etcd 定义了六种日志等级，每种等级都有明确的判定标准。以下是约定的完整内容：

Debug：一切正常，但细节很多

一切仍然正常，但可能会记录常见操作，以及帮助性较低但数量较多的通知。通常不在生产环境使用。

典型示例：

• 向远端 peer 发送一条普通消息；
• 向日志盘写入一条日志记录。

对应源码层面，etcd 的 gRPC 调用追踪正是在 debug 等级下才启用：在 server/embed/config_logging.go 的 SetupGlobalLoggers 方法中，仅当 cfg.LogLevel == "debug" 时才会执行 grpc.EnableTracing = true 并把 gRPC 日志接入 zap logger，其他等级下 gRPC 日志直接丢弃到 io.Discard。这体现了 Debug 级“帮助性较低但量大”的定位——生产环境开启会带来可观的日志量。

Info：正常运行信息

正常的工作日志信息，一切正常，但包含用于审计或常见操作的有用通知。在正常服务器运行中，不应比每隔几秒更频繁地输出。

典型示例：

• 启动时的配置信息（startup configuration）；
• 开始做快照（start to do a snapshot）。

“每几秒一次”是 Info 级的频率红线。etcd 源码中启动配置打印、快照触发（snapshot compaction 启动）等日志正遵循此节奏。这也是为什么 client/pkg/logutil/log_level.go 中将 DefaultLogLevel = "info" 定为默认等级——生产环境只关心“有用但不高频”的信息。

Warning：（希望是）暂时的、可能出错的状况

（希望是）暂时的、可能导致错误但也可能运行正常的状况。一个副本消失（但可能重新连接）就属于警告。

典型示例：

• 向远端 peer 发送 raft 消息失败；
• 在配置的选举超时时间内未能收到心跳消息。

注意 Warning 的关键语义是“暂时性”：raft 网络抖动、peer 短暂失联、选举超时未收心跳，都属于集群能自愈的范畴。此外，etcd 在实际代码中也遵循了“避免刷屏”的 warning 使用原则，例如 server/embed/config_logging.go 中 TLS 握手失败的回调：EOF 类错误降级为 Debug 记录（Log EOF errors on DEBUG not to spam logs too much），只有真正的证书/协议问题才按 Warn 输出。

Error：数据丢失或请求因严重原因失败

数据已丢失、一个请求因糟糕的原因失败，或者一个必需的 resources 已丢失。

典型示例：

• 为 WAL 分配磁盘空间失败。

etcd 将 WAL 写盘空间不足视为 Error 级，因为此时已触及数据可靠性底线。源码中对应的错误语义可见 server/etcdserver/errors/errors.go 中的 ErrNoSpace（"etcdserver: no space"），测试用例 server/storage/wal/wal_test.go 中也专门验证了 "no space left on device" 场景的错误路径。

Panic：不可恢复且需要停止执行

不可恢复或意外错误状况，需要停止执行。

典型示例：创建数据库失败。

Panic 意味着进程状态已无法保证一致性，应中断执行交由运维介入。

Fatal：不可恢复且需要立即退出

不可恢复或意外错误状况，需要立即退出。大多在测试中使用。

典型示例：

• 找不到数据目录；
• 运行测试函数失败。

从约定本身看，Panic 与 Fatal 的区别在于处理策略：Panic 停止执行（留下现场供分析），Fatal 直接终止进程。文档特别注明 Fatal “Mostly used in the test”，说明生产路径上 etcd 优先使用 Panic 而非 Fatal。

三、日志等级的实现：logutil 包

等级约定落地为代码，核心在独立的 client/pkg/v3/logutil 包（当前仓库中的 client/pkg/logutil 目录）。

等级字符串到 zap 等级的转换

client/pkg/logutil/log_level.go 提供了转换入口：

var DefaultLogLevel = "info"

// ConvertToZapLevel converts log level string to zapcore.Level.
func ConvertToZapLevel(lvl string) zapcore.Level {
	var level zapcore.Level
	if err := level.Set(lvl); err != nil {
		panic(err)
	}
	return level
}

注意这里对非法等级字符串的处理是 panic——这本身与上一节 Panic 级“不可恢复状况停止执行”的约定一致：日志等级属于进程启动早期就必须确定的配置，出错时不应带病运行。

默认 zap 配置：采样、编码与输出路径

client/pkg/logutil/zap.go 定义了 DefaultZapLoggerConfig，几个关键点对排障很实用：

• 采样（Sampling）：Initial: 100, Thereafter: 100，即同等级日志首次放行 100 条后，每 100 条只放行 1 条。这是防止日志风暴的保护机制——如果生产环境看到日志密度突然下降，应先怀疑触发了采样，而不是日志“丢了”。
• 时间格式：2006-01-02T15:04:05.000000Z0700，注释中明确说明是特意与历史 capnslog 的时间戳格式、精度保持一致，保证日志聚合工具（如基于时间戳解析的方案）在 capnslog → zap 切换时平滑兼容。
• 字段命名：ts / level / logger / caller / msg / stacktrace，级别用 LowercaseLevelEncoder 小写输出（即前文各等级的 debug/info/warn/error 等小写形式）。
• 默认输出路径：stderr，/dev/null 可用于完全丢弃日志；MergeOutputPaths 负责合并多个输出目标并去重。

四、命令行配置：等级、格式与输出目标

etcd 服务端的日志配置通过 embed 包的 Config 暴露，字段定义见 server/embed/config.go，flag 注册见同文件 L708-L710。四个核心参数如下：

--logger

日志实现选择，目前仅支持 zap；capnslog 自 v3.5 起被移除。server/embed/config_logging.go 的 setupLogging 中直接对 capnslog 返回错误：

case "capnslog": // removed in v3.5
    return fmt.Errorf("--logger=capnslog is removed in v3.5")

--log-level

取值 debug, info, warn, error, panic, fatal，默认 info（由 logutil.DefaultLogLevel 决定）。这就是第二节六种等级约定的直接配置入口：

etcd --log-level debug   # 排障时开启，会同时启用 gRPC 追踪日志
etcd --log-level warn    # 只看临时性异常，如 raft 消息发送失败

--log-format

取值 json（默认）或 console，由 client/pkg/logutil/log_format.go 的 ConvertToZapFormat 校验，非法值会报错 unknown log format: %s, supported values json, console。JSON 格式适合机器采集，console 格式适合人工查看。

--log-outputs

支持多个逗号分隔的输出目标，语义见 config.go 的字段注释：

• default（默认）：作为 os.Stderr 处理；在 systemd/journald 环境下会改写为写入 journal；
• stderr / stdout：即使运行在 systemd 下也强制走标准流、跳过 journald；
• 文件路径：追加写入该文件。

server/embed/config_logging.go 中 setupLogging 的分支逻辑还包含一个易踩的约束：当配置了多个输出目标时不允许包含 default（"multi logoutput for %q is not supported yet"）；而使用 journal 输出时，其他目标必须全部显式指定为具体值，否则报错提示覆盖 default。

五、日志轮转：--enable-log-rotation

当 --log-outputs 指向文件且启用轮转时，etcd 通过 lumberjack 实现单文件目标的大小/时间/备份数轮转。相关实现与约束（server/embed/config_logging.go 的 setupLogRotation）：

• 只支持一个文件目标：default/stderr/stdout 这类标准流目标被跳过计数，若没有任何文件目标（报 ErrLogRotationInvalidLogOutput）或文件目标超过 1 个，均直接报错；
• 轮转参数透传：--log-rotation-config-json 直接透传给 lumberjack，JSON 语法错误会分类报 "improperly formatted log rotation config"，类型错误报 "invalid log rotation config"；
• 机制：向 zap 注册 rotate scheme 的 sink，文件目标被改写成 rotate:/path 形式接入 zap 输出管道。

配置示例（以当前仓库支持的参数为准）：

etcd \
  --logger zap \
  --log-level info \
  --log-format json \
  --log-outputs /var/log/etcd.log \
  --enable-log-rotation \
  --log-rotation-config-json '{"maxsize":100,"maxbackups":5,"maxage":30}'

其中 maxsize 单位为 MB，达到阈值或按时间/备份数策略滚动文件。

六、贡献代码时如何选对日志等级

回到规范文档本身，它对贡献者的实际约束可以归纳为一张决策表：

状况	等级	文档示例
常见操作、量大的细节通知	Debug	向远端 peer 发送普通消息；写日志到盘
正常工作的审计/常用信息（频率不超过每几秒一次）	Info	启动配置；开始快照
暂时性异常，可能自愈	Warning	raft 消息发送失败；选举超时内未收心跳
数据丢失 / 请求因严重原因失败 / 必需资源丢失	Error	WAL 磁盘空间分配失败
不可恢复，需要停止执行	Panic	创建数据库失败
不可恢复，需要立即退出（多用于测试）	Fatal	找不到数据目录；测试函数执行失败

评审贡献时的两条实用检查点：

1. 频率检查：如果某条 Info 日志在正常集群中高频出现（如每个请求都打），违反了 Info 级“每几秒一次”的约定，应降级或改为 Debug；
2. 可恢复性检查：raft peer 重连、网络抖动类问题属于“暂时状况”，只能是 Warning；而数据完整性受损必须升为 Error。仓库中 TLS 握手失败回调对 EOF 降级的处理（config_logging.go）可作为遵循该原则的代码范例。

小结

etcd 的日志体系由两层构成：一是对人的等级语义约定（六种等级各有明确判定标准与示例），二是对机器的配置与实现（logutil 包的等级转换、采样与编码，embed 包的 --logger / --log-level / --log-format / --log-outputs / --enable-log-rotation 参数解析与轮转）。生产排障时建议保持默认 info 级别、按需临时提升 debug；贡献代码时则严格按“频率 + 可恢复性”两个维度对号入座，确保日志等级约定在整个代码库中保持一致。