query

/api/query

Method

GET, POST, DELETE

请求参数

Sub query

有2中sub query 分别是metric query 和 tsuid query，sub query 包括下面：

Rate Options

当在一个query语句 里面添加了rate 选项，这个选项必须围绕大括号，比如： m=sum:rate{counter,,1000}:if.octets.in. 如果你想用counterMax但是不希望提供resetValue，那么你需要在刚才的例子里面那样添加2个逗号，一些附加的rateOption如下：

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包括下面:

请求体

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格式组成。

example：
"time":{ "start":"1h-ago", "end":"10m-ago", "downsampler":{"interval":"15m","aggregator":"max"}

Downsampler

Fill Policies

example :
{"id":"cpunice", "filter":"f1", "metric":"system.cpu.nice"}

expressions

一系列在metric上的表达式。在表达式中的变量必须是指定一个metric id或者表达式id。可以支持嵌套的表达式，但是如果出现一个自我引用（self reference）或者循环依赖（ circular dependency），就会抛出异常。到现在的话基本的操作是支持的，包括加、减、乘、除、取模。

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

控制返回结果的一些参数

决定了输出操作以及是否允许你去删除一些从结果或者是原始metric中包含的表达式。默认的情况下，所有的表达式的这个部分是缺失的 。这个部分是一系列一个或者多个输出的对象

example:
{"id":"e", "alias":"System Busy"}

返回

输出将在名为outputs的数组总包含一个对象列表，这个结果的arrays表示每一个时间序列，这些时间序列跟随者一些meta data。最初的query 以及一些summary的统计也包含在其中。

输出数组中meta 部分包括有序的关于每一个时间序列信息，第一个数组元素将总是有一个metric的时间戳值。

返回示例

{
  "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

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

请求参数

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}&timeseries=proc.stat.mem{host=foo,type=idle}
http://localhost:4242/api/query/last?tsuids=000001000002000003,000001000002000004&back_scan=24&resolve=true

返回

输出是一个array。如果特定时序的data point 没有被定位，那么不会输出。

返回示例

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