opentsdb http api 使用方法

引言

tsdb所有的特性基本都可以通过http接口进行操作，比如查询数据、写入数据以及管理元数据等。http访问的路径是http://localhost:4242/path。localhost是ip，默认端口为4242，不同的path会指向不同的接口而实现不同的功能，下面会对这些path进行详细讲解。接下来我们通过http接口去使用和管理tsdb。

本文的包括的接口如下：

• /s
• /api/aggregators
• /api/annotation
• /api/config
• /api/dropcaches
• /api/put
• /api/rollup
• /api/histogram
• /api/query
• /api/query/last
• /api/search/lookup
• /api/stats
• /api/suggest
• /api/uid/assign
• /api/uid/tsmeta
• /api/uid/uidmeta

/s

• 请求方式：get、post、delete等
• 请求参数：紧接着 /s 后面加上文件路径和文件名称

在安装opentsdb的时候我们记得配置了下面这一项:

tsd.http.staticroot=./build/staticroot

这个是配置了tsdb一些静态文件的地址，比如前端的js文件等。当我们发送如下请求时：

http://localhost:4242/s/queryui.nocache.js

返回的是staticroot文件夹下面queryui.nocache.js的内容。

/api/aggregators

• 请求方式：get、post
• 请求参数：无

该接口返回的是tsdb支持的所有聚合方式。请求示例：

http://localhost:4242/api/aggregators

返回内容：

["mult","p90","zimsum","mimmax","sum","p50","none","p95","ep99r7","pfsum","p75","p99","ep99r3","ep95r7","min","avg","ep75r7","dev","ep95r3","ep75r3","ep50r7","ep90r7","mimmin","p999","ep50r3","ep90r3","ep999r7","last","max","count","diff","median","squareSum","ep999r3","first"]

/api/annotation

opentsdb除了支持metrics数据之外还支持annotation数据，annotation数据是记录一个时间点发生的事件（可以去解释tsdb代表的意义），其值为字符类型，需要注意的是annotation数据的时间戳是以秒为单位，它的字段及意义如下：

• startTime：必填，以秒为单位的时间戳，代表时间发生的时间。
• endTime ：可选，同样是以秒为单位的时间戳，代表事件结束或者完成的时间。
• tsuid：可选，tsuid是关联该事件和时间序列的纽带（因为时间序列都有一个唯一的id，我们称之为tsuid，它由metric，tags的uid构成）,当uid为空时即代表全局事件。
• description：可选，对事件的简短描述，建议不超过25个字符，描述可能会出现在时间序列图上。
• notes：可选，事件的详细描述。
• custom：可选，是一个map类型的数据，用于保存自定义的字段。
  注意：annotation数据的唯一性约束由startTime和tsuid来满足，也就是说不同的annotation数据必定会有不同的startTime或者不同的tsuid。

请求方式

1. get - 查询单个annotation。
2. post - 新增或者修改annotation。
3. put - 新增或者替换annotation。
4. delete - 删除单个annotation。

• 一个post请求的例子：

{
  "startTime":"1369141261",
  "tsuid":"000001000001000001",
  "description": "Testing Annotations",
  "notes": "These would be details about the event, the description is just a summary",
  "custom": {
      "owner": "jdoe",
      "dept": "ops"
  }
}

当我们通过如下的get请求时，便可得：

http://localhost:4242/api/annotation?start_time=1369141261&tsuid=000001000001000001
// 请求结果为：
{
    "tsuid": "000001000001000001",
    "description": "Testing Annotations",
    "notes": "These would be details about the event, the description is just a summary",
    "custom": {
        "owner": "jdoe",
        "dept": "ops"
    },
    "startTime": 1369141261,
    "endTime": 1369141262
}

/api/config

• 请求方式：get、post
• 请求参数：无
  该接口以key/value的方式返回tsdb所有的配置。

/api/dropcaches

• 请求方式：get、post
• 请求参数：无
  该接口的作用是清理tsdb的内存，主要是清理UID到metric、tags，和metric、tags到UID的映射关系，需要注意的是这个接口并不会清理磁盘上的缓存。

/api/put

• 请求方式：post
• 请求参数：

参数	说明	example
summary	返回主要摘要	/api/put?summary
details	返回详细信息	/api/put?details
sync	是否同步，即是否等待数据都写入成功后才返回结果	/api/put?sync
sync_timeout	返回结果之前的等待时间	/api/put/?sync&sync_timeout=60000

请求body

名称	类型	描述
metric	String	要存储指标的名称
timestamp	Integer	以秒或者毫秒为单位的时间戳
value	Integer/Float	时序数据库的值
tags	Map	本条数据的tags

单条数据的写入例子：

{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
       "host": "web01",
       "dc": "lga"
    }
}

单词写入多条数据的例子：

[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 18,
        "tags": {
           "host": "web01",
           "dc": "lga"
        }
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        }
    }
]

Response
tsdb写入成功默认返回的http状态码是204，也就是返回的body为空。若想要知道更详细的结果可以在请求路径上加上summary或者details参数。

/api/rollup

该接口和 /api/put 类似，都是写入数据，但是还涉及到rollup和pre-aggregate。个人目前还未了解清楚，先贴出官方参考文档地址，待博主弄清楚再回来记录。

/api/histogram

该接口是opentsdb 2.4版本新特性，假若需要使用该接口，在启动tsdb时需要配置tsd.core.histograms.config。

• 请求方式:post
• 请求路径上的参数和 /api/put是一样的：summary、details、sync和sync_timeout。

直方图大体上分为两类，第一类是简单的分块直方图，第二类就是可以通过编码器和解码器定义的直方图。

1. 简单分块直方图，请求体如下：

{
    "metric": "sys.cpu.nice",
    "timestamp": 1356998400,
    "overflow": 1,
    "underflow": 0,
    "buckets": {
        "0,1.75": 12,
        "1.75,3.5": 16
    },
    "tags": {
        "host": "web01",
        "dc": "lga"
    }
}

metric、timestamp、tags代表的意义和 /api/put 中的意义相同，此处不再赘述。其它参数代表意义如下：

名称	类型	描述
overflow	Integer	The count of measurements higher than the highest bucket upper bound. Default is zero.
underflow	Integer	The count of measurements lower than the lowest bucket lower bound.
buckets	Map	Map中的每一对数据，key表示区间，value表示数值，需要注意的是区间一定需要连续

2. 解编码定义的直方图请求体如下：

{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": "AgMIGoAAAAADAAAAAAAAAAAAAAAAAPA/AAAAAABARUAAAAAAAADwPwAAAAAAADhAAAAAAABARUA=",
    "tags": {
        "host": "web01",
        "dc": "lga"
    },
    "id": 1
}

字段id和value代表的含义如下：

名称	类型	描述
value	String	base64编码的直方图数据
id	Integer	指解码器，id具体代表什么解码器由tsd.core.histograms.config 配置决定

/api/query

查询数据的接口，也是用的最多的接口。

• 请求方式：get、post、delete，注意:从opentsdb2.2版本开始，若用delete查询数据，则在返回数据的同时会删除数据，第二次就查询结果则为空。

query官网文档地址
由于该接口的复杂度，日后会新增一篇文章来记录，可参见opentsdb写入和查询详解。

/api/query/last

该接口是查询最新数据，查询最新数据的方式有两种：

1. Counter Method：该查询方式是基于data point counter的。
2. Back Scan：设定一个扫描的时间，从当前时刻往后扫描。

请求body中的backScan即代表往后扫描24小时，当backScan为0时表示采用第一种查询方式。resolveNames=true时，会把数据的metric，tags，tsuid也一起返回回来。

{
    "queries": [
        {"metric":"sys.cpu.nice","tags":{"host":"web01","dc":"lga"}}
    ],
    "resolveNames":true,
    "backScan":24
}

/api/search/lookup

该接口在给定了metric的情况下，可以查询有哪些时间序列。需要注意的是：若需要使用此接口，在启动tsdb的时候需要加上下面三项配置，作用是开启Metadata功能。

tsd.core.meta.enable_realtime_uid=true
tsd.core.meta.enable_realtime_ts=true
tsd.core.meta.enable_tsuid_tracking=true

现在先写入两条数据,两条数据有相同的metric但是有不同的tags：

[
{"metric":"sys.cpu.nice2","timestamp":1562068000,"value":0,"tags":{"host":"web01","dc":"lga"}},
{"metric":"sys.cpu.nice2","timestamp":1562068000,"value":0,"tags":{"host":"web02","dc":"lga"}}
]

再利用 /api/search/lookup 接口进行查询，查询body如下，意思是给定metric为sys.cpu.nice2，和tags中dc=lga的条件下，查询符合条件的时间序列。

{"metric":"sys.cpu.nice2","tags":[{"key":"dc","value":"lga"}]}

返回结果如下,可以看到result中返回了两个刚刚插入的数据信息，若返回的数据较多还可以进行分页查询，详细请参考官网。

{
    "type": "LOOKUP",
    "metric": "sys.cpu.nice2",
    "tags": [{"key":"dc","value":"lga"}],
    "limit": 25,
    "time": 25,
    "results": [
 {"tsuid":"000003000001000001000002000002","metric":"sys.cpu.nice2","tags":{"host":"web01","dc":"lga"}},
 {"tsuid":"000003000001000003000002000002","metric":"sys.cpu.nice2","tags":{"host":"web02","dc":"lga"}}
    ],
    "startIndex": 0,
    "totalResults": 2
}

/api/stats

该接口是查询tsdb的一些统计信息，出了该接口本身之外还包含了一些子接口：

1. /api/stats/jvm:关于jvm的信息。
2. /api/stats/query:256最近查询接口的信息。
3. /api/stats/region_clients：hbase有关的信息。
4. /api/stats/threads：tsdb的线程信息。

/api/suggest

该接口可用于页面上输入metric、tagk和tagv的自动提示.
请求body如下,type指定是metric,tagk或者tagv，q用于匹配的值，max是返回结果的个数。

{"type":"metrics","q":"sys","max":10}

需要注意的是匹配是从字符串头部开始匹配，并不支持全文搜索和模糊匹配，并且是区分大小写的。

/api/uid/assign

接口可以为metric,tagk,tagv分配uid，post请求body如下：

{"metric":["sys.cpu.nice","sys.cpu.nice1"],"tagk":["host"],"tagv":["web01","web02"]}

其返回结果如下：

{
    "tagv_errors":{"web01":"Name already exists with UID: 000001","web02":"Name already exists with UID: 000003"},
    "metric": {},
    "tagk": {},
    "tagk_errors": {"host": "Name already exists with UID: 000001"},
    "metric_errors": {"sys.cpu.nice": "Name already exists with UID: 000001","sys.cpu.nice1": "Name already exists with UID: 000002"},
    "tagv": {}
}

可见这些metric,tags都已经被分配。如果需要让tsdb在写入数据时，对metric自动生成uid，tsdb需要加入下面一条配置：

tsd.core.auto_create_metrics = true

否则在put数据并且该metric不存在时，会报错该metric不存在的错误。

/api/uid/tsmeta

该接口可以查询、修改和删除meta data信息，mate data就是时间序列和metric、tags的中介数据。

get请求方式是对meta data进行查询，请求方式有两种，metric方式和tsuid方式，请求例子如下：

http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001
http://localhost:4242/api/uid/tsmeta?m=sys.cpu.nice&dc=lga

POST/PUT方式是对meta data进行更改，并且进行操作的meta data一定是要存在的，否则会报错。并且如果用put请求方式，没有提供的字段也会按照默认值进行更改。
现在我们先查询一个meta data，查询请求接口和返回结果如下：

http://localhost:4242/api/uid/tsmeta?tsuid=000004000001000008000002000009

{
    "tsuid": "000004000001000008000002000009",
    "metric":{"uid":"000004","type":"METRIC","name":"cpu.system","description":"","notes":"","created":1562462940,"custom":null,"displayName":""},
    "tags": [
        {"uid":"000001","type":"TAGK","name":"host","description":"","notes":"","created":0,"custom":null,"displayName":""},
        {"uid":"000008","type":"TAGV","name":"web01.dal.mysite.com","description":"","notes":"","created":1562462940,"custom":null,"displayName":""},
        {"uid":"000002","type":"TAGK","name":"dc","description":"","notes":"","created":0,"custom":null,"displayName":""},
        {"uid":"000009","type":"TAGV","name":"dal","description":"","notes":"","created":1562462940,"custom":null,"displayName":""}
    ],
    "description": "","notes": "", "created": 1562462940,"units": "","retention": 0, "max": "NaN","min": "NaN","displayName": "", "dataType": "","lastReceived": 0,"totalDatapoints": 0
}

然后我们再对该meta data进行修改，post请求body如下：

{
    "tsuid":"000004000001000008000002000009",
    "displayName":"test api/uid/tsmeta displayName",
    "description":"test api/uid/tsmeta description",
    "notes":"test api/uid/tsmeta notes",
    "custom": { "owner": "Jane Doe", "department": "Operations","assetTag": "12345"}
}

修改之后，再次查询该meta data 返回的结果就如下：

{
    "tsuid": "000004000001000008000002000009",
    "metric":{"uid":"000004","type":"METRIC","name":"cpu.system","description":"","notes":"","created":1562462940,"custom":null,"displayName":""},
    "tags": [{"uid":"000001","type":"TAGK","name":"host","description":"","notes":"","created":0,"custom":null,"displayName":""},{"uid":"000008","type":"TAGV","name":"web01.dal.mysite.com","description":"","notes":"","created":1562462940,"custom":null,"displayName":""},{"uid":"000002","type":"TAGK","name":"dc","description":"","notes":"","created":0,"custom":null,"displayName":""},{"uid":"000009","type":"TAGV","name":"dal","description":"","notes":"","created":1562462940,"custom":null,"displayName":""}],
    "description": "test api/uid/tsmeta description",
    "notes": "test api/uid/tsmeta notes",
    "created": 1562462940,
    "custom": {"owner": "Jane Doe", "assetTag": "12345", "department": "Operations" }, "units": "","retention": 0, "max": "NaN", "min": "NaN",
    "displayName": "test api/uid/tsmeta displayName", "dataType": "","lastReceived": 0,"totalDatapoints": 0
}

可见，进行修改的项已经生效，当然也可以对meta data的其他字段进行修改，这个example中仅仅对meta data的部分字段进行修改。

DELETE请求方式是删除meta data，请求body如下

{   "tsuid":"00002A000001000001"}

注意即使删除meta data，与其相关的时间序列数据是不会被删除的。

/api/uid/uidmeta

该接口类似于上一个接口/api/uid/tsmeta,但是这个接口是对uid的meta data进行查询、更新和删除，并且即使删除uid对应的meta data，与其相关的时间序列数据不会被删除。

• get，查询tsmeta
• post/put，修改tsmeta
• delete，删除tsmeta

一个post请求的body例子如下：

{
    "uid":"00002A",
    "type":"metric",
    "displayName":"System CPU Time",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    }
}

总结

关于opentsdb支持的http接口，本文基本都有进行介绍，但是本文的介绍仅仅只能作为参考，相比而言官网介绍得会更加全面。除此之外，博主还写了另一篇文章，用一些实际的example来对tsdb的一些重要特性进行详细介绍，可参见opentsdb写入和查询详解。