Grafana 可视化 ClickHouse 的 TTL 清理进度

将 Grafana + ClickHouse 结合使用，是构建 ClickHouse 自监控系统 的最佳实践。特别是对于 TTL（Time To Live）数据清理进度 的可视化，能够帮助你实时掌握数据生命周期状态、验证 TTL 策略是否生效、评估存储优化效果。

本篇将详细介绍如何使用 Grafana 可视化 ClickHouse 的 TTL 清理进度，实现“数据何时过期、是否已清理、清理了多少”一目了然。

---

🎯 一、目标：监控 TTL 清理进度

我们希望在 Grafana 中展示以下关键指标：

指标	说明
✅ 待清理 Parts 数量	已过期但尚未删除的 Parts
✅ 待清理数据量（行数/字节）	即将被 TTL 删除的数据规模
✅ 已清理数据统计	历史 TTL 清理记录（行数、字节）
✅ TTL 策略执行延迟	数据过期后多久才被清理

---

🧰 二、环境准备

组件	要求
ClickHouse	≥ v20.8（推荐最新版）
Grafana	≥ v8.0
数据源插件	Grafana ClickHouse 插件
网络	Grafana 能访问 ClickHouse 的 HTTP 接口（8123）

✅ 安装插件：

grafana-cli plugins install grafana-clickhouse-datasource

---

🔗 三、步骤 1：配置 Grafana 数据源

1. 打开 Grafana → Configuration → Data Sources → Add data source
2. 选择 ClickHouse
3. 填写配置：
   • URL: http://clickhouse-server:8123
   • Database: default
   • Auth: 填写用户名密码（如 default / password）
4. 点击 Save & Test，确保连接成功

---

📊 四、步骤 2：创建仪表盘（Dashboard）

创建一个名为 “TTL Data Lifecycle Monitor” 的仪表盘，并添加以下 Panels。

---

Panel 1：待清理的过期 Parts（数量 & 数据量）

标题: Pending TTL Cleanup (Parts & Data)

查询:

SELECT
    count() AS parts_count,
    sum(rows) AS total_rows,
    formatBytes(sum(bytes_on_disk)) AS total_size
FROM system.parts
WHERE 
    database = 'default'
    AND table LIKE '%log%'  -- 可按需过滤表
    AND remove_time IS NOT NULL
    AND active = 1

可视化建议:

• 使用 Stat 或 Singlestat 面板
• 显示 parts_count, total_rows, total_size

✅ 说明：remove_time IS NOT NULL 表示该 Part 已过期，等待在下次 Merge 时删除。

---

Panel 2：各表 TTL 状态分布

标题: TTL Status by Table

查询:

SELECT
    table,
    count() AS parts_count,
    sum(rows) AS rows_pending,
    formatBytes(sum(bytes_on_disk)) AS size_pending,
    min(modification_time) AS oldest_part,
    max(modification_time) AS newest_part
FROM system.parts
WHERE 
    database = 'default'
    AND remove_time IS NOT NULL
    AND active = 1
GROUP BY table
ORDER BY size_pending DESC

可视化建议:

• 使用 Table 面板
• 添加排序：按 size_pending 降序

---

Panel 3：历史 TTL 清理记录（按天）

标题: Historical TTL Cleanup (Daily)

查询:

SELECT
    event_date,
    sum(rows_removed) AS rows_removed,
    formatBytes(sum(bytes_removed)) AS bytes_removed,
    count() AS cleanup_count
FROM system.part_log
WHERE 
    event_type = 'RemovePart'
    AND part_name LIKE '%ttl%'
    AND event_date >= today() - INTERVAL 30 DAY
GROUP BY event_date
ORDER BY event_date

可视化建议:

• 使用 Time series 面板
• Y 轴：rows_removed（左），bytes_removed（右，需转换为数字）

⚠️ 注意：bytes_removed 是字符串（如 “1.2 GB”），需用 sum(bytes_removed) 原始值绘图。

修改查询（用于绘图）:

SELECT
    event_date,
    sum(rows_removed) AS "Rows Removed",
    sum(bytes_removed) AS "Bytes Removed (Raw)"
FROM system.part_log
...
GROUP BY event_date

---

Panel 4：TTL 清理延迟分析

标题: TTL Cleanup Delay (Age at Removal)

查询:

SELECT
    event_date,
    avg(toUnixTimestamp(event_time) - toUnixTimestamp(modification_time)) AS avg_delay_seconds,
    quantile(0.95)(toUnixTimestamp(event_time) - toUnixTimestamp(modification_time)) AS p95_delay_seconds
FROM system.part_log
WHERE 
    event_type = 'RemovePart'
    AND part_name LIKE '%ttl%'
    AND event_date >= today() - INTERVAL 14 DAY
GROUP BY event_date
ORDER BY event_date

✅ 说明：计算“数据过期到被删除”的延迟（秒）

可视化建议:

• 使用 Time series 面板
• 展示 avg_delay_seconds 和 p95_delay_seconds

---

Panel 5：TTL 策略概览（可选）

标题: TTL Policies in Use

查询:

SELECT
    database,
    table,
    create_table_query
FROM system.tables
WHERE 
    create_table_query LIKE '%TTL%'
    AND database NOT IN ('system', 'information_schema')
LIMIT 50

可视化建议:

• 使用 Table 面板
• 显示建表语句中的 TTL 配置

---

📈 五、高级技巧

1. 添加变量（Variables）实现动态过滤

• 创建变量 $database、$table，支持下拉选择
• 在查询中使用 [[database]] 动态过滤

2. 设置告警（Alerting）

• 当 待清理数据量 > 100GB 时触发告警
• 当 平均清理延迟 > 24h 时通知运维

3. 使用 Annotation 显示重大变更

• 标记 ALTER TABLE ... TTL 操作时间点
• 便于分析策略变更影响

---

⚠️ 六、注意事项

问题	说明
system.part_log 不记录所有操作	只记录 Merge 相关事件
remove_time 是预估时间	实际删除时间取决于 Merge 任务
大表 OPTIMIZE FINAL 风险高	可能导致长时间锁表
TTL 清理依赖 merge_with_ttl_timeout	默认 1 天，可调小但影响性能

---

🎯 七、总结：Grafana + ClickHouse 监控 TTL 的核心价值

能力	说明
👁️ 可视化 TTL 状态	实时掌握哪些数据即将被清理
📉 验证 TTL 策略	确认 TTL 是否按预期工作
💾 评估存储优化	了解冷数据清理带来的成本节约
⏱️ 分析清理延迟	优化 merge_with_ttl_timeout 策略
🚨 主动告警	防止过期数据堆积导致磁盘满

🎯 这是 ClickHouse 数据治理的“透明之窗”：
让你不再“盲人摸象”，而是清晰掌控数据生命周期。