全部产品
Search
文档中心

查询时间线最新数据点

更新时间: 2020-08-11

请求路径和方法

请求路径 请求方法 描述
/api/query/last POST 获得时间线最新写入的数据点

注意:此端口完全兼容 OpenTSDB 协议。

请求内容

请求内容JSON格式

名字 类型 是否必需 描述 默认值 举例
queries Array 子查询数组 见子查询说明
timestamp Long unix 时间戳,单位为秒或者毫秒,指定该参数时表示查询到该时间戳为止最新的数据点,否则表示查询当前最新的数据点 1539763573
hint Map 查询 Hint 化 见查询 Hint 化说明

子查询JSON格式

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

Metric 查询

名称 类型 是否必需 描述 默认值 举例
metric String 待查询最新数据点的 Metric cpu.usage
tags String 待查询最新数据点的 Tags host_name=host1

hint|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

请求体:

  1. {
  2. "queries" : [
  3. {
  4. "metric":"cpu.usage",
  5. "tags" : {
  6. "host_name": "host1"
  7. }
  8. },
  9. {
  10. "tsuids": [
  11. "00005B00005C00002E00005D0000EE00005E0000EF",
  12. "00005B00005C0000F000005D0000EE00005E0000EF"
  13. ]
  14. }
  15. ]
  16. }

响应说明

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

名称 描述
metric 指标名
timestamp 最新数据点的时间戳
value 指标值
tags 数据点对应的tag键值集合
tsuid 数据点对应的时间线ID

响应体:

  1. [{
  2. "metric": "cpu.usage",
  3. "timestamp": 1556418300000,
  4. "value": 30.3,
  5. "tags": {
  6. "host_name": "host1"
  7. },
  8. "tsuid": "00005B00005C00001D",
  9. }, {
  10. "metric": "cpu.usage",
  11. "timestamp": 1556418300000,
  12. "value": 25.6,
  13. "tags": {
  14. "host_name": "host2",
  15. "cluster": "cluster1"
  16. "zone": "zone1"
  17. },
  18. "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE",
  19. }, {
  20. "metric": "cpu.usage",
  21. "timestamp": 1556418300000,
  22. "value": 43.1,
  23. "tags": {
  24. "host_name": "host3",
  25. "cluster": "cluster1"
  26. "zone": "zone1"
  27. },
  28. "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF",
  29. }]

查询 Hint 化说明

场景说明

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

格式说明

  • 当前版本只支持 tagk 级别的查询索引限制
  • 其中,0 表示不使用对应 tagk 的索引,反之 1 表示使用对应 tagk 的索引

查询示例

子查询级别

  1. {
  2. "queries": [
  3. {
  4. "metric": "sys.cpu.nice",
  5. "tags": {
  6. "host": "web01"
  7. },
  8. "hint": {
  9. "tagk": {
  10. "dc": 1
  11. }
  12. }
  13. }
  14. ]
  15. }

整体查询级别

  1. {
  2. "queries": [
  3. {
  4. "metric": "sys.cpu.nice",
  5. "tags": {
  6. "host": "web01"
  7. }
  8. }
  9. ],
  10. "hint": {
  11. "tagk": {
  12. "dc": 1
  13. }
  14. }
  15. }

异常情况

不可同时指定 0 和 1

  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "none",
  7. "metric": "sys.cpu.nice",
  8. "tags": {
  9. "dc": "lga",
  10. "host": "web01"
  11. }
  12. }
  13. ],
  14. "hint": {
  15. "tagk": {
  16. "dc": 1,
  17. "host": 0
  18. }
  19. }
  20. }

会返回如下报错信息:

  1. {
  2. "error": {
  3. "code": 400,
  4. "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
  5. "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=[])"
  6. }
  7. }

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

  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "none",
  7. "metric": "sys.cpu.nice",
  8. "tags": {
  9. "dc": "lga",
  10. "host": "web01"
  11. }
  12. }
  13. ],
  14. "hint": {
  15. "tagk": {
  16. "dc": 100
  17. }
  18. }
  19. }

会返回如下报错信息:

  1. {
  2. "error": {
  3. "code": 400,
  4. "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
  5. "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=[])"
  6. }
  7. }