请求路径 | 请求方法 | 描述 |
---|---|---|
/api/query | POST | 查询数据 |
名字 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
start | Long | 是 | 开始时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。 | 无 | 1499158925 |
end | Long | 否 | 结束时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。默认值为 TSDB 服务器当前时间。 | 当前时间 | 1499162916 |
queries | Array | 是 | 子查询数组 | 无 | 见子查询说明 |
msResolution | boolean | 否 | 子查询数组 | false | 该参数只对原始数据单位是秒的查询生效;当该参数设置为 true 时,查询结果中的时间戳会转换为毫秒,否则仍保留原始时间单位;对于原始数据是毫秒的查询,返回结果中时间戳始终为毫秒。 |
hint | Map | 否 | 查询 Hint 化 | 无 | 见查询 Hint 化说明 |
时间戳的单位可以是秒或者毫秒。TSDB 会通过数值大小来判断时间戳的单位,规则如下:
说明:适用于写入数据 (/api/put
) 和查询数据 (api/query
) 两个接口。
TSDB 支持单时间点数据查询。您可以将开始时间和结束时间设置为相同的数值。例如,"start":1356998400
,"end":1356998400
。
名称 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
aggregator | String | 是 | 聚合函数,详见下面的聚合(Aggregate)说明。 | 无 | sum |
metric | String | 是 | 指标名 | 无 | sys.cpu0 |
rate | Boolean | 否 | 是否计算指定指标值的增长速率;计算公式: Vt-Vt-1/t1-t-1 | false | true |
delta | Boolean | 否 | 是否计算指定指标值的差值; 计算公式: Vt-Vt-1 | false | true |
limit | Integer | 否 | 数据分页,子查询返回数据点的最大数目 | 0 | 1000 |
offset | Integer | 否 | 数据分页,子查询返回数据点的偏移量 | 0 | 500 |
dpValue | String | 否 | 根据提供条件过滤返回数据点,支持”>”, “<”, “=”,”<=”, “>=”, “!=”。 | 无 | >=1000 |
preDpValue | String | 否 | 根据提供的条件在扫描原始数据点时进行过滤,支持”>”, “<”, “=”,”<=”, “>=”, “!=”。 注意:它与“dpValue”的不同在于前者是对查询完成后计算的结果进行值过滤;后者是在存储的数据点进行扫描时进行值过滤,使得不满足过滤条件的数据点根本不会加入查询计算。 |
无 | >=1000 |
downsample | String | 否 | 时间维度降采样 | 无 | 60m-avg |
tags | Map | 否 | 指定标签过滤,和filters冲突 | 无 | - |
filters | List | 否 | 过滤器,和tags冲突 | 无 | - |
hint | Map | 否 | 查询 Hint 化 | 无 | 见查询 Hint 化说明 |
forecasting | String | 否 | 数据预测 | 无 | 见查询 forecasting 说明 |
abnormaldetect | String | 否 | 数据预测 | 无 | 见查询 abnormaldetect 说明 |
说明:
请求: POST/api/query
请求体:
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0"
},
{
"aggregator": "sum",
"metric": "sys.cpu.1"
}
]
}
Limit::子查询返回数据点的最大数目。默认值是 0,代表不限制返回点数量。
Offset: 子查询返回数据点的偏移量。默认值也是 0,代表不偏移返回的数据点。
注意:limit 和 offset 不能为负数。
返回第 1001 到 1500 的数据点,则 limit 设为 500,offset 设为 1000。
{
"start":1346046400,
"end":1347056500,
"queries":[
{
"aggregator":"avg",
"downsample":"2s-sum",
"metric":"sys.cpu.0",
"limit":"500",
"offset":"1000",
"tags":{
"host":"localhost",
"appName":"hitsdb"
}
}
]
}
根据用户设置的数值限制条件,过滤最终的返回数据点。支持 “>”, “<”, “=”, “<=”, “>=”, “!=”。
{
"start":1346046400,
"end":1347056500,
"queries":[
{
"aggregator":"avg",
"downsample":"2s-sum",
"metric":"sys.cpu.0",
"dpValue":">=500",
"tags":{
"host":"localhost",
"appName":"hitsdb"
}
}
]
}
当用户在子查询中指定差值算子的时候,TSDB返回的数据的”dps”中的key-value对的value值将是计算所得的差值。需要注意的是,如果未指定差值时返回的”dps”中有 n 个key-value对,那么计算完差值后返回的”dps”中将只包含 n-1 个key-value对(第一个key-value对因无法求差值将被舍去)。差值算子对于Downsample后的值也同样适用。
此外,用户指定了差值算子时,还可以进一步在子查询中指定 “deltaOptions” 来对求差值的行为进行进一步控制。当前支持的 “deltaOptions” 如下所示:
名称 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
counter | Boolean | 否 | 当该标记位被指定时则表示假定用于计算差值的指标值被用户视作是一个类似计数器的单调递增(或递减)的累计值(但服务器并不会加以check) | false | true |
counterMax | Integer | 否 | 当counter被设置为true时, 该值用于指定差值的阈值。当差值的绝对值超过该阈值时将被视作异常值;该值不指定时则对差值不设阈值 | 无 | 100 |
dropReset | Boolean | 否 | 该标记位需要与上述 counterMax 结合使用。当通过指定counterMax 后计算出了异常的差值,dropReset决定是否要直接丢弃异常的差值。若指定为true,则异常值直接被丢弃;若指定为false(默认情况),则异常值被重置为零 | false | true |
{
"start":1346046400,
"end":1347056500,
"queries":[
{
"aggregator":"none",
"downsample":"5s-avg",
"delta":true,
"deltaOptions":{
"counter":true,
"counterMax":100
}
"metric":"sys.cpu.0",
"dpValue":">=50",
"tags":{
"host":"localhost",
"appName":"hitsdb"
}
}
]
}
当查询的时间范围比较长,只需返回一定精度的数据时使用。查询格式如下:
<interval><units>-<aggregator>[-fill policy]
该查询格式可称作降采样表达式
其中:
interval:指数值,如 5、60 等,特殊的“0all”表示时间维度聚合为一个点。
units:s 代表秒,m 代表分,h 代表小时,d 代表天,n 代表月,y 代表年。
说明:支持基于日历时间间隔的降采样。要使用日历界限,您需要在时间单位 units 后添加一个c
。例如,1dc
代表从当日零点到次日零点之间的 24 小时。
aggregator:降采样使用的算子及其说明如下表所示。
算子 | 描述 |
---|---|
avg | 平均值 |
count | 数据点数 |
first | 取第一个值 |
last | 取最后一个值 |
min | 最小值 |
max | 最大值 |
median | 求中位数 |
sum | 求和 |
zimsum | 求和 |
rfirst | 功能同first 但降采样后返回的结果的时间戳是原始数据的时间戳; 而非降采样对齐后的时间戳 |
rlast | 功能同last 但降采样后返回的结果的时间戳是原始数据的时间戳; 而非降采样对齐后的时间戳 |
rmin | 功能同min 但降采样后返回的结果的时间戳是原始数据的时间戳; 而非降采样对齐后的时间戳 |
rmax | 功能同max 但降采样后返回的结果的时间戳是原始数据的时间戳; 而非降采样对齐后的时间戳 |
说明:
Fill policy 即填值。降采样先把所有时间线按照指定精度切分,并把每个降采样区间内的数据做一次运算,降采样后如果某个精度区间没有值,fill policy 可以指定在这个时间点填充具体的值。比如某条时间线降采样后的时间戳为:t+0, t+20, t+30,此时如果不指定 fill policy,只有 3 个值,如果指定了 fill policy 为 null,此时间线会有 4 个值,其中 t+10 时刻的值为 null。
Fill policy 与具体填充值的对应如下表所示。
Fill Policy | 填充值 |
---|---|
none | 默认行为,不填值 |
nan | NaN |
null | null |
zero | 0 |
linear | 线性填充值 |
previous | 之前的一个值 |
near | 邻近的一个值 |
after | 之后的一个值 |
fixed | 用指定的一个固定填充值(请参照下面示例) |
Fixed Fill Policy
使用方法:将固定的填充值写到 “#”之后。填充值支持正负数。格式如下:
<interval><units>-<aggregator>-fixed#<number>
示例:1h-sum-fixed#6, 1h-avg-fixed#-8
示例:1m-avg,1h-sum-zero,1h-sum-near
注意:查询时,downsample 不是必要条款。您甚至可以在查询时明确标明其值为 null 或者空(””),例如:{“downsample”: null} 或者 {“downsample”: “”},这样就不会触发数据点降采样。
在降采样后会得到多条时间线的值,并且这些时间线的时间戳是对齐的,而聚合就是把多条时间线的值按各个对齐时刻聚合为一条时间线的结果(注意:如果只有一条时间线,则不进行聚合)。聚合时必须要求每条时间线在对应时刻都有值,如果某条时间线在某个时刻没有值,则会进行插值,插值描述如下。
插值
如果某条时间线某个精度区间没有值且没有使用 fill policy 进行填值,而待聚合的其他时间线中有一条时间线在此精度区间有值,则会对本时间线的这个缺值精度区间进行插值。
例如:降采样以及聚合条件为{“downsample”: “10s-avg”, “aggregator”: “sum”} ,有两条时间线需要使用 sum 聚合,按 10s-avg 做降采样后的这两条时间线有值的时间戳分别为:
line 1: t+0, t+10, t+20, t+30
line 2: t+0, t+20, t+30
第二条时间线 line 2 缺 “t+10” 这个时刻的值,那么在聚合前会对 line 2 的 “t+10” 这个时间点进行插值。插值的方法与聚合的算子有关,详见下面的算子列表。
算子 | 描述 | 插值方法 |
---|---|---|
avg | 平均值 | 线性插值(斜率拟合) |
count | 数据点数 | 插 0 |
mimmin | 最小值 | 插最大值 |
mimmax | 最大值 | 插最小值 |
min | 最小值 | 线性插值 |
max | 最大值 | 线性插值 |
none | 不做计算 | 插 0 |
sum | 求和 | 线性插值 |
zimsum | 求和 | 插 0 |
有以下两种方法可以指定 filter:
在指定 tagk 时指定 filter:
tagk = *:对 tagk 下面的 tagv 做 groupBy,相同的 tagv 做聚合。
tagk = tagv1|tagv2: 分别对 tagk 下面的 tagv1 和 tagv2 数据做聚合。
名字 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
type | String | 是 | filter 类型,详见下面说明 | 无 | literal_or |
tagk | String | 是 | 指定 tagk 名 | 无 | host |
filter | String | 是 | filter 表达式 | 无 | web01丨web02 |
groupBy | Boolean | 否 | 是否对 tagv 做 groupBy | false | false |
名称 | filter 举例 | 描述 |
---|---|---|
literal_or | web01丨 web02 | 分别对多个 tagv 做聚合,区分大小写 |
wildcard | *mysite.com | 分别对满足通配符的 tagv 做聚合,区分大小写 |
请求体:
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"tags": {
"host": "*",
"dc": "lga"
}
}
]
}
请求体:
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"filters": [
{
"type": "wildcard",
"tagk": "host",
"filter": "*",
"groupBy": true
},
{
"type": "literal_or",
"tagk": "dc",
"filter": "lga|lga1|lga2",
"groupBy": false
}
]
}
]
}
查询成功的 HTTP 响应码为 200,响应内容为 JSON 格式数据。说明如下:
名称 | 描述 |
---|---|
metric | 指标名 |
tags | tagv 未做聚合的 tag |
aggregateTags | tagv 做了聚合的 tag |
dps | 数据点对 |
响应结果示例:
[
{
"metric": "tsd.hbase.puts",
"tags": {"appName": "hitsdb"},
"aggregateTags": [
"host"
],
"dps": {
"1365966001": 25595461080,
"1365966061": 25595542522,
"1365966062": 25595543979,
"1365973801": 25717417859
}
}
]
该特性主要是提高查询速度。假设某一个 tags A 命中的时间线明显大于其他的 tags B 命中的时间线,则需要舍弃,避免捞取 tags A 的大量时间线之后,被 tagsB 小规模时间线交集后,结果集等于 tagsB。
0
表示不使用对应 tagk 的索引,反之 1
表示使用对应 tagk 的索引从 v2.6.1 版本开始支持 hint 特性
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
},
"hint": {
"tagk": {
"dc": 1
}
}
}
]
}
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1
}
}
}
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1,
"host": 0
}
}
}
会返回如下报错信息:
{
"error": {
"code": 400,
"message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 100
}
}
}
会返回如下报错信息:
{
"error": {
"code": 400,
"message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
根据时间序列已有数据作为训练集,通过AI算法发现数据趋势和周期,从而预测该时间序列在未来一段时间的数据点。查询格式如下:
<AlgorithmName>-<ForecastPointCount>[-<ForecastPolicy>]
其中:
ForecastPolicy: 预测策略。 算法不同代表含义也不同。
当AlgorithmName 是arima时,ForecastPolicy格式如下:
Delta-Seasonality
当AlgorithmName 是holtwinters时,ForecastPolicy格式如下:
Seasonality
示例: arima-1,arima-48-1-48,holtwinters-1-1
假设数据是
[
{
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web00"
},
"aggregateTags": [],
"dps": {
"1346837400": 1,
"1346837401": 2,
"1346837402": 3,
"1346837403": 4,
"1346837404": 5,
"1346837405": 6,
"1346837406": 7,
"1346837407": 8,
"1346837408": 9,
"1346837409": 10,
"1346837410": 11,
"1346837411": 12
}
}
]
查询
{
"start":1346837400,
"end": 1346847400,
"queries":[
{
"aggregator":"none",
"metric":"sys.cpu.nice",
"forecasting" : "arima-1"
}
]
}
[
{
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web00"
},
"aggregateTags": [],
"dps": {
"1346837400": 1,
"1346837401": 2,
"1346837402": 3,
"1346837403": 4,
"1346837404": 5,
"1346837405": 6,
"1346837406": 7,
"1346837407": 8,
"1346837408": 9,
"1346837409": 10,
"1346837410": 11,
"1346837411": 12,
"1346837412": 13
}
}
]
根据时间序列已有数据作为训练集,通过AI算法发现数据趋势和周期,从而预测该时间序列在未来一段时间的数据点。查询格式如下:
<AlgorithmName>[-<Sigma>-<NP>-<NS>-<NT>-<NL>]
目前异常检测只支持一种算法:stl 方法。对于参数调参不太了解的建议选择默认参数。如果用户对STL算法比较熟悉,可以通过额外调参获得更好的预测结果。异常检测的完整参数有6个,分别是 “AlgorithmName-Sigma-NP-NS-NT-NL” 示例如下 “stl-5-5-7-0-0”,参数通过‘-’ 分隔。每个参数代表的含义如下:
示例1:
“abnormaldetect”: “stl”,
示例2:
“abnormaldetect”: “stl-5-5-7-0-0”,
{
"start":1346836400,
"end":1346946400,
"queries":[
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"abnormaldetect": "stl-5-5-7-0-0",
"filters": [
{
"type": "literal_or",
"tagk": "dc",
"filter": "lga",
"groupBy": false
},
{
"type": "literal_or",
"tagk": "host",
"filter": "web00",
"groupBy": false
}
]
}
]
}
TSDB的异常检测输出的是一个链表, 该链表layout固定,格式如下
[srcValue, upperValue, lowerValue, predictValue, isAbnormal]
[
{
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web00"
},
"aggregateTags": [],
"dps": {
"1346837400": [
1,
1.0000000000000049,
0.9999999999999973,
1.0000000000000013,
0
],
"1346837401": [
2,
2.0000000000000036,
1.9999999999999958,
1.9999999999999998,
0
],
"1346837402": [
3,
3.0000000000000036,
2.9999999999999956,
3,
0
],
"1346837403": [
4,
4.0000000000000036,
3.9999999999999956,
4,
1
],
"1346837404": [
5,
5.0000000000000036,
4.9999999999999964,
5,
0
],
"1346837405": [
6,
6.000000000000002,
5.999999999999995,
5.999999999999998,
0
],
"1346837406": [
7,
7.0000000000000036,
6.9999999999999964,
7,
1
],
"1346837407": [
8,
8.000000000000004,
7.9999999999999964,
8,
0
],
"1346837408": [
9,
9.000000000000004,
8.999999999999996,
9,
0
],
"1346837409": [
10,
10.000000000000004,
9.999999999999996,
10,
0
],
"1346837410": [
11,
11.000000000000005,
10.999999999999998,
11.000000000000002,
0
],
"1346837411": [
12,
12.000000000000004,
11.999999999999996,
12,
0
]
}
}
]
在文档使用中是否遇到以下问题
更多建议
匿名提交