查詢(xún)時(shí)間線最新數(shù)據(jù)點(diǎn)
請(qǐng)求路徑和方法
請(qǐng)求路徑 | 請(qǐng)求方法 | 描述 |
/api/query/last | POST | 獲得時(shí)間線最新寫(xiě)入的數(shù)據(jù)點(diǎn) |
此端口完全兼容 OpenTSDB 協(xié)議。
請(qǐng)求內(nèi)容
請(qǐng)求內(nèi)容JSON格式
名字 | 類(lèi)型 | 是否必需 | 描述 | 默認(rèn)值 | 舉例 |
queries | Array | 是 | 子查詢(xún)數(shù)組 | 無(wú) | 見(jiàn)子查詢(xún)說(shuō)明 |
timestamp | Long | 否 | unix 時(shí)間戳，單位為秒或者毫秒，指定該參數(shù)時(shí)表示查詢(xún)到該時(shí)間戳為止最新的數(shù)據(jù)點(diǎn)，否則表示查詢(xún)當(dāng)前最新的數(shù)據(jù)點(diǎn) | 無(wú) | 1539763573 |
hint | Map | 否 | 查詢(xún) Hint 化 | 無(wú) | 見(jiàn)查詢(xún) Hint 化說(shuō)明 |
limit | Map | 否 | 多個(gè)最新點(diǎn)查詢(xún)。 | 無(wú) | 見(jiàn)查詢(xún) Limit 化說(shuō)明 |
子查詢(xún)JSON格式
子查詢(xún)中可以指定“Metric查詢(xún)”格式或 “TSUID查詢(xún)”格式。前者是通過(guò)指定時(shí)間線metric, tags作為檢索條件執(zhí)行查詢(xún)；后者則是直接指定時(shí)間線的唯一ID來(lái)執(zhí)行查詢(xún)。在子查詢(xún)的列表中，兩種格式可以共存。
Metric 查詢(xún)
名稱(chēng) | 類(lèi)型 | 是否必需 | 描述 | 默認(rèn)值 | 舉例 |
metric | String | 是 | 待查詢(xún)最新數(shù)據(jù)點(diǎn)的 Metric | 無(wú) | cpu.usage |
tags | String | 否 | 待查詢(xún)最新數(shù)據(jù)點(diǎn)的 Tags | 無(wú) | host_name=host1 |
hint | Map | Map | 查詢(xún) Hint 化 | 無(wú) | 見(jiàn)查詢(xún) Hint 化說(shuō)明 |
這里不支持通過(guò)filters指定維度過(guò)濾條件，必須使用tags字段指定維度過(guò)濾條件
TSUID 查詢(xún)
名稱(chēng) | 類(lèi)型 | 是否必需 | 描述 | 默認(rèn)值 | 舉例 |
tsuid | String | 是 | 待查詢(xún)最新數(shù)據(jù)點(diǎn)的 TSUID | 無(wú) | 00005B00005C0000F000005D0000EE00005E0000EF |
時(shí)間線的 TSUID 可以通過(guò) /api/search/lookup 接口查詢(xún)。
在高可用版本中，tsuid字段僅僅是形式上兼容，但不再支持tsuid查詢(xún)功能。同樣，在高可用版本中，/api/search/lookup 也不再支持返回tsuid值
請(qǐng)求 JSON 示例
任務(wù)：
查詢(xún)包含 metric 名字為“cpu.usage” 和 tag 名字為“host_name=host1”的時(shí)間線的最新寫(xiě)入數(shù)據(jù)點(diǎn)。
同時(shí)，查詢(xún)包含 TSUID 為00005B00005C00002E00005D0000EE00005E0000EF和00005B00005C0000F000005D0000EE00005E0000EF兩條時(shí)間線的最新寫(xiě)入數(shù)據(jù)點(diǎn)。
請(qǐng)求：POST/api/query/last
請(qǐng)求體：
{
"queries" : [
{
"metric":"cpu.usage",
"tags" : {
"host_name": "host1"
}
},
{
"tsuids": [
"00005B00005C00002E00005D0000EE00005E0000EF",
"00005B00005C0000F000005D0000EE00005E0000EF"
]
}
]
}響應(yīng)說(shuō)明
查詢(xún)成功的 HTTP 響應(yīng)碼為 200，返回符合條件的時(shí)間線最新數(shù)據(jù)點(diǎn)，內(nèi)容為JSON 格式數(shù)據(jù)；如果沒(méi)有時(shí)間線滿(mǎn)足條件，則返還空集。JSON說(shuō)明如下：
名稱(chēng) | 描述 |
metric | 指標(biāo)名 |
timestamp | 最新數(shù)據(jù)點(diǎn)的時(shí)間戳 |
value | 指標(biāo)值 |
tags | 數(shù)據(jù)點(diǎn)對(duì)應(yīng)的tag鍵值集合 |
tsuid | 數(shù)據(jù)點(diǎn)對(duì)應(yīng)的時(shí)間線ID |
響應(yīng)體：
[{
"metric": "cpu.usage",
"timestamp": 1556418300000,
"value": 30.3,
"tags": {
"host_name": "host1"
},
"tsuid": "00005B00005C00001D",
}, {
"metric": "cpu.usage",
"timestamp": 1556418300000,
"value": 25.6,
"tags": {
"host_name": "host2",
"cluster": "cluster1"
"zone": "zone1"
},
"tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE",
}, {
"metric": "cpu.usage",
"timestamp": 1556418300000,
"value": 43.1,
"tags": {
"host_name": "host3",
"cluster": "cluster1"
"zone": "zone1"
},
"tsuid": "00005B00005C0000F000005D0000EE00005E0000EF",
}]查詢(xún) Hint 化說(shuō)明
場(chǎng)景說(shuō)明
該特性主要是提高查詢(xún)速度。假設(shè)某一個(gè) tags A 命中的時(shí)間線明顯大于其他的 tags B 命中的時(shí)間線，則需要舍棄，避免撈取 tags A 的大量時(shí)間線之后，被 tagsB 小規(guī)模時(shí)間線交集后，結(jié)果集等于 tagsB。
格式說(shuō)明
當(dāng)前版本只支持 tagk 級(jí)別的查詢(xún)索引限制（hint 下的 tagk 是固定寫(xiě)法）
其中，
0表示不使用對(duì)應(yīng) tagk 的索引，反之1表示使用對(duì)應(yīng) tagk 的索引
版本說(shuō)明
從 v2.6.1 版本開(kāi)始支持 hint 特性
查詢(xún)示例
子查詢(xún)級(jí)別
{
"queries": [
{
"metric": "sys.cpu.nice",
"tags": {
"host": "web01"
},
"hint": {
"tagk": {
"dc": 1
}
}
}
]
}整體查詢(xún)級(jí)別
{
"queries": [
{
"metric": "sys.cpu.nice",
"tags": {
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1
}
}
}異常情況
不可同時(shí)指定 0 和 1
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1,
"host": 0
}
}
}會(huì)返回如下報(bào)錯(cuò)信息：
{
"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=[])"
}
}不可指定除了 0 和 1 之外的值
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 100
}
}
}會(huì)返回如下報(bào)錯(cuò)信息：
{
"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=[])"
}
}查詢(xún)Limit說(shuō)明
Limit: 通過(guò)指定Limit可以查詢(xún)多個(gè)最新數(shù)據(jù)點(diǎn)。當(dāng)請(qǐng)求中沒(méi)有指定Limit時(shí)，每條時(shí)間序列只返回一個(gè)最新的數(shù)據(jù)點(diǎn)。
JSON格式說(shuō)明
名稱(chēng) | 類(lèi)型 | 是否必需 | 描述 | 默認(rèn)值 | 舉例 |
size | Integer | 是 | 每個(gè)時(shí)間線最新數(shù)據(jù)點(diǎn)的最大數(shù)量。 | 無(wú) | 5 |
from | Long | 是 | 查詢(xún)范圍開(kāi)始時(shí)間。 | 無(wú) | 1346846400 |
示例
寫(xiě)入數(shù)據(jù)：4個(gè)時(shí)間序列每個(gè)時(shí)間線2條數(shù)據(jù)。
[{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736040, "value":1},
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736050, "value":2},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736060, "value":3},
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736070, "value":4},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736080, "value":5},
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736090, "value":6},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736100, "value":7},
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736110, "value":8}]查詢(xún)?cè)O(shè)置size為3，從時(shí)間戳1514736040到1514736100間共有7條數(shù)據(jù)
{
"timestamp": 1514736100,
"limit": {
"size": 2,
"from": 1514736040
},
"queries": [
{
"metric": "testmetric"
}
]
}查詢(xún)結(jié)果，時(shí)間范圍內(nèi)每個(gè)時(shí)間線最多2條數(shù)據(jù)
[
{
"metric": "testmetric",
"timestamp": 1514736060000,
"value": 3.0,
"tags": {
"testmetric1_tagk": "testmetric1_tagv1"
},
"tsuid": "0200000200000200****",
"version": 0,
"dps": {
"1514736040000": 1.0,
"1514736060000": 3.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736100000,
"value": 7.0,
"tags": {
"testmetric1_tagk": "testmetric1_tagv2"
},
"tsuid": "0400000200000200****",
"version": 0,
"dps": {
"1514736080000": 5.0,
"1514736100000": 7.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736070000,
"value": 4.0,
"tags": {
"testmetric2_tagk": "testmetric2_tagv1"
},
"tsuid": "0E00000200000300****",
"version": 0,
"dps": {
"1514736050000": 2.0,
"1514736070000": 4.0
}
},
{
"metric": "testmetric",
"timestamp": 1514736090000,
"value": 6.0,
"tags": {
"testmetric2_tagk": "testmetric2_tagv2"
},
"tsuid": "1000000200000300****",
"version": 0,
"dps": {
"1514736090000": 6.0
}
}
]