OpenTSDB接口使用简介

一、简介

---

    OpenTSDB提供基于HTTP的接口，以实现与外部系统的集成。 几乎所有OpenTSDB功能都可通过API访问，例如查询时间序列数据，管理元数据和存储数据点。 在使用各个接口之前，需要阅读相关API文档。

    目前OpenTSDB已经与很多开源的监控系统集成，这种情况下，对OpenTSDB的接口就相对简单些，只需要掌握一些相对固定的查询接口就可以实现来巡检、自定制可视化界面的功能。

    但如果是自行开发可视化界面和监控报警功能，就需要深入掌握OpenTSDB接口的请求方法和返回内容了。

    本文内容：

        1）OpenTSDB接口概览

        2）OpenTSDB常用接口详解

   

 

二、OpenTSDB接口概览

---

    OpenTSDB默认使用json序列号来显示请求和响应。    

    OpenTSDB目前无身份验证和访问控制系统，所以只能通过防火墙等方式来限制访问。

    和常规的http标准响应一样，OpenTSDB的接口返回也会有响应代码200、204、301等，以及400等错误代码。如果是错误，返回内容会包括code、message、details、trace等信息用以显示错误描述。

    通常情况下，OpenTSDB的接口是使用GET查询、POST更新及创建、PUT替换、DELETE删除，但为了方便开发，OpenTSDB的部分API也支持了通过GET、POST来完成PUT、DELETE操作，具体在各个API中会介绍。一般查询操作是通过GET字符串请求来查，但由于编码的复杂性，OpenTSDB的接口还支持POST+body content的形式进行访问。

    OpenTSDB的接口说明参见下面内容（大部分是结合官方文档和我自己的理解写的）。

 

三、OpenTSDB接口

---

• /s    GET、POST、PUT、DELETE    访问本地系统上的静态文件，响应将是所请求文件的内容，并配置了适当的HTTP标头 

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

• /api/aggregators     GET、POST     列出时间序列查询中使用的已实现聚合函数的名称

http://localhost:4242/api/aggregators

返回：

["min","sum","max","avg","dev"]

• /api/annotation     GET、POST、PUT、DELETE     提供了添加，编辑或删除存储在OpenTSDB后端中的注释的方法

请求内容：                    

Name	Data Type	Required	Description	Default	QS	RW	Example
startTime	Integer	Required	Unix时间戳，以秒为单位，标记应记录注释事件的时间		start_time	RW	1369141261
endTime	Integer	Optional	事件的可选结束时间（如果已完成或已解决）	0	end_time	RW	1369141262
tsuid	String	Optional	如果注释与时间序列关联，则为TSUID。 如果注释是针对全局事件，则此值可以为null或为空		tsuid	RW	000001000001000001
description	String	Optional	该事件的简要说明。 由于这可能出现在GnuPlot图表上，描述应该非常短，理想情况下应少于25个字符。		description	RW	Network Outage
notes	String	Optional	关于该事件的详细说明		notes	RW	Switch #5 died and was replaced
custom	Map	Optional	用于存储自定义字段和值的键/值映射	null		RW	See Below

http://localhost:4242/api/annotation?start_time=1369141261&tsuid=000001000001000001

{

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

}}

返回：

{

"tsuid": "000001000001000001",

"description": "Testing Annotations",

"notes": "These would be details about the event, the description is just a summary",

"custom": {

"owner": "jdoe",

"dept": "ops"

},

"endTime": 0,

"startTime": 1369141261}

• /api/config     GET、POST     返回有关TSD运行配置的信息。 它是只读的，不能用于设置配置选项

             /api/config/filters     用法相似， 列出了TSD加载的各种过滤器以及有关如何使用它们的一些信息

http://localhost:4242/api/config

{

"tsd.search.elasticsearch.tsmeta_type": "tsmetadata",

"tsd.storage.flush_interval": "1000",

"tsd.network.tcp_no_delay": "true",

...省略

}

• /api/dropcaches      GET、POST     清除OpenTSDB中缓存的内存数据。包括UID和名称的映射，映射内容包括 metrics, tag names 及tag values

Note

此接口不会清除存储图形和其他文件的磁盘上临时缓存。

http://localhost:4242/api/dropcaches

{

"message": "Caches dropped",

"status": "200"

}

• /api/put     POST     通过HTTP在OpenTSDB中存储数据，以替代Telnet接口。

    为了节省带宽，该接口允许客户端在单个请求中存储多个数据点。数据点不必以任何方式相关。每个数据点都是单独处理的，一个数据的错误不会影响其他数据的存储。这意味着如果您的请求有100个数据点，其中1个有错误，则仍会写入99个数据点，其中一个将被拒绝。

    API在处理完每个数据点之前不会返回。这意味着必须验证metric和tag/tag value，解析数据并将解析过的数据排队等待存储。如果put请求包含大量数据点，则API可能需要很长时间才能响应，特别是如果OpenTSDB必须将UID分配给tag名称或值。因此，限制每个请求的最大数据点数是个保证效率的好方法， 每个请求50个是一个相对较合适的配置。

Note

如果无法解析您提供的请求内容，此类JSON内容缺少引号或大括号，则将丢弃所有数据点。 API将返回错误，其中包含有关错误的详细信息。

Note

如果 tsd.mode 设置为 ro ，则 /api/put 端点将不可用，并且所有呼叫都将返回404错误。

请求的body内容中添加以下内容来更改请求的响应：

Name	Data Type	Required	Description	Default	QS	RW	Example
summary	Present	Optional	是否返回摘要信息	false	summary		/api/put?summary
details	Present	Optional	是否返回详细信息	false	details		/api/put?details
sync	Boolean	Optional	是否在返回结果之前等待数据刷新到存储。	false	sync		/api/put?sync
sync_timeout	Integer	Optional	在返回错误之前等待数据刷新到存储的超时（以毫秒为单位）。 发生超时时，使用该 details 标志将告知有多少数据点失败以及有多少数据点成功。 sync 还必须为此生效。 值为0表示写入不会超时。	0	sync_timeout		/api/put/?sync&sync_timeout=60000

请求的数据点内容：

Name	Data Type	Required	Description	Default	QS	RW	Example
metric	String	Required	存储的指标的名称			W	sys.cpu.nice
timestamp	Integer	Required	Unix时间戳，以秒或毫秒为单位。 时间戳不得包含非数字字符。			W	1365465600
value	Integer, Float, String	Required	要记录此数据点的值。 它 可以引用 或不引用，并且必须符合OpenTSDB值规则： ../../ user_guide / writing			W	42.5
tags	Map	Required	tag名称/tag值对的映射。 必须至少提供一对。			W	{"host":"web01"}

单个数据点请求：

{

"metric": "sys.cpu.nice",

"timestamp": 1346846400,

"value": 18,

"tags": {

"host": "web01",

"dc": "lga"

}}

多个数据点请求：

[

{

...略

},

{

...略

}]

响应：

{

"failed": 1,

"success": 0}

明细响应：

{

"errors": [

{

"datapoint": {

"metric": "sys.cpu.nice",

"timestamp": 1365465600,

"value": "NaN",

"tags": {

"host": "web01"

}

},

"error": "Unable to parse value to a number"

}

],

"failed": 1,

"success": 0}

 

 

• /api/rollup     POST     通过HTTP在OpenTSDB中存储汇总（ rollups）和/或预聚合数据。

    汇总和预聚合值是 /api/put 接口 的扩展，带有三个附加字段。下面列出了所有字段：

Name

Data Type

<