宏是什么
面板查询里的时间宏由 Grafana 按当前时间范围与面板宽度实时计算，写进查询后在每次刷新时替换成具体数值。使用宏可以让同一条表达式在不同时间范围下都保持合理的数据点数，而不必为每个时间范围各写一份查询。
两个窗口宏的区别
步长宏表示当前每个数据点覆盖的时间长度，随面板宽度与时间范围变化；速率窗口宏则在此基础上保证窗口足够大，官方定义取步长加一个采集间隔，与采集间隔四倍中的较大值。前者用于普通聚合，后者专供速率类函数使用。
为什么推荐自适应窗口
把窗口写死会带来两种问题：时间范围拉大后窗口小于步长，速率对不上采样密度；时间范围缩小后窗口又远大于步长，曲线被过度平滑。自适应窗口把这件事交给看板处理，是官方推荐的写法。
基本信息
| 作用 | 按时间范围与面板宽度动态生成数值 |
|---|---|
| 替换时机 | 查询执行时由看板替换 |
| 速率窗口前提 | 数据源配置里的采集间隔必须填写准确 |
| 常用位置 | 窗口函数参数、聚合窗口、时间过滤条件 |
典型使用场景
- 速率查询：让不同时间范围下都使用合理窗口
- 聚合窗口：按步长自动确定聚合粒度
- 日志统计：用自动步长控制返回的数据点数量
- 时间过滤：在关系型数据库查询里按看板时间范围筛选
- 对外联动：把起止时间戳传给外部系统做对账
- 模板复用：一份查询适配任意时间范围
推荐写法
推荐写法
# 速率类查询使用自适应窗口
rate(http_requests_total[$__rate_interval])
# 普通聚合使用步长
avg_over_time(node_memory_MemAvailable_bytes[$__interval])
# 需要数值参数或整段范围时
$__interval_ms # 步长对应的毫秒数
$__range # 当前时间范围，如 6h
$__from / $__to # 起止毫秒时间戳常用宏
| 宏 | 含义 | 常见用途 |
|---|---|---|
| $__interval | 面板当前步长 | 普通聚合的窗口 |
| $__interval_ms | 步长的毫秒数 | 需要数值参数的场景 |
| $__rate_interval | 自适应速率窗口 | 速率函数的窗口 |
| $__range | 时间范围文本 | 需要整段范围的参数 |
| $__from 与 $__to | 起止毫秒时间戳 | 与外部系统对时间 |
| $__auto | 按数据点数量划分步长 | 日志类查询的常用选择 |
常见写法对比
| 写法 | 问题 | 改进 |
|---|---|---|
| 写死固定窗口 | 时间范围拉大后曲线稀疏 | 改用自适应窗口宏 |
| 窗口小于步长 | 速率对不上采样密度，曲线失真 | 交给速率窗口宏 |
| 各面板宏不统一 | 同一指标在不同面板形状不同 | 统一模板与宏用法 |
使用要点
- 速率函数优先用速率窗口宏，其他聚合用步长宏
- 数据源里的采集间隔填错会让速率窗口整体偏移
- 把宏写进面板模板，新面板继承同一套写法
- 导出看板前检查是否残留写死的窗口参数
宏只在看板与探索区查询中生效：直接调用后端查询接口时需要自己给出时间参数，两者的窗口口径要事先对齐。
把速率窗口宏用在非速率函数上会让窗口含义错位：它表达的是窗口长度而不是速率，混用时容易得到意料之外的分母。
建看板时先定宏的用法再填表达式：面板一旦大量复制，统一改写的成本会随时间迅速上升。
面板时间范围与自动刷新频率要一起考虑：刷新很快而范围很长时，每次刷新都是一次重查询，后端压力会明显上升。