query
query
/api/query
Method
GET, POST, DELETE
请求参数
Name | Data Type | Required | Description | QS | Default | Example |
---|---|---|---|---|---|---|
start | String, Integer | Required | query操作的起始时间,可以是相对或者绝对时间戳。 | start | 1h-ago | |
end | String, Integer | Optional | query操作的终止时间戳,如果没有提供的话,那么tsd就会把本地系统的时间戳作为这个时间戳,可以是相对的或者绝对时间戳。 | end | 执行操作的tsd的server当前时间 | 1s-ago |
queries | Array | Required | 一个或者多个子query,用来选择返回的时序数据。这些可以是metric m或者是TSUID tsuid的query。 | m or tsuids | 见下面 | |
noAnnotations | Boolean | Optional | 是否返回一次query的注释,默认是返回请求的时间跨度的注释,但是这个flag 可以让本次返回没有注释信息,这个影响着本地以及全局的注释以及override。 globalAnnotations |
no_annotations | false | false |
globalAnnotations | Boolean | Optional | 是否应该取回这次时间跨度的全局注释 | global_annotations | false | true |
msResolution (or ms) | Boolean | Optional | 是否把输出的datapoint的时间戳以毫秒或者秒表示。这个falg是建议被设置的,如果这个flag没有被提供那么将会一秒内有多个datapoiont。这些datapoint会在down sampled的时候使用query的aggregation功能. | ms | false | true |
showTSUIDs | Boolean | Optional | 是否对输出的TSUID关联时序信息。如果多个时序信息被aggregated成一个set集合,多个TSUID将以一个排序的形式返回。 | show_tsuids | false | true |
showSummary (2.2) | Boolean | Optional | 是否在query结果中展示timing(时序query结果)的summary信息。如果设置这个flag的话,将会在map中创建一个新的object,和datapoint object不一样。 | show_summary | false | true |
showStats (2.2) | Boolean | Optional | 是否在query结果中展示详细的timing信息。这个flag被设置的话,将会在map中创建一个object,和datapoint的object不一样。 | show_stats | false | true |
showQuery (2.2) | Boolean | Optional | 是否在结果中返回最初的sub query。如果请求包括了多个sub query的话,那么这个flag设置的话,可以显示的告诉我们哪个结果属于哪个sub query .注意下,在这种情况下 *或者是 通配符的query,可以引起许多重复的结果输出。 | show_query | false | true |
delete | Boolean | Optional | 可以带着post传递给json,用于删除任意满足query的datapoint。 | false | true | |
timezone (2.3) | String | Optional | 可以选择的时区,用在基于日历下的downsampling。必须是一个有效的且是TSD server上安装的JRE支持的时区数据集名字。 | timezone | UTC | Asia/Kabul |
useCalendar (2.3) | Boolean | Optional | 是否使用给定时区的日历来做downsampling间隔操作 | false | true |
Sub query
有2中sub query 分别是metric query 和 tsuid query,sub query 包括下面:
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
aggregator | String | Required | 使用的aggregator函数名字. 可以通过请求 /api/aggregators 获得 | sum | |
metric | String | Required | 系统存储的metric名字 | sys.cpu.0 | |
rate | Boolean | Optional | 数据在返回前是否需要转换为deltas. 如果metric是持续的增长型的counter计数,且你想看 data points间的数据变化率. | false | true |
rateOptions | Map | Optional | 单调的递增计数处理选项 | See below | See below |
downsample | String | Optional | 一个可选的downsampling 函数,用来降低数据返回的数量。 | See below | 5m-avg |
tags | Map | Optional | 深入研究特殊的时序序列或者按tag归类的组结果,支持一个或多个map values以一个格式作为query 字符串。tag 在2.2版本被转为filter。如果没tag被设置,所有的metric都会被aggregated到这个结果。2.2 版本被 Deprecated | See Below | |
explicitTags (2.3) | Boolean | Optional | 返回只包括tag key的序列 | false | true |
Rate Options
当在一个query语句 里面添加了rate 选项,这个选项必须围绕大括号,比如: m=sum:rate{counter,,1000}:if.octets.in
. 如果你想用counterMax但是不希望提供resetValue,那么你需要在刚才的例子里面那样添加2个逗号,一些附加的rateOption如下:
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
counter | Boolean | Optional | 这个潜在的数据是否是一个单调递增的计数,且可以翻转(roll over) | false | true |
counterMax | Integer | Optional | 这是一个正数,表示counter的最大值 | Java Long.MaxValue | 65535 |
resetValue | Integer | Optional | 一个可选的值,当超过了value的范围,将导致aggregator变为0,当data soure频繁性的置位虚假高峰(spurious spikes)时,这个选项是很有用的。 | 0 | 65000 |
dropResets | Boolean | Optional | 是否简单的翻折(drop rolled-over),或者直接重置data point | false | true |
filter
2.2版本以后opentsdb支持在key 和value tag组合上的可扩展的、插件化的filter。filter 可以用于query 字符串以及post字符串。多个filter是支持的,且在执行的过程中,当在一个tag key上执行,会有and的组合效应。如果我们提出filter: host=literal_or(web01)
和host=literal_or(web02),
那么我们得到的结果可能是空。如果一个或者多个filter在一个tag key上执行,且其中一个有group by的作用,别的没有,那么 group by 将是为造成所有的filter在这个tag key上变成有效的true,filters包括下面:
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
type | String | Required | filter 调用的名字 | regexp | |
tagk | String | Required | tag key 用于调用这个filter | host | |
filter | String | Required | filter的表达式,依赖这个表达式的具体意义进行filter | web.*.mysite.com | |
groupBy | Boolean | Optional | 是否group这个结果以匹配这个filter。默认的话,所有的匹配这个filter的值将会aggregated成为一个时序 。 | false | true |
请求体
Metric Query 字符串格式:
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>]}]
TSUID Query 字符串格式:
tsuid=<aggregator>:<tsuid1>[,...<tsuidN>]
example 存储文件file叫做query.json:
1.简单:start,queries(metric,aggregator)
{
"start":"48h-ago",
"queries":[
{
"metric": "sys.cpu.nice",
"aggregator":"avg"
}
]
}
2.带有filter on a tag;
{
"start":"48h-ago",
"queries":[
{
"metric": "sys.cpu.nice",
"aggregator":"avg",
"tags":{
"dc":"lga"
}
}
]
}
3.如果需要某一个特定的时序数据,需要把tag信息都具体化
{
"start":"48h-ago",
"queries":[
{
"metric": "sys.cpu.nice",
"aggregator":"avg",
"tags":{
"host": "web02",
"dc": "lga"
}
}
]
}
4.grouping+ filter操作,例子中统一的web01做sum操作;通过通配符*以及host=web01限制得出素有
web01的,但是所有dc的机器48小时内的cpu system的各个sum;
{
"start":"48h-ago",
"queries":[
{
"metric": "sys.cpu.system",
"aggregator":"sum",
"tags":{
"dc":"*",
"host": "web01"
}
}
]
}
5.grouping操作,配合or字符,or的字符就是“|”字符;下面的例子就是找出所有dc内,是web03或者web04的host的
cpu的system的和;
{
"start":"48h-ago",
"queries":[
{
"metric": "sys.cpu.system",
"aggregator":"sum",
"tags":{
"dc":"*",
"host": "web03|web04"
}
}
]
}
6.
示例
metric实列字符串:
按照上述的请求体中的json 字符串存在一个本地文件query.json里面,当然也可以直接在curl的语句中拼接json字符串
我们的第一种使用方法:
curl -i -X POST -d @./query.json -H "Content-Type: application/json" http://localhost:4242/api/query
将localhost 换成tsd的实际hostname即可;
返回的结果正常的情况话会包含需要的数据;比如:我们实际的情况下的返回的数据:
curl -i -X POST -d @./query.json -H "Content-Type: application/json" http://localhost:4242/api/query
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 112
[{"metric":"sys.cpu.nice","tags":{"dc":"lga"},"aggregateTags":["host"],"dps":{"1544773808":13,"1544773809":18}}]
***
/api/query/exp
这个endpoint允许查询数据使用表达式,query被允许切分成多个部分;两个set的操作(或者join)也是被允许的。所有时序的并集是+符号; 比如,我们可以用group by在一个host层面计算“a+b”。所有的metric需要每一个host给出一个时序。比如“web01”,“web02”,“web03”。我们让a有所有三个host的值,但是b没有web03 使用加号,表达式会把“a.web01 + b.web01”以及“”a.web02 + b.web02”叠加,但是会skip web03.这点需要注意。使用union操作符,将会为b metric加“web01”和“web02”时序。这个会将替代metric的fill 策略。
Method
POST
请求参数
time部分是以json格式组成。
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
start | Integer | Required | 时间query的起始点,可以是相对的,也可以是绝对时间 | 1h-ago, 2015/05/05-00:00:00 | |
aggregator | String | Required | 全局aggregation的函数,用于所有的metric。将会被在某个单独metric上被override | sum | |
end | Integer | Optional | 时间query的终止点,可以是相对的,也可以是绝对时间 | now | 1h-ago, 2015/05/05-00:00:00 |
downsampler | Object | Optional | 降低(donw return)返回的datapoint的数量,格式见下面 | None | See below |
rate | Boolean | Optional | 是否计算所有的metric作为rate,比如每秒的value. | false | true |
example:
"time":{ "start":"1h-ago", "end":"10m-ago", "downsampler":{"interval":"15m","aggregator":"max"}
Downsampler
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
interval | String | Required | downsampling 间隔, i.e. 什么时间跨度去做rollup原生value . 格式是 <#><unit> , e.g. 15m |
1h | |
aggregator | String | Required | 用于降低(down)datapoint的aggregation函数 | avg | |
fillPolicy | Object | Optional | filling buckets的策略。bucket是缺少data point的 | None | See Below |
Fill Policies
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
policy | String | Required | 使用的policy,名字见下面 | zero | |
value | Double | Optional | 对于scalar fills, 在substitution过程中可以被使用的value。 | NaN | 42 |
Name | Description |
---|---|
nan | 如果所有aggregation的value都是NaN或者“missing”,那么发出一个 。对于aggregators,NaN被当做“哨兵值”(sentinel)用来使函数跳过这个值, 注意如果一个时序发出一个NaN,那么这个NaN 是有感染力的,会造成表达式的output变成NaN。序列化中NaN会被发出( At serialization the NaN will be emitted) |
null | 序列化的时间,发出一个NullEmits a Null,在计算的时候,这个值被当做NaNs。 |
zero | 当值没有的时候发出0 |
scalar | 当datapoint丢失的时候发出一个用户定义的值。必须指定好value。这个值可以是整数或者浮点型。 |
example :
{"id":"cpunice", "filter":"f1", "metric":"system.cpu.nice"}
expressions
一系列在metric上的表达式。在表达式中的变量必须是指定一个metric id或者表达式id。可以支持嵌套的表达式,但是如果出现一个自我引用(self reference)或者循环依赖( circular dependency),就会抛出异常。到现在的话基本的操作是支持的,包括加、减、乘、除、取模。
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
id | String | Required | 独一无二的表达式的id | cpubusy | |
expr | String | Required | 需要执行的表达式 | a + b / 1024 | |
join | Object | Optional | 一系列为了达到集合间的时序操作(perform for series across sets)集合操作(set operation)或者join操作 | union | See below |
fillPolicy | Object | Optional | 当用于一个嵌套表达式中且没有一个值提供的表达式的可选的fill 策略 | NaN | See above |
example:
{
"id": "cpubusy",
"expr": "(((a + b + c + d + e + f + g) - g) / (a + b + c + d + e + f + g)) * 100",
"join": {
"operator": "intersection",
"useQueryTags": true,
"includeAggTags": false
}
}
Joinsjoin对象(join object)如何将给出的metric众多的时间序列在一个表达式下进行merge。两个基本的支持的操作是union 以及intersection
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
operator | String | Required | 要么是使用 union 或者intersecti的一个操作符 | intersection | |
useQueryTags | Boolean | Optional | 当计算join的key的时候,决定的是否使用filter中明确定义的tags | false | true |
includeAggTags | Boolean | Optional | 是否在连接键中包含从一系列聚合的标记键 | true | false |
控制返回结果的一些参数
决定了输出操作以及是否允许你去删除一些从结果或者是原始metric中包含的表达式。默认的情况下,所有的表达式的这个部分是缺失的 。这个部分是一系列一个或者多个输出的对象
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
id | String | Required | metric或者表达式的id | e | |
alias | String | Optional | 一系列时序的可描述名字 | System Busy |
example:
{"id":"e", "alias":"System Busy"}
返回
输出将在名为outputs的数组总包含一个对象列表,这个结果的arrays表示每一个时间序列,这些时间序列跟随者一些meta data。最初的query 以及一些summary的统计也包含在其中。
Name | Description |
---|---|
id | 输出结果匹配的表达式id |
dps | 数组结果,每一个子数组以时间戳(毫秒)开始。余下的值是当groub by提供时候的每一个时序。 |
dpsMeta | query语句的meta data。包含第一以及最后的时间戳,结果数据集的数量或者是sub array,以及表述的时序数量。 |
datapoints | 经过aggregation以后的data point的数量。 |
meta | 在结果集中的每一个时间序列的数据。详细见下面。 |
输出数组中meta 部分包括有序的关于每一个时间序列信息,第一个数组元素将总是有一个metric的时间戳值。
Name | Description |
---|---|
index | meta指向的data point 数组中的index |
metrics | 表达式中包含的不同的metric名字 |
commonTags | 在结果序列中被aggregated的时间序列相关的tag key以及value。(Tag keys and values that were common across all time series that were aggregated in the resulting series ) |
aggregatedTags | 结果序列中出现的tag key(Tag keys that appeared in all series in the resulting series but had different values) |
rawDps | 包裹在结果中的原始值的数量。(The number of raw values wrapped into the result) |
dps | data point值数量 |
返回示例
{
"outputs": [
{
"id": "Mega expression",
"dps": [
[
1431561600000,
1010,
1030
],
[
1431561660000,
"NaN",
"NaN"
],
[
1431561720000,
"NaN",
"NaN"
],
[
1431561780000,
1120,
1140
]
],
"dpsMeta": {
"firstTimestamp": 1431561600000,
"lastTimestamp": 1431561780000,
"setCount": 4,
"series": 2
},
"meta": [
{
"index": 0,
"metrics": [
"timestamp"
]
},
{
"index": 1,
"metrics": [
"sys.cpu",
"sys.iowait"
],
"commonTags": {
"host": "web01"
},
"aggregatedTags": []
},
{
"index": 2,
"metrics": [
"sys.cpu",
"sys.iowait"
],
"commonTags": {
"host": "web02"
},
"aggregatedTags": []
}
]
},
{
"id": "sys.cpu",
"dps": [
[
1431561600000,
1,
2
],
[
1431561660000,
3,
0
],
[
1431561720000,
5,
0
],
[
1431561780000,
7,
8
]
],
"dpsMeta": {
"firstTimestamp": 1431561600000,
"lastTimestamp": 1431561780000,
"setCount": 4,
"series": 2
},
"meta": [
{
"index": 0,
"metrics": [
"timestamp"
]
},
{
"index": 1,
"metrics": [
"sys.cpu"
],
"commonTags": {
"host": "web01"
},
"aggregatedTags": []
},
{
"index": 2,
"metrics": [
"sys.cpu"
],
"commonTags": {
"host": "web02"
},
"aggregatedTags": []
}
]
}
],
"statsSummary": {
"datapoints": 0,
"rawDatapoints": 0,
"aggregationTime": 0,
"serializationTime": 33,
"storageTime": 77,
"timeTotal": 148.63
},
"query": {
"name": null,
"time": {
"start": "1y-ago",
"end": null,
"timezone": null,
"downsampler": null,
"aggregator": "sum"
},
"filters": [
{
"id": "f1",
"tags": [
{
"tagk": "host",
"filter": "web*",
"group_by": true,
"type": "wildcard"
}
]
}
],
"metrics": [
{
"metric": "sys.cpu",
"id": "a",
"filter": "f1",
"aggregator": null,
"fillPolicy": {
"policy": "nan",
"value": "NaN"
},
"timeOffset": null
},
{
"metric": "sys.iowait",
"id": "b",
"filter": "f1",
"aggregator": null,
"fillPolicy": {
"policy": "nan",
"value": "NaN"
},
"timeOffset": null
}
],
"expressions": [
{
"id": "e",
"expr": "a + b"
},
{
"id": "e2",
"expr": "e * 2"
},
{
"id": "e3",
"expr": "e2 * 2"
},
{
"id": "e4",
"expr": "e3 * 2"
},
{
"id": "e5",
"expr": "e4 + e2"
}
],
"outputs": [
{
"id": "e5",
"alias": "Woot!"
},
{
"id": "a",
"alias": "Woot!2"
}
]
}
}
***
/api/query/gexp
Method
GET
请求参数
query 只能通过GET请求,并且不支持Json
Name | Data Type | Required | Description | Example |
---|---|---|---|---|
exp | String | Required | 执行的石墨样式表达式(The Graphite style expression ).第一个函数的参数必须是另一个函数或者URI样式的sub query | scale(sum:if.bytes_in{host=*},1024) |
example:
http://localhost:4242/api/query/gexp?start=1h-ago&exp=scale(sum:if.bytes_in{host=*},1024)
函数
接受单个metric query的函数将在每一个时间序列结果上面操作。比如,如果一个query包含一个在host上group by的列如( scale(sum:if.bytes_in{host=*},1024)
),以及多个host在这个metric上都存在数据,那么每一个host相关的时序将都被发出,并被函数执行。对于执行多个metric的函数,一个union会被在每一个metric上都执行。E.g query sum(sum:if.bytes_in{host=*},sum:if.bytes_out{host=*})
, 假设2 hosts 存在, web01
and web02
. 输出是 if.bytes_in{host=web01} + if.bytes_out{host=web01}
and if.bytes_in{host=web02} + if.bytes_out{host=web02}
.
absolute()
发出数值的绝对值,负数转成正数
diffSeries([,])
在list中返回所有时序的不同。在每一个metric结果集的所有tag上执行一个union操作。默认是把value 填(fill)0。最多支持同时26个时序。
divideSeries([,])
list中返回所有时序的商。每一个metric结果集tag上执行一个union操作。默认是把value 填(fill)0。最多支持同时26个时序。
highestCurrent(,)
基于时间序列数据的最近结果进行排序,发出n个时序数据量的最大值。n是正整数
highestMax(,)
基于时间序列数据的最大结果进行排序,发出n个时序数据量的最大值。n是正整数
movingAverage(,)
发出一个对每个data point 以及metric的序列上的滑动窗口。这个窗口参数要么是可以表示data point数据量的正整数。或者是由一个时间粒度的整数时间跨度比如60s,60min等。
multiplySeries([,])
返回所有时序的结果到一个list。执行在每一个metric结果集中执行一个tag上的union。默认设置(fill)值是0,最大的同时执行的是26个时序数据。
scale(,)
每一个时序乘以一个因子,这个因子可以是正数或者是负数也可以是浮点数。
sumSeries([,])
把所有时序数据的和返回到一个list。执行在每一个metric结果集中执行一个tag上的union。默认设置(fill)值是0,最大的同时执行的是26个时序数据。
/api/query/last
这个endpoint提供接触每一个时间序列的最近value。当只有最近data point需要的时候提供一个regular query上的优化。通过meta data counter的时间戳或者是逆向(backwards)扫描当前系统时间的定位到最近的point .有2个方法可以提供query;
- Metric Query - 和传统 metric query相似, 可以提供一个metric名字以及一系列可选择的tag 对。如果实时meta开启,TSD 将scan meta data 表来发现是否任何时序匹配这个query。每一个匹配的时序,将扫描出最近的data point ,如果meta 没有启动,TSD将尝试寻找确切的metric 和tag集。
- TSUID Query - 提供UIDs既可以query,
2个方法去找到最近的data point:
- Counter Method - 如果反向scan 值提供了,且meta 被启动,那么默认是在meta data 表中查找data point counter。counter 记录了由tsd记录的最近data point的时间。这个endpoint 找出时间戳以及获取合适的data row,取出最近的row中的point。这个将在大多数时间有效,然而如果你回填了老的数据,这个counter的列时间戳就可能不精确。.这个方法最好用在持续的更新数据。
- Back Scan - 或者 可以从当前tsd执行的系统时间指定向回扫描数个小时。比如,如果你设置了一个往回scan 24小时,这个tsd将第一次在当前小时内在row上查找数据。如果这个row空的,那么它将在这个row查找时间前一个小时查找。它将一直执行这件事直到找到一个data point 或者是达到时间限制。时间设置越长,消耗scan时间越多。
所有的匹配了query的时间序列并被找到的data point都会返回结果。这个结果是一个个每个时序的单独data point的list。在单独的data point上执行aggregation是不行的。
Method
GET, POST
请求参数
Name | Data Type | Required | Description | Default | Example |
---|---|---|---|---|---|
timeseries | Array | Required | 一个或者多个query的list 决定哪一个时序去找到最近的data point | ||
resolve | Boolean | Optional | 是否需要解决结果的TSUIDS。 | false | true |
back_scan | Integer | Optional | 在过去的几个小时内查找data,如果是0那么meta data counter的时间戳被使用 | 0 | 24 |
Metric Query 字符串格式
timeseries=<metric_name>[{<tag_name1>=<tag_value1>[,...<tag_nameN>=<tag_valueN>]}]
和传统的 metric query一样,但是不允许 aggregations, rates, down sampling or grouping操作。 如果你提供一个反向scan的值以避免meta table,那么你必须应用所有的tag 以及value以匹配你查找的时间序列。
TSUID Query 字符串格式:
tsuids=<tsuid1>[,...<tsuidN>]
Example
http://localhost:4242/api/query/last?timeseries=proc.stat.cpu{host=foo,type=idle}×eries=proc.stat.mem{host=foo,type=idle}
http://localhost:4242/api/query/last?tsuids=000001000002000003,000001000002000004&back_scan=24&resolve=true
返回
输出是一个array。如果特定时序的data point 没有被定位,那么不会输出。
Name | Description |
---|---|
metric | 时间序列metric的名字. 只有 resolve 设置 true才会返回 |
tags | 时间序列的tag list. 只有 resolve 设置 true才会返回 |
timestamp | 毫秒级别的unix时间戳 |
value | data point 返回 值,是string |
tsuid | 时间序列的十六进制tsuid |
返回示例
[
{
"timestamp": 1377118201000,
"value": "1976558550",
"tsuid": "0023E3000002000008000006000001"
},
{
"timestamp": 1377118201000,
"value": "1654587485",
"tsuid": "0023E3000002000008000006001656"
}
]
[
{
"metric": "tsd.hbase.rpcs",
"timestamp": 1377186301000,
"value": "2723265185",
"tags": {
"type": "put",
"host": "tsd1"
},
"tsuid": "0023E3000002000008000006000001"
},
{
"metric": "tsd.hbase.rpcs",
"timestamp": 1377186301000,
"value": "580720",
"tags": {
"type": "put",
"host": "tsd2"
},
"tsuid": "0023E3000002000008000006017438"
}
]
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论