---
title: "JVM GC 开销调试阈值配置"
date: 2026-02-17
lastmod: 2026-02-17
description: "monitor.jvm.gc.overhead.debug 配置项用于控制 JVM GC 开销的 DEBUG 级别日志阈值。"
tags: ["监控", "JVM", "GC", "性能调优"]
summary: "配置项作用 #  monitor.jvm.gc.overhead.debug 配置项用于控制JVM 垃圾回收（GC）开销的 DEBUG 级别日志阈值。
当 GC 开销（GC 时间占总时间的百分比）达到或超过此阈值时，系统会记录 DEBUG 级别的日志，帮助开发人员分析 GC 行为。
配置项属性 #   配置路径: monitor.jvm.gc.overhead.debug 数据类型: Integer（整数） 默认值: 10（10%） 取值范围: 0-100（百分比） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  GC 开销监控流程 监控周期: refresh_interval (默认 1s) 每个周期: ├── 记录上次 GC 时间 ├── 记录当前 GC 时间 ├── 计算周期总耗时 ├── 计算 GC 开销百分比 └── 判断日志级别 GC 开销计算: fraction = (GC 时间 / 总时间) × 100 日志级别判断: if (fraction >= warn_threshold) { → WARN 日志 ⚠️ } else if (fraction >= info_threshold) { → INFO 日志 ℹ️ } else if (fraction >= debug_threshold) { → DEBUG 日志 🔍 } else { → 不记录日志 } 阈值层级 #  三个 GC 开销阈值 默认配置: ├── WARN: 50% ├── INFO: 25% └── DEBUG: 10% 阈值关系: WARN (50%) > INFO (25%) > DEBUG (10%) 日志输出: GC 开销 = 5%: ├── 5% < 10% (DEBUG) └── 不记录日志 GC 开销 = 15%: ├── 15% >= 10% (DEBUG) ├── 15% < 25% (INFO) └── 记录 DEBUG 日志 🔍 GC 开销 = 30%: ├── 30% >= 25% (INFO) ├── 30% < 50% (WARN) └── 记录 INFO 日志 ℹ️ GC 开销 = 60%: ├── 60% >= 50% (WARN) └── 记录 WARN 日志 ⚠️ DEBUG 日志示例 #  DEBUG 日志格式 [gc][{seq}] overhead, spent [{gc_time}] collecting in the last [{total_time}] 示例: [gc][1] overhead, spent [150ms] collecting in the last [1000ms] ├── 序列号: 1 ├── GC 时间: 150ms ├── 总时间: 1000ms ├── GC 开销: 15% └── 级别: DEBUG (15% >= 10%) 配置建议 #  生产环境（默认） #  monitor: jvm: gc: overhead: debug: 10 # 默认值 建议: 保持默认值 10%。适合大多数生产环境。"
---


## 配置项作用

`monitor.jvm.gc.overhead.debug` 配置项用于控制**JVM 垃圾回收（GC）开销的 DEBUG 级别日志阈值**。

当 GC 开销（GC 时间占总时间的百分比）达到或超过此阈值时，系统会记录 DEBUG 级别的日志，帮助开发人员分析 GC 行为。

## 配置项属性

- **配置路径**: `monitor.jvm.gc.overhead.debug`
- **数据类型**: `Integer`（整数）
- **默认值**: `10`（10%）
- **取值范围**: `0-100`（百分比）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
GC 开销监控流程

监控周期: refresh_interval (默认 1s)

每个周期:
├── 记录上次 GC 时间
├── 记录当前 GC 时间
├── 计算周期总耗时
├── 计算 GC 开销百分比
└── 判断日志级别


GC 开销计算:
fraction = (GC 时间 / 总时间) × 100


日志级别判断:
if (fraction >= warn_threshold) {
    → WARN 日志 ⚠️
} else if (fraction >= info_threshold) {
    → INFO 日志 ℹ️
} else if (fraction >= debug_threshold) {
    → DEBUG 日志 🔍
} else {
    → 不记录日志
}
```

## 阈值层级

```
三个 GC 开销阈值

默认配置:
├── WARN: 50%
├── INFO: 25%
└── DEBUG: 10%


阈值关系:
WARN (50%) > INFO (25%) > DEBUG (10%)


日志输出:
GC 开销 = 5%:
├── 5% < 10% (DEBUG)
└── 不记录日志


GC 开销 = 15%:
├── 15% >= 10% (DEBUG)
├── 15% < 25% (INFO)
└── 记录 DEBUG 日志 🔍


GC 开销 = 30%:
├── 30% >= 25% (INFO)
├── 30% < 50% (WARN)
└── 记录 INFO 日志 ℹ️


GC 开销 = 60%:
├── 60% >= 50% (WARN)
└── 记录 WARN 日志 ⚠️
```

## DEBUG 日志示例

```
DEBUG 日志格式

[gc][{seq}] overhead, spent [{gc_time}] collecting in the last [{total_time}]


示例:

[gc][1] overhead, spent [150ms] collecting in the last [1000ms]
├── 序列号: 1
├── GC 时间: 150ms
├── 总时间: 1000ms
├── GC 开销: 15%
└── 级别: DEBUG (15% >= 10%)
```

## 配置建议

## 生产环境（默认）

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 10  # 默认值
```

**建议**: 保持默认值 `10%`。适合大多数生产环境。

## 开发环境

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 5  # 降低阈值
```

**建议**: 设置为 `5%`。获取更详细的调试信息。

## 高负载环境

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 15  # 提高阈值
```

**建议**: 设置为 `15%`。减少日志量。

## 禁用 DEBUG 日志

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 0  # 禁用
```

**建议**: 设置为 `0`。完全禁用 GC 开销的 DEBUG 日志。

## 代码示例

## easysearch.yml 基础配置

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 10
        info: 25
        warn: 50
```

## 开发调试配置

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 5
        info: 15
        warn: 30
```

## 生产优化配置

```yaml
monitor:
  jvm:
    gc:
      overhead:
        debug: 10
        info: 25
        warn: 50
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `monitor.jvm.gc.overhead.debug` | DEBUG 阈值 | 10% |
| `monitor.jvm.gc.overhead.info` | INFO 阈值 | 25% |
| `monitor.jvm.gc.overhead.warn` | WARN 阈值 | 50% |
| `monitor.jvm.gc.refresh_interval` | 监控刷新间隔 | 1s |

## 阈值约束

```
配置约束规则

必须满足:
WARN > INFO > DEBUG


错误示例:
debug: 25
info: 25  ❌ (必须大于 DEBUG)
warn: 50


正确示例:
debug: 10
info: 25  ✅
warn: 50


启动验证:
if (info <= debug) {
    throw IllegalArgumentException(
        "monitor.jvm.gc.overhead.info must be greater than monitor.jvm.gc.overhead.debug"
    )
}
```

## 使用场景

## 推荐使用默认值的场景

- **标准应用**: 正常的 Java 应用
- **平衡监控**: 平衡日志详细度和性能
- **生产环境**: 生产环境推荐配置

## 推荐降低阈值的场景

- **开发环境**: 需要详细的 GC 调试信息
- **性能调优**: 正在进行性能优化
- **问题排查**: 排查 GC 相关问题
- **测试环境**: 测试环境获取更多信息

## 推荐提高阈值的场景

- **高负载环境**: GC 开销本来就高
- **减少日志**: 希望减少日志量
- **稳定应用**: 应用非常稳定
- **存储受限**: 日志存储空间有限

## GC 开销分析

```
GC 开销的影响

GC 开销 < 10%:
├── 状态: 优秀 ✅
├── 应用流畅
└── 无需关注


GC 开销 10-25% (DEBUG):
├── 状态: 良好
├── 有一定 GC 压力
└── 记录 DEBUG 日志


GC 开销 25-50% (INFO):
├── 状态: 警告 ℹ️
├── GC 压力较大
└── 记录 INFO 日志


GC 开销 > 50% (WARN):
├── 状态: 严重 ⚠️
├── 大量时间在 GC
├── 应用性能下降
└── 记录 WARN 日志
```

## 性能调优建议

```
基于 GC 开销的调优

GC 开销持续 < 10%:
├── 堆内存配置合理 ✅
├── 无需调整
└── 继续监控


GC 开销持续在 10-25%:
├── 堆内存略显紧张
├── 建议增加堆内存
├── 或优化对象分配
└── 持续观察


GC 开销持续在 25-50%:
├── 堆内存明显不足 ℹ️
├── 应该增加堆内存
├── 或优化 GC 策略
└── 需要关注


GC 开销持续 > 50%:
├── 严重的内存问题 ⚠️
├── 必须增加堆内存
├── 检查内存泄漏
├── 优化 GC 策略
└── 紧急处理
```

## 注意事项

1. **阈值关系**: 必须满足 `WARN > INFO > DEBUG`。

2. **百分比单位**: 配置值是百分比（0-100）。

3. **启动验证**: 启动时会验证配置的正确性。

4. **GC 开销计算**: GC 时间 / 总时间 × 100。

5. **DEBUG 级别**: 需要日志级别设置为 DEBUG 才能看到。

6. **开发友好**: 开发环境可以降低阈值获取更多信息。

7. **生产建议**: 生产环境建议保持默认值。

8. **性能影响**: 日志记录对性能影响很小。

9. **配合使用**: 与其他 GC 监控配置配合使用。

10. **定期检查**: 定期检查 GC 开销日志评估内存配置。

## 日志级别配置

```
查看 DEBUG 日志的配置

log4j2.properties:
logger.jvm.name = org.easysearch.monitor.jvm
logger.jvm.level = debug


或者通过 easysearch.yml:
logger.org.easysearch.monitor.jvm.level: debug
```