---
title: "日志级别配置"
date: 2026-03-04
lastmod: 2026-03-04
description: "logger.level 配置项用于控制 Easysearch 的默认日志输出级别。"
tags: ["日志", "调试", "运维", "Log4j2"]
summary: "配置项作用 #  logger.level 配置项用于控制Easysearch 系统中所有日志记录器的默认日志级别。
当没有为特定日志记录器设置级别时，所有日志将使用这个默认级别。此配置影响日志系统的基础日志级别，决定哪些级别的日志信息会被输出。
配置项属性 #   配置路径: logger.level 数据类型: Level（Log4j2 日志级别枚举） 默认值: INFO 可选值: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  日志级别层次 FATAL (最高) ↓ ERROR ↓ WARN ↓ INFO ← 默认级别 ↓ DEBUG ↓ TRACE (最低) 日志输出规则: ├── 只输出 >= 设置级别的日志 ├── 低级别日志被过滤 └── 高级别日志总是输出 示例: logger.level = INFO 输出: ├── FATAL 日志 ✅ ├── ERROR 日志 ✅ ├── WARN 日志 ✅ ├── INFO 日志 ✅ ├── DEBUG 日志 ❌ (被过滤) └── TRACE 日志 ❌ (被过滤) 日志继承机制 #  日志记录器层次 Root Logger (logger."
---


## 配置项作用

`logger.level` 配置项用于控制**Easysearch 系统中所有日志记录器的默认日志级别**。

当没有为特定日志记录器设置级别时，所有日志将使用这个默认级别。此配置影响日志系统的基础日志级别，决定哪些级别的日志信息会被输出。

## 配置项属性

- **配置路径**: `logger.level`
- **数据类型**: `Level`（Log4j2 日志级别枚举）
- **默认值**: `INFO`
- **可选值**: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `OFF`
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
日志级别层次

FATAL (最高)
    ↓
ERROR
    ↓
WARN
    ↓
INFO ← 默认级别
    ↓
DEBUG
    ↓
TRACE (最低)


日志输出规则:
├── 只输出 >= 设置级别的日志
├── 低级别日志被过滤
└── 高级别日志总是输出


示例: logger.level = INFO

输出:
├── FATAL 日志 ✅
├── ERROR 日志 ✅
├── WARN 日志 ✅
├── INFO 日志 ✅
├── DEBUG 日志 ❌ (被过滤)
└── TRACE 日志 ❌ (被过滤)
```

## 日志继承机制

```
日志记录器层次

Root Logger (logger.level = INFO)
    │
    ├── org.easysearch (继承 INFO)
    │   │
    │   ├── transport (继承 INFO)
    │   │   └── TransportService.logger → 输出 INFO+
    │   │
    │   └── index (继承 INFO)
    │       └── IndexService.logger → 输出 INFO+
    │
    └── 其他包 (继承 INFO)


特定配置覆盖:

logger.level: INFO
logger.org.easysearch.transport.level: DEBUG


效果:
Root Logger → 输出 INFO+
org.easysearch.transport → 输出 DEBUG+ ✅
其他包 → 输出 INFO+
```

## 配置加载流程

```
日志配置初始化

1. 读取 easysearch.yml
   │
   ↓
2. 解析 logger.level
   │
   ↓
3. 应用到 Root Logger
   │
   ↓
4. 加载特定 logger 配置
   │
   ↓
5. 初始化 Log4j2
   │
   ↓
6. 日志系统就绪


代码流程:
LogConfigurator.configureLoggerLevels()
    │
    ├── 读取 logger.level
    │
    ├── Loggers.setLevel(RootLogger, level)
    │
    └── 读取特定 logger.*.level
        │
        └── Loggers.setLevel(特定Logger, level)
```

## 配置建议

## 生产环境（推荐）

```yaml
logger.level: INFO  # 默认值
```

**建议**: 保持 `INFO` 级别。平衡日志详细程度和性能。

## 生产环境（精简）

```yaml
logger.level: WARN  # 仅警告和错误
```

**建议**: 设置为 `WARN`。减少日志量，降低磁盘 I/O。

## 开发/调试环境

```yaml
logger.level: DEBUG  # 调试信息
```

**建议**: 设置为 `DEBUG`。开发或排查问题时使用。

## 故障排查

```yaml
logger.level: TRACE  # 最详细的日志
```

**建议**: 设置为 `TRACE`。临时排查问题时使用。

## 禁用日志

```yaml
logger.level: OFF  # 关闭日志
```

**建议**: 慎用。仅在特殊场景下使用。

## 代码示例

## easysearch.yml 基础配置

```yaml
logger.level: INFO
```

## 生产环境配置

```yaml
logger.level: WARN
```

## 开发环境配置

```yaml
logger.level: DEBUG
```

## 特定模块调试

```yaml
# 全局级别
logger.level: INFO

# 特定模块调试级别
logger.org.easysearch.transport.level: DEBUG
logger.org.easysearch.index.level: DEBUG
logger.org.easysearch.cluster.level: TRACE
```

## 通过系统属性设置

```bash
# 启动时通过系统属性设置
./bin/easysearch -Des.logger.level=DEBUG
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `logger.level` | 全局日志级别 | INFO |
| `logger.*.level` | 特定模块日志级别 | 继承全局 |

## 日志级别说明

| 级别 | 描述 | 使用场景 |
|------|------|----------|
| FATAL | 致命错误，可能导致系统终止 | 系统崩溃、无法恢复的错误 |
| ERROR | 错误，但系统可以继续运行 | 异常、错误操作 |
| WARN | 警告，潜在问题 | 弃用警告、配置问题 |
| INFO | 信息，正常运行消息 | 启动、关闭、状态变化 |
| DEBUG | 调试信息，详细的运行细节 | 开发、调试 |
| TRACE | 追踪信息，最详细的日志 | 深度调试、性能分析 |
| OFF | 关闭日志输出 | 特殊场景 |

## 日志量对比

```
假设系统运行 1 小时

FATAL: ~0 条
ERROR: ~10 条
WARN: ~100 条
INFO: ~10000 条
DEBUG: ~100000 条
TRACE: ~1000000 条


不同级别的日志量:

INFO: 10 MB
WARN: 100 KB
ERROR: 10 KB
FATAL: ~0 KB


DEBUG: 100 MB
INFO: 10 MB
WARN: 100 KB
ERROR: 10 KB


TRACE: 1000 MB
DEBUG: 100 MB
INFO: 10 MB
WARN: 100 KB
```

## 性能影响分析

| logger.level 设置 | 优点 | 缺点 |
|-------------------|------|------|
| OFF | 最高性能 | 无日志可查 |
| WARN | 低日志量 | 调试困难 |
| INFO（默认） | 平衡性能和可调试性 | 标准设置 |
| DEBUG | 易于调试 | 日志量大，性能影响 |
| TRACE | 最详细 | 严重的性能影响 |

## 性能影响对比

```
日志性能开销估算

INFO:
├── 日志量: 适中
├── 磁盘 I/O: 适中
├── CPU 开销: 适中
└── 性能影响: ~5% ✅


DEBUG:
├── 日志量: 大
├── 磁盘 I/O: 高
├── CPU 开销: 高
└── 性能影响: ~15-20%


TRACE:
├── 日志量: 很大
├── 磁盘 I/O: 很高
├── CPU 开销: 很高
└── 性能影响: ~30-50% ❌
```

## 使用场景

## 推荐使用 INFO 的场景

- **生产环境**: 正常的生产运行
- **平衡需求**: 平衡日志量和性能
- **标准监控**: 需要基本的系统可见性

## 推荐使用 WARN 的场景

- **高性能**: 需要最小化日志开销
- **高并发**: 高并发场景减少 I/O
- **磁盘受限**: 磁盘空间有限

## 推荐使用 DEBUG 的场景

- **开发环境**: 开发和测试阶段
- **问题排查**: 排查具体问题
- **性能分析**: 分析系统性能

## 推荐使用 TRACE 的场景

- **深度调试**: 需要最详细的日志
- **问题追踪**: 追踪复杂问题
- **短期使用**: 临时开启，用完即关

## 特定模块配置

```
为特定模块设置不同级别

全局配置:
logger.level: INFO


传输层调试:
logger.org.easysearch.transport.level: DEBUG
logger.org.easysearch.transport.netty.level: TRACE


索引层调试:
logger.org.easysearch.index.level: DEBUG
logger.org.easysearch.index.shard.level: TRACE


集群调试:
logger.org.easysearch.cluster.level: DEBUG
logger.org.easysearch.discovery.level: TRACE


效果:
├── 大部分模块: INFO
├── 传输层: DEBUG/TRACE
├── 索引层: DEBUG/TRACE
└── 集群: DEBUG/TRACE
```

## 日志文件管理

```
日志文件轮转策略

log4j2.properties 配置:

appender.rolling.strategy.type = SizeBasedTriggeringPolicy
appender.rolling.strategy.size = 1GB

appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 10


结合 logger.level 使用:

INFO:
├── 日志量: 10 MB/小时
├── 单文件: ~1 GB / 100 小时
└── 可保留: ~10 天 ✅


DEBUG:
├── 日志量: 100 MB/小时
├── 单文件: ~1 GB / 10 小时
└── 可保留: ~1 天 ⚠️


TRACE:
├── 日志量: 1000 MB/小时
├── 单文件: ~1 GB / 1 小时
└── 可保留: ~10 小时 ❌
```

## 注意事项

1. **默认值**: 默认值为 `INFO`，适用于大多数场景。

2. **需要重启**: 修改此配置需要重启节点。

3. **性能影响**: 日志级别越低，性能影响越大。

4. **磁盘空间**: 低级别日志会产生大量日志文件。

5. **特定模块**: 可以为特定模块设置不同的日志级别。

6. **临时使用**: DEBUG 和 TRACE 应该临时使用。

7. **监控建议**: 监控日志文件大小和磁盘使用。

8. **日志轮转**: 配合日志轮转策略使用。

9. **敏感信息**: 注意日志中可能包含敏感信息。

10. **测试验证**: 生产环境变更前应先在测试环境验证。