Graphite 语法参考手册
简介
Graphite 是一个开源的时序数据存储和可视化系统，采用层次化的指标命名方式和函数式查询语法。本文档汇总了 Graphite 的常见语法格式和基本参数含义，帮助开发者快速掌握 Graphite 查询语言。
指标路径语法
基本结构
Graphite 使用点分隔的层次结构来组织指标，格式如下：
<metric_path> = <node1>.<node2>.<node3>...<nodeN>
示例：
cluster.region.service.metric.submetric
路径节点
每个节点（node）可以是：
- 字母数字字符：
a-z,A-Z,0-9 - 连字符：
- - 下划线：
_
命名规范：
- 使用小写字母（推荐）
- 使用连字符分隔单词
- 保持层次结构清晰
通配符
单级通配符（*）
匹配单个路径节点中的任意字符。
示例：
cluster.*.service.metric
匹配
cluster.region1.service.metric、
cluster.region2.service.metric 等。
多级通配符（**）
匹配多个路径节点。
示例：
cluster.**.metric
匹配
cluster.region.service.metric、
cluster.region.service.subservice.metric 等。
字符类（Character Classes）
使用方括号 [] 定义字符类，匹配指定范围内的字符。
示例：
server[0-9].cpu.usage
匹配
server0.cpu.usage、
server1.cpu.usage 等。
函数语法
函数调用格式
Graphite 函数采用函数式语法，基本格式如下：
<function_name>(<argument1>, <argument2>, ...)
函数嵌套
函数支持嵌套调用，内层函数的返回值作为外层函数的参数：
<outer_function>(<inner_function>(<argument>))
示例：
sum(scale(metric.path, 0.1))函数链式调用
多个函数可以通过逗号分隔，形成链式调用：
<function1>(<function2>(<metric_path>))
示例：
aliasSub(sortByMaxima(groupByNodes(metric.path, 'sum', 14)), "(^.*$)", "\\1 B")
常用函数详解
数据聚合函数
方法 | 说明 | 语法 | 示例 |
|---|---|---|---|
sum() | 对多个指标进行求和 | sum(metric.path)sumSeries(metric.path1, metric.path2, ...) | sum(cluster.*.service.metric) |
average() | 计算多个指标的平均值 | average(metric.path)averageSeries(metric.path1, metric.path2, ...) | average(cluster.*.service.cpu.usage) |
max() | 获取最大值 | max(metric.path) | max(cluster.*.service.response_time) |
min() | 获取最小值 | min(metric.path) | min(cluster.*.service.response_time) |
groupByNodes() | 按指定节点分组聚合 | groupByNodes(metric.path, 'function', node_index1, node_index2, ...) 参数：metric.path（指标路径）、'function'（聚合函数，如 'sum', 'avg', 'max', 'min'）、node_index（节点索引，从 0 开始） | groupByNodes(cluster.*.service.*.metric, 'sum', 0, 2) 按第 0 个节点（cluster）和第 2 个节点（service）分组，对 metric 求和 |
数据转换函数
方法 | 说明 | 语法 | 示例 |
|---|---|---|---|
scale() | 数值缩放，将指标值乘以指定系数 | scale(metric.path, factor) | scale(metric.path, 0.1) 将指标值乘以 0.1 |
scaleToSeconds() | 将指标转换为每秒速率 | scaleToSeconds(metric.path, seconds) | scaleToSeconds(metric.path, 1) 将指标转换为每秒的速率 |
aliasSub() | 使用正则表达式重命名指标 | aliasSub(metric.path, pattern, replacement) 参数：pattern（正则表达式模式）、replacement（替换字符串，可使用 \1, \2 等引用捕获组） | aliasSub(metric.path, "(^.*$)", "\\1 B") 将指标名称替换为原名称加上 " B" 后缀 |
数据选择函数
方法 | 说明 | 语法 | 示例 |
|---|---|---|---|
sortByMaxima() | 按最大值排序 | sortByMaxima(metric.path) | sortByMaxima(cluster.*.service.metric) |
limit() | 限制返回的指标数量 | limit(metric.path, count) | limit(sortByMaxima(metric.path), 10) 返回按最大值排序后的前 10 个指标 |
时间函数
方法 | 说明 | 语法 | 示例 |
|---|---|---|---|
timeShift() | 将时间序列向前或向后移动指定时间 | timeShift(metric.path, shift) 参数：shift（时间偏移量，格式如 -1d 表示向前 1 天，+1h 表示向后 1 小时） | timeShift(metric.path, "-1d") 获取一天前的数据 |
条件函数
方法 | 说明 | 语法 | 示例 |
|---|---|---|---|
removeAboveValue() | 移除高于指定值的数据点 | removeAboveValue(metric.path, threshold) | removeAboveValue(metric.path, 100) 移除值大于 100 的数据点 |
removeBelowValue() | 移除低于指定值的数据点 | removeBelowValue(metric.path, threshold) | removeBelowValue(metric.path, 10) 移除值小于 10 的数据点 |
查询参数
Render API 参数
target（必需）
目标表达式，指定要查询的指标路径和函数。
格式：
target=<encoded_expression>
编码要求：
- 需要进行 URL 编码
- 单引号必须编码为
%27 - 空格编码为
%20或+
format（可选）
返回数据格式。
可选值：
json：JSON 格式（推荐）csv：CSV 格式png：PNG 图片格式
from（必需）
查询起始时间。
格式：
- Unix 时间戳（秒级）：
from=1609459200 - 相对时间：
from=-1h（1 小时前）、from=-7d（7 天前）
until（必需）
查询结束时间。
格式：
- Unix 时间戳（秒级）：
until=1609545600 - 相对时间：
until=now（当前时间）
maxDataPoints（可选）
最大数据点数限制。
格式：
maxDataPoints=1000当查询时间范围较大时，Graphite 会自动进行数据点采样，该参数控制返回的最大数据点数量。
最佳实践
1. 指标命名规范
推荐做法：
- 使用小写字母
- 使用点分隔的层次结构
- 保持命名一致性
- 避免使用特殊字符
示例：
cluster.region.service.metric.submetric
2. 函数组合
推荐做法：
- 先进行数据聚合，再进行转换
- 合理使用函数嵌套，避免过度复杂
- 使用别名函数提高可读性
示例：
aliasSub( sortByMaxima( groupByNodes( scaleToSeconds(metric.path, 1), 'sum', 14 ) ), "(^.*$)", "\\1 B")
3. 性能优化
推荐做法：
- 使用
maxDataPoints限制数据点数量 - 合理设置查询时间范围
- 使用通配符时注意性能影响
- 避免过于复杂的函数嵌套
4. 错误处理
常见问题：
- 指标路径不存在：返回空数据
- 函数参数错误：返回错误信息
- 时间范围无效：返回空数据
处理建议：
- 验证指标路径是否存在
- 检查函数参数格式
- 设置合理的时间范围
5. 变量替换
在实际应用中，Target 表达式通常包含变量占位符，需要在查询前进行替换。
常见变量：
$service：服务名称$tpx：百分位值（如 p80, p95, p99）$region：区域标识
替换示例：
原始表达式：span.$service.metric.$tpx
替换后：span.$service_name.metric.$percentile_value
总结
本文档汇总了 Graphite 的常见语法格式和基本参数含义，包括：
- 指标路径语法：层次化命名、通配符、字符类
- 函数语法：函数调用、嵌套、链式调用
- 常用函数：聚合函数、转换函数、选择函数、时间函数、条件函数
- 查询参数：Render API 的参数说明
- 最佳实践：命名规范、函数组合、性能优化、错误处理、变量替换
掌握这些语法和参数，可以帮助开发者更高效地使用 Graphite 进行时序数据查询和分析。
本文参与 腾讯云自媒体同步曝光计划，分享自微信公众号。
原始发表：2025-12-08，如有侵权请联系 cloudcommunity@tencent.com 删除
评论
登录后参与评论
推荐阅读
目录
腾讯云开发者
