---
title: "Rollup 统计刷新间隔配置"
date: 2026-02-13
lastmod: 2026-02-13
description: "monitor.rollup.stats_refresh_interval 配置项用于控制 Rollup 任务统计信息的刷新间隔。"
tags: ["监控", "Rollup", "任务统计", "数据聚合"]
summary: "配置项作用 #  monitor.rollup.stats_refresh_interval 配置项用于控制Rollup 任务统计信息的定期刷新间隔时间。
此配置决定了系统多久从 .easysearch-ilm-config 索引中获取和缓存一次滚动任务统计信息，包括处理的页面数、文档数、索引时间等指标。
配置项属性 #   配置路径: monitor.rollup.stats_refresh_interval 数据类型: TimeValue（时间值） 默认值: 5s（5秒） 最小值: 1s（理论） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  Rollup 统计刷新机制 定时任务 (scheduleWithFixedDelay): 上次刷新完成 │ ↓ 等待 refresh_interval │ ↓ 触发本次刷新 │ ├── 检查 Rollup 插件是否安装 ├── 检查集群状态 ├── 检查索引是否存在 ├── 发送 cluster:admin/monitor/rollup/stats 请求 ├── 获取 Rollup 任务统计信息 └── 缓存统计结果 │ ↓ 刷新完成 ↓ 等待 refresh_interval │ ↓ (循环) 示例 (refresh_interval = 5s): 00:00 ──→ 刷新 1 开始 00:00 ──→ 刷新 1 完成 00:05 ──→ 刷新 2 开始 00:05 ──→ 刷新 2 完成 00:10 ──→ 刷新 3 开始 ."
---


## 配置项作用

`monitor.rollup.stats_refresh_interval` 配置项用于控制**Rollup 任务统计信息的定期刷新间隔时间**。

此配置决定了系统多久从 `.easysearch-ilm-config` 索引中获取和缓存一次滚动任务统计信息，包括处理的页面数、文档数、索引时间等指标。

## 配置项属性

- **配置路径**: `monitor.rollup.stats_refresh_interval`
- **数据类型**: `TimeValue`（时间值）
- **默认值**: `5s`（5秒）
- **最小值**: `1s`（理论）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
Rollup 统计刷新机制

定时任务 (scheduleWithFixedDelay):

上次刷新完成
    │
    ↓ 等待 refresh_interval
    │
    ↓
触发本次刷新
    │
    ├── 检查 Rollup 插件是否安装
    ├── 检查集群状态
    ├── 检查索引是否存在
    ├── 发送 cluster:admin/monitor/rollup/stats 请求
    ├── 获取 Rollup 任务统计信息
    └── 缓存统计结果
    │
    ↓ 刷新完成
    ↓
等待 refresh_interval
    │
    ↓ (循环)


示例 (refresh_interval = 5s):

00:00 ──→ 刷新 1 开始
00:00 ──→ 刷新 1 完成
00:05 ──→ 刷新 2 开始
00:05 ──→ 刷新 2 完成
00:10 ──→ 刷新 3 开始
...
```

## Rollup 统计信息内容

```
Rollup 统计包含的数据

1. 处理统计
   ├── pages_processed
   │   └── 已处理的页面数量
   ├── documents_processed
   │   └── 已处理的原始文档数量
   └── rollups_indexed
       └── 已索引的滚动文档数量


2. 时间统计
   ├── index_time_in_millis
   │   └── 索引滚动文档花费的总时间
   └── search_time_in_millis
       └── 查询/聚合实时文档花费的总时间


3. 任务状态
   ├── 任务 ID
   ├── 任务状态
   └── 任务配置


4. 其他信息
   ├── 时间戳
   ├── 节点信息
   └── 索引信息
```

## 禁用定期刷新

```
设置 <= 0 可以禁用定期刷新

refresh_interval <= 0:
    │
    ↓
logger.info("Rollup stats periodic refresh is disabled (interval is non-positive).")
    │
    ↓
定时任务不启动
    │
    ↓
不自动刷新统计信息
```

## 配置建议

## 生产环境（默认）

```yaml
monitor:
  rollup:
    stats_refresh_interval: 5s  # 默认值
```

**建议**: 保持默认值 `5s`。平衡实时性和开销。

## 减少刷新频率

```yaml
monitor:
  rollup:
    stats_refresh_interval: 10s  # 减少刷新
```

**建议**: 设置为 `10-30s`。Rollup 任务不频繁时使用。

## 高频刷新

```yaml
monitor:
  rollup:
    stats_refresh_interval: 1s  # 更频繁
```

**建议**: 设置为 `1-3s`。需要实时监控 Rollup 状态时使用。

## 禁用自动刷新

```yaml
monitor:
  rollup:
    stats_refresh_interval: -1  # 禁用
```

**建议**: 设置为 `-1` 或 `0s`。不需要自动刷新时使用。

## 代码示例

## easysearch.yml 基础配置

```yaml
monitor:
  rollup:
    stats_refresh_interval: 5s
```

## 标准生产配置

```yaml
monitor:
  rollup:
    stats_refresh_interval: 5s
```

## 低频率配置

```yaml
monitor:
  rollup:
    stats_refresh_interval: 30s
```

## 禁用自动刷新配置

```yaml
monitor:
  rollup:
    stats_refresh_interval: -1
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `monitor.rollup.stats_refresh_interval` | Rollup 统计刷新间隔 | 5s |
| `rollup.*` | Rollup 任务配置 | - |

## 性能影响分析

| stats_refresh_interval 设置 | 优点 | 缺点 |
|------------------------------|------|------|
| -1/0s | 无开销 | 无自动监控 |
| 1-3s | 实时监控 | 较高查询开销 |
| 5s（默认） | 平衡监控和开销 | 标准设置 |
| 10-30s | 低查询开销 | 监控延迟 |
| 60s+ | 最低查询开销 | 延迟较大 |

## 查询开销对比

```
不同间隔的查询开销

refresh_interval = 5s (默认):
├── 每分钟查询: 12 次
├── 单次开销: ~10ms (查询 .easysearch-ilm-config)
└── 每分钟开销: ~120ms (0.2%)


refresh_interval = 1s:
├── 每分钟查询: 60 次
├── 单次开销: ~10ms
└── 每分钟开销: ~600ms (1%)


refresh_interval = 10s:
├── 每分钟查询: 6 次
├── 单次开销: ~10ms
└── 每分钟开销: ~60ms (0.1%)


refresh_interval = 30s:
├── 每分钟查询: 2 次
├── 单次开销: ~10ms
└── 每分钟开销: ~20ms (0.03%)
```

## 使用场景

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

- **标准 Rollup**: 正常的 Rollup 任务运行
- **定期监控**: 需要定期了解任务状态
- **平衡需求**: 平衡实时性和开销

## 推荐增加间隔的场景

- **少量任务**: Rollup 任务数量很少
- **减少开销**: 希望减少查询开销
- **长期任务**: 长期运行的 Rollup 任务

## 推荐减少间隔的场景

- **频繁监控**: 需要实时监控任务状态
- **调试 Rollup**: 正在调试 Rollup 任务
- **关键任务**: Rollup 任务非常关键

## 推荐禁用的场景

- **不需要监控**: 不需要自动监控 Rollup
- **手动查询**: 只需要时手动查询
- **节省资源**: 希望节省集群资源

## Rollup 任务监控

```
监控 Rollup 任务的重要性

监控指标:

pages_processed:
├── 反映处理的页面数量
├── 持续增加 → 任务正常 ✅
└── 不变 → 可能有问题 ⚠️


documents_processed:
├── 反映处理的文档数量
├── 与源数据增长匹配
└── 可预测处理速度


rollups_indexed:
├── 反映生成的滚动文档数量
├── 持续增长 → 任务正常 ✅
└── 不变 → 可能有问题 ⚠️


index_time_in_millis:
├── 反映索引耗时
├── 突然增加 → 性能问题 ⚠️
└── 持续高位 → 需要优化


search_time_in_millis:
├── 反映查询耗时
├── 突然增加 → 源数据问题 ⚠️
└── 持续高位 → 需要优化
```

## 数据延迟分析

```
监控数据的延迟

refresh_interval = 5s (默认):
00:00 ──→ Rollup 统计: pages=1000
00:02 ──→ Rollup 统计: pages=2000 (实际变化)
00:03 ──→ 查询 → 返回 1000 (缓存)
00:05 ──→ 缓存刷新 → 获取到 2000
00:06 ──→ 查询 → 返回 2000 ✅
延迟: 最多 5 秒


refresh_interval = 30s:
00:00 ──→ Rollup 统计: pages=1000
00:10 ──→ Rollup 统计: pages=2000 (实际变化)
00:15 ──→ 查询 → 返回 1000 (缓存)
00:30 ──→ 缓存刷新 → 获取到 2000
00:35 ──→ 查询 → 返回 2000 ✅
延迟: 最多 30 秒
```

## 刷新流程详解

```
fetchAndCacheStats() 流程

1. 检查前置条件
   ├── Rollup 插件是否安装
   ├── 集群状态是否正常
   └── 索引是否存在且状态正常


2. 发送统计请求
   cluster:admin/monitor/rollup/stats
   ├── 目标: .easysearch-ilm-config 索引
   ├── 获取所有 Rollup 任务统计
   └── 返回统计结果


3. 缓存统计结果
   ├── 更新内部缓存
   ├── 供 API 查询使用
   └── 记录时间戳


4. 错误处理
   ├── 索引不存在 → 记录警告，继续
   ├── 插件未安装 → 记录警告，继续
   └── 请求失败 → 记录错误，继续
```

## 注意事项

1. **默认值**: 默认值为 `5s`，适合大多数场景。

2. **禁用设置**: 设置为 `<= 0` 会禁用定期刷新。

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

4. **固定延迟**: 使用 `scheduleWithFixedDelay` 策略。

5. **索引依赖**: 需要 `.easysearch-ilm-config` 索引。

6. **插件依赖**: 需要 Rollup 插件安装。

7. **查询开销**: 刷新会查询集群状态。

8. **监控建议**: 根据任务数量调整间隔。

9. **测试验证**: 配置变更后应验证刷新效果。

10. **手动查询**: 禁用后仍可手动查询统计。

## 相关 API

```
获取 Rollup 统计的 API

手动查询统计:
GET /_rollup/stats

响应:
{
  "jobs": [
    {
      "job_id": "rollup_job_1",
      "status": "started",
      "stats": {
        "pages_processed": 1000,
        "documents_processed": 100000,
        "rollups_indexed": 50000,
        "index_time_in_millis": 5000,
        "search_time_in_millis": 2000
      }
    }
  ]
}


监控集成:
├── Prometheus Exporter
├── 自定义监控脚本
└── 运维平台集成
```