查询时间线最新数据点

请求路径和方法

请求路径

请求方法

描述

/api/query/last

POST

获得时间线最新写入的数据点

注意

此端口完全兼容 OpenTSDB 协议。

请求内容

请求内容JSON格式

名字

类型

是否必需

描述

默认值

举例

queries

Array

子查询数组

见子查询说明

timestamp

Long

unix 时间戳,单位为秒或者毫秒,指定该参数时表示查询到该时间戳为止最新的数据点,否则表示查询当前最新的数据点

1539763573

hint

Map

查询 Hint 化

见查询 Hint 化说明

limit

Map

多个最新点查询。

见查询 Limit 化说明

子查询JSON格式

子查询中可以指定“Metric查询”格式或 “TSUID查询”格式。前者是通过指定时间线metric, tags作为检索条件执行查询;后者则是直接指定时间线的唯一ID来执行查询。在子查询的列表中,两种格式可以共存。

Metric 查询

名称

类型

是否必需

描述

默认值

举例

metric

String

待查询最新数据点的 Metric

cpu.usage

tags

String

待查询最新数据点的 Tags

host_name=host1

hint

Map

Map

查询 Hint 化

见查询 Hint 化说明

注意

这里不支持通过filters指定维度过滤条件,必须使用tags字段指定维度过滤条件

TSUID 查询

名称

类型

是否必需

描述

默认值

举例

tsuid

String

待查询最新数据点的 TSUID

00005B00005C0000F000005D0000EE00005E0000EF

注意

  1. 时间线的 TSUID 可以通过 /api/search/lookup 接口查询。

  2. 高可用版本中,tsuid字段仅仅是形式上兼容,但不再支持tsuid查询功能。同样,在高可用版本中,/api/search/lookup 也不再支持返回tsuid值

请求 JSON 示例

任务:

查询包含 metric 名字为“cpu.usage” 和 tag 名字为“host_name=host1”的时间线的最新写入数据点。

同时,查询包含 TSUID 为00005B00005C00002E00005D0000EE00005E0000EF00005B00005C0000F000005D0000EE00005E0000EF两条时间线的最新写入数据点。

请求:POST/api/query/last

请求体:

{
    "queries" : [
        {
            "metric":"cpu.usage",
            "tags" : {
                "host_name": "host1"
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

响应说明

查询成功的 HTTP 响应码为 200,返回符合条件的时间线最新数据点,内容为JSON 格式数据;如果没有时间线满足条件,则返还空集。JSON说明如下:

名称

描述

metric

指标名

timestamp

最新数据点的时间戳

value

指标值

tags

数据点对应的tag键值集合

tsuid

数据点对应的时间线ID

响应体:

[{
    "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",
}]

查询 Hint 化说明

场景说明

该特性主要是提高查询速度。假设某一个 tags A 命中的时间线明显大于其他的 tags B 命中的时间线,则需要舍弃,避免捞取 tags A 的大量时间线之后,被 tagsB 小规模时间线交集后,结果集等于 tagsB。

格式说明

  • 当前版本只支持 tagk 级别的查询索引限制(hint 下的 tagk 是固定写法)

  • 其中,0 表示不使用对应 tagk 的索引,反之 1 表示使用对应 tagk 的索引

版本说明

从 v2.6.1 版本开始支持 hint 特性

查询示例

子查询级别

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      },
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

整体查询级别

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1
    }
  }
}

异常情况

不可同时指定 0 和 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=[])"
    }
}

不可指定除了 0 和 1 之外的值

{
  "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=[])"
    }
}

查询Limit说明

Limit: 通过指定Limit可以查询多个最新数据点。当请求中没有指定Limit时,每条时间序列只返回一个最新的数据点。

JSON格式说明

名称

类型

是否必需

描述

默认值

举例

size

Integer

每个时间线最新数据点的最大数量。

5

from

Long

查询范围开始时间。

1346846400

示例

写入数据:4个时间序列每个时间线2条数据。

[{"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}]

查询设置size为3,从时间戳1514736040到1514736100间共有7条数据

{
    "timestamp": 1514736100,
    "limit": {
        "size": 2,
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric"
        }
    ]
}

查询结果,时间范围内每个时间线最多2条数据

[
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "02000002000002000003",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "04000002000002000005",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E000002000003000004",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "10000002000003000006",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]