引言
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。
请求方式
- get - 查询单个annotation。
- post - 新增或者修改annotation。
- put - 新增或者替换annotation。
- 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。
直方图大体上分为两类，第一类是简单的分块直方图，第二类就是可以通过编码器和解码器定义的直方图。
- 简单分块直方图，请求体如下：
{
"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表示数值，需要注意的是区间一定需要连续 |
- 解编码定义的直方图请求体如下：
{
"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
该接口是查询最新数据，查询最新数据的方式有两种：
- Counter Method：该查询方式是基于data point counter的。
- 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的一些统计信息，出了该接口本身之外还包含了一些子接口：
- /api/stats/jvm:关于jvm的信息。
- /api/stats/query:256最近查询接口的信息。
- /api/stats/region_clients：hbase有关的信息。
- /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写入和查询详解。
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
