功能介绍:
从OPENTSDB数据库中查询数据。
一、请求参数:
表1:请求参数说明
名称 |
数据类型 |
|
必填 |
描述 |
缺省 |
Query String |
示例 |
start |
String, Integer |
|
必填 |
起始时间。查询结果包含该时间的值。时间格式请参见“时间格式说明” |
|
start |
1h-ago |
end |
String, Integer |
|
可选 |
结束时间,默认值为LEAP TSDB的当前系统时间。查询结果包含该时间的值。 |
now |
end |
1s-ago |
queries |
Array |
|
必填 |
子查询,可以有多个。详情参见表2子查询 |
|
m |
|
msResolution |
Boolean |
|
可选 |
默认情况下,查询结果中的时间戳是以秒为单位的。如果设置为true,则查询结果中的时间戳以毫秒为单位 |
false |
msResolution |
true |
showSummary |
Boolean |
|
可选 |
查询结果是否显示汇总信息 |
false |
show_summary |
true |
showStats |
Boolean |
|
可选 |
查询结果是否显示详细信息 |
false |
show_stats |
true |
showQuery |
Boolean |
|
可选 |
查询结果是否返回原始子查询。如果查询请求包含多个子查询,使用此选项可用以判断各个结果集对应的子查询。 注意: 如果子查询中使用了通配符*,结果集中会产生大量重复结果。 |
false |
show_query |
true |
useCalendar |
Boolean |
|
可选 |
Downsampling计算时是否使用时区日历。必须是JRE可以识别的时区名称。 |
false |
|
true |
timezone |
String |
|
可选 |
Downsampling计算时所使用的时区日历(如果使用的话) |
UTC |
timezone |
Asia/Kabul |
表2:子查询
名称 |
数据类型 |
必填 |
描述 |
缺省 |
示例 |
|
aggregator |
String |
必填 |
|
|
sum |
|
metric |
String |
必填 |
指标项 |
|
sys.cpu.0 |
|
rate |
Boolean |
可选 |
是否返回变化率 |
false |
true |
|
rateOptions |
Map |
可选 |
计算变化率时可以使用的额外参数 |
|
|
|
downsample |
String |
可选 |
降低时间精度采样。详情见“downsample说明” |
|
5m-avg |
|
filters |
List |
可选 |
filter 根据 tags 对结果进行过滤,可以设置多个过滤器,详情见“Filter参数说明” |
|
|
|
explicitTags |
Boolean |
可选 |
是否只返回包含且只包含filter指定的tags的时序。 例如: 若数据库中有两个时序数据,其中时序1包含3个tags = { tag1,tag2,tag3 },时序2包含4个tags = { tag1,tag2,tag3,tag4 }。 当explicitTags=true后,若filter中指定了tag1,tag2,tag3的条件,则结果仅返回时序1;若filter中仅指定了tag1,tag2,则结果中不包含。 精确指定tags可有效提高查询效率。 |
false |
true |
|
percentiles |
List |
可选 |
返回数据的百分位数,输入参数为0-100的数值。 输入多个数值可同时返回多个百分位数。 |
|
[99.9, 95.0, 75.0] |
|
二、时间格式说明:
1、相对时间格式:
<amount><time unit>-ago
<amount> 表示时间值,<time unit>表示时间单位。比如1h-ago表示从现在开始的一小时之前。时间单位包括:
- ms - Milliseconds
- s - Seconds
- m - Minutes
- h - Hours
- d - Days (24 hours)
- w - Weeks (7 days)
- n - Months (30 days)
- y - Years (365 days)
2、绝对Unix时间格式:
Unix 格式的时间戳。比如1364410924表示 ISO 8601:2013-03-27T19:02:04Z。
3、绝对格式化时间:
支持以下格式的时间:
- yyyy/MM/dd-HH:mm:ss
- yyyy/MM/dd HH:mm:ss
- yyyy/MM/dd-HH:mm
- yyyy/MM/dd HH:mm
- yyyy/MM/dd
三、Aggregator说明:
Aggregator可在聚合多个时序和降低采样downsampling时使用,通过算子将多个数据点汇聚成一个数据点。
聚合算子请参见下表:
算子 |
描述 |
补值方式 |
avg |
平均值 |
线性插值 |
count |
数据点数 |
补0 |
dev |
计算标准偏差 |
线性插值 |
ep50r3 |
用R-3方法计算的第50百分位 |
线性插值 |
ep50r7 |
用R-7方法计算的第70百分位 |
线性插值 |
ep75r3 |
用R-3方法计算的第75百分位 |
线性插值 |
ep75r7 |
用R-7方法计算的第75百分位 |
线性插值 |
ep90r3 |
用R-3方法计算的第90百分位 |
线性插值 |
ep90r7 |
用R-7方法计算的第90百分位 |
线性插值 |
ep95r3 |
用R-3方法计算的第95百分位 |
线性插值 |
ep95r7 |
用R-7方法计算的第95百分位 |
线性插值 |
ep99r3 |
用R-3方法计算的第99百分位 |
线性插值 |
ep99r7 |
用R-7方法计算的第99百分位 |
线性插值 |
ep999r3 |
用R-3方法计算的第99.9百分位 |
线性插值 |
ep999r7 |
用R-7方法计算的第99.9百分位 |
线性插值 |
first |
取第一个值 |
- |
last |
取最后一个值 |
- |
mimmin |
最小值 |
补最大值 |
mimmax |
最大值 |
补最小值 |
min |
最小值 |
线性插值 |
max |
最大值 |
线性插值 |
none |
不做计算 |
补0 |
p50 |
第50百分位 |
线性插值 |
p75 |
第75百分位 |
线性插值 |
p90 |
第90百分位 |
线性插值 |
p95 |
第95百分位 |
线性插值 |
p99 |
第99百分位 |
线性插值 |
p999 |
第99.9百分位 |
线性插值 |
sum |
求和 |
线性插值 |
zimsum |
求和 |
补0 |
四、Downsample说明:
当查询的时间跨度很大,例如每秒都将温度作为数据写入LEAP TSDB,每个小时会产生3600条数据点,当查询一周的数据时,会返回604800个数据点。展示如此多数据会显得很乱,通常也不需要这样精确的数据。使用降精度的方式将一段时间的数据点聚合后当作一个数据点,比如将每个小时的数据聚合为1个数据点,这样就会只显示168个数据点。
格式:
<Interval><units>-<aggregator>[c][-<fill policy>]
-
- Interval:时间数值。unit:时间单位,s秒,m分,h小时,d天。
- aggregator:聚合策略。将一段时间内的数据点集聚合为一个数据点的策略。具体取值请参见“聚合算子”。
- c:表示使用时区日历采样,可选项。此参数需要和timezone 参数配合使用,例如:&timezone=Asia/Kabul
- fill policy:补值策略,可选项。当使用aggreator计算一段时间内的聚合值时,遇到中间缺少的数据点时,会使用一定的策略补充数据。补值策略如下表所示。
名称 |
描述 |
none |
默认,不补值 |
nan |
补NaN |
null |
补null |
zero |
补0 |
1h-sum
30m-avg-nan
24h-max-zero
1dc-sum
0all-sum
五、Filter参数说明:
名称 |
类型 |
必填 |
描述 |
示例 |
type |
String |
是 |
filter类型,参见下表 |
regexp |
tagk |
String |
是 |
要做filter的tag名 |
host |
filter |
String |
是 |
filter的表达式值 |
web[0-9]+.lax.mysite.com |
groupBy |
Boolean |
否 |
是否对tagv做groupBy,默认false |
false |
六、Filter类型:
名称 |
说明 |
示例 |
literal_or |
tagv等于或者等于 |
host=literal_or(web01|web02|web03) |
ilteral_or |
tagv等于或者等于; 大小写敏感 |
|
not_literal_or |
tagv不等于或者不等于 |
host=not_literal_or(web01|web02|web03) |
not_iliteral_or |
tagv不等于或者不等于; 大小写敏感 |
|
wildcard |
tagv需满足的通配符 |
host=wildcard(*mysite.com) |
iwildcard |
与wildcard作用相反 |
host=iwildcard (*mysite.com) |
regexp |
tagv需满足正则表达式 |
regexp(web[0-9].mysite.com) |
七、Filter的Query String格式:
<tagk>=<type>(<filter_expression>)
例如:{host=wildcard(web*)}
结果集是否group取决于filter在哪个大括号里面,query string里可以有两个大括号,第一个是group filter,第二个是non-group filter。比如: {host=wildcard(web*)}{colo=regexp(sjc.*)}表示该filter需要分组;如果只需要non-group filter,第一个大括号必须置空,比如:{}{host=wildcard(web*),colo=regexp(sjc.*)}表示该filter不分组。
八、Query String查询格式:
当使用GET方式查询时,Query String的完整格式如下:
m=<aggregator>:[rate[{counter[,<counter_max>[,<reset_value>]]]}:][<down_sampler>:][percentiles\[<p1>, <pn>\]:][explicit_tags:]<metric_name>[{<tag_name1>=<grouping_filter>[,...<tag_nameN>=<grouping_filter>]}][{<tag_name1>=<non_grouping filter>[,...<tag_nameN>=<non_grouping_filter>]}]
参见示例
以便于理解。