OpenTSDB数据写入HTTP API接口,统计总记录数

一.命名方案

OpenTSDB命名格式有点类似于RRD样式，只不过引入了标记(tags)，使得指标(metric)更具有代表性和通用性，可以共享许多独特的时间序列。通过标记的键值对组合来确定指标的唯一性，可以非常灵活的进行聚合函数的查询。

RRD如果要记录web1服务器的第一个CPU的用户空间使用量，命名的格式为web1.sys.cpu.0.user，如果有上千台服务器，每台多核CPU，那么需要命名很多来区别，如webN.sys.cpu.M.user。 对于OpenTSDB，可以这么命名sys.cpu.user host=web1,cpu=0。如果要汇总所有内核的值，只需sum:sys.cpu.user{host=web1}。如果要汇总上千台服务器的CPU值，只需sum:sys.cpu.user。比RRD命名格式更加的灵活通用。

因此，对于要监控的对象命名，要定义一个相同的共性，便于汇总，同时，要能很好的表达监控的项目。

二.指标命名规范

指标名称区分大小写，统一以小写字母命名。

指标名称不能含有空格。

指标名称只能含有下列字符：a-z,A-Z,0-9,-,_,.,/或Unicode字母。

指标名称尽量精短。

三.指标值规范

指标值可以是整数也可以是浮点数。

四.时间戳

UNIX时间戳，可以是秒或毫秒，必需是整数，且不能超过13位数。毫秒级的时间戳格式必需是1234567890123，最后三位代表毫秒数。对于应用程式生成的时间戳超过13位的，必需四舍五入至最高13位，否则报错。

由于OpenTSDB底层存储系统HBase目前只支持秒级别的存储，因此对于毫秒级别的数据会转换成秒。

五. 标记命名规范

标记是用来补充说明指标的，是指标的属性，来对指标进行差异性的定义。

标记是一对键值对。

每个指标至少有一个标记。通常是host=ip或host=hostname。

OpenTSDB最多支持8个标记。

标记区分大小写，统一以小写字母命名。

标记不能含有空格。

标记只能含有下列字符：a-z,A-Z,0-9,-,_,.,/或Unicode字母。

六. HTTP API接口

为了节省带宽，该接口允许在一个单一的请求中提交多个数据点数据。每个数据点单独处理，如果其中某个数据点有问题不会影响其他数据点的存储。

• 地址：

1. /api/put
2. /api/put?summary 调试，返回汇总信息
3. /api/put?details 调试，返回详细信息

• 方法：POST
• 格式：
  {

metric:     ”lvs.connection.active”,              //必需，字符串，指标名称

timestamp:        1234567890，                            //必需，整型，时间戳

value:        11.11,                                             //必需，整型、浮点型、字符串，指标值

tags: {“host”:”web1”}                                     //必需，对象，标记对

}

• 返回结果：

默认情况下，如果所有数据存储成功，响应一个204的状态码。如果有一个或多个数据点出错，返回400状态码和错误消息内容。

1. 请求地址是/api/put?summary时，返回：
   {

“failed”: 1,                            //整型，存储失败的数据点数量

“success”: 0                         //整型，存储成功的数据点数量

}

2. 请求地址是/api/put?details时，返回：
   {

"errors": [  …],             //数组，失败的数据点列表以及失败原因

"failed": 1,

"success": 0

}

七. HTTP API接口实例

1. /api/put

# curl -i -X POST -d '{"metric":"proc.loadavg.15m", "timestamp":1413015492, "value":8, "tags":{"host":"10.0.101.145"}}' http://10.0.101.145:4242/api/put

HTTP/1.1204NoContent

Content-Type:application/json;charset=UTF-8

Content-Length:0

2./api/put?summary

1 2 3 4 5 6

# curl -i -X POST -d '{"metric":"proc.loadavg.15m", "timestamp":1413015492, "value":8, "tags":{"host":"10.0.101.145"}}' http://10.0.101.145:4242/api/put?summary HTTP/1.1200OK Content-Type:application/json;charset=UTF-8 Content-Length:24   {"failed":0,"success":1}

3. /api/put?details

2 3 4 5 6

# curl -i -X POST -d '{"metric":"proc.loadavg.15m", "timestamp":1413015492, "value":8, "tags":{"host":"10.0.101.145"}}' http://10.0.101.145:4242/api/put?details HTTP/1.1200OK Content-Type:application/json;charset=UTF-8 Content-Length:36   {"errors":[],"failed":0,"success":1}

2 3 4 5 6

# curl -i -X POST -d '{"metric":"proc.loadavg.15m", "timestamp":1413015492, "value":8, "tags":{"host":"10.0.101.145"}}' http://10.0.101.145:4242/api/put?details HTTP / 1.1 200 OK Content - Type : application / json ; charset = UTF - 8 Content - Length : 36   { "errors" : [ ] , "failed" : 0 , "success" : 1 }

OpenTSDB是一个基于HBase上的实时监控信息收集和展示平台。它支持秒级数据采集metrics，使用HBase进行永久存储，可以做容量规划，并很容易的接入到现有的监控系统里。OpenTSDB可以从大规模的设备中获取相应的metrics并进行存储、索引以及服务，从而使得这些数据更容易让人理解，如web化，图形化等。

1. 安装

Opentsdb依赖Gnuplot，它 是一个命令行的交互式绘图工具。用户通过输入命令，可以逐步设置或修改绘图环境，并以图形描述数据或函数，使我们可以借由图形做更进一步的分析。

1	yum install - y gnuplot

Opentsdb目前有现成的rpm、deb打包，非常方便。下载链接：https://github.com/OpenTSDB/opentsdb/releases .下面我们安装rpm。

1	yum localinstall opentsdb - 2.0.1.noarch.rpm

配置

1 2 3 4 5 6 7

vim / etc / opentsdb / opentsdb .conf #TSDB通讯的端口 tsd .network .port = 4242 #数据保存到保存到HBase表下 tsd .storage .hbase .data_table = tsdb #ZooKeeper Quorum tsd .storage .hbase .zk_quorum = hadoop01 : 2181 , hadoop02 : 2181 , hadoop03 : 2181

配置完成后，我们通过下面命令在HBase中建立opentsdb所需的表。默认情况下opentsdb建立的HBase表启用了lzo压缩。需要开启Hadoop中的lzo压缩支持， 这里我们直接在下面脚本中把COMPRESSION的支持关闭：

1 2	vim / usr / share / opentsdb / tools / create_table .sh COMPRESSION = NONE

然后在HBase用户下执行下面脚本,在HBase中create所需的几张表。

1 2 3 4 5 6 7 8 9 10 11 12 13 14

/ usr / share / opentsdb / tools / create_table . sh Hbase :: Table - tsdb - uid create 'tsdb' ,    { NAME = > 't' , VERSIONS = > 1 , COMPRESSION = > 'NONE' , BLOOMFILTER = > 'ROW' } 0 row ( s ) in 0.4220 seconds Hbase :: Table - tsdb create 'tsdb-tree' ,    { NAME = > 't' , VERSIONS = > 1 , COMPRESSION = > 'NONE' , BLOOMFILTER = > 'ROW' } 0 row ( s ) in 0.4140 seconds Hbase :: Table - tsdb - tree create 'tsdb-meta' ,    { NAME = > 'name' , COMPRESSION = > 'NONE' , BLOOMFILTER = > 'ROW' } 0 row ( s ) in 0.4200 seconds Hbase :: Table - tsdb - meta

启动tsd(Time Series Daemon)服务，该命令有一些常用参数，会覆盖/etc/opentsdb/opentsdb.conf中的配置。参数列表如下：

1 2 3 4 5 6 7 8 9 10 11 12 13

Usage : tsd -- port = PORT -- staticroot = PATH -- cachedir = PATH Starts the TSD , the Time Series Daemon -- async - io = true | false Use async NIO ( default true ) or traditionalblocking io -- auto - metric         Automatically add metrics to tsdb as they are inserted .    Warning : this may cause unexpected metrics to be tracked -- cachedir = PATH       Directory underwhich to cache result of requests . -- flush - interval = MSEC Maximum time for which a new data point canbe buffered ( default : 1000 ) . -- port = NUM             TCPport to listen on . -- staticroot = PATH     Web root from which toserve static files ( / s URLs ) . -- table = TABLE         Nameof the HBase table where to store the time series ( default : tsdb ) . -- uidtable = TABLE       Name of theHBase table to use for Unique IDs ( default : tsdb - uid ) . -- worker - threads = NUM   Number for async io workers ( default : cpu * 2 ) . -- zkbasedir = PATH       Path underwhich is the znode for the - ROOT - region ( default : / hbase ) . -- zkquorum = SPEC       Specificationof the ZooKeeper quorum to use ( default : localhost ) .

那么我们通过14242端口启动TSD。

1 2 3

sudo - u hbase tsdb tsd -- port 14242 …… 2015 - 03 - 12 17 : 04 : 52 , 253 INFO    [ main ] TSDMain : Ready to serve on / 0.0.0.0 : 14242

OK！下面我们打开URL：http://debugo01:14242/

Opentsdb已经安装成功！

2. OpenTSDB设计探索

在OpenTSDB中，有下面一个基本的概念：
Metric：一个可测量的单位的标称。metric不包括一个数值或一个时间，其仅仅是一个标签，包含数值和时间的叫datapoints，metric是用逗号连接的不允许有空格，例如：proc.loadavg.5m
Timestamp：一个绝对时间戳值。
Tags：tag描述被测量的实体，Tags由tag key和tag value组成，前者表示一个分组，后者表示一个特定的项。
Data Point：可以被记录为某一个Timestamp的一个数值。
Time Series：一个metric的带有多个tag的data point集合。
UID：在OpenTSDB中，每一个metric、tagk或者tagv在创建的时候被分配一个唯一标识叫做UID，他们组合在一起可以创建一个序列的UID或者TSUID。在OpenTSDB的存储中，对于每一个metric、tagk或者tagv都存在从0开始的计数器，每来一个新的metric、tagk或者tagv，对应的计数器就会加1。
TSUID。当一个data point被写到OpenTSDB时，其row key格式为： [… ]，不考虑时间戳的话，将其余部分都转换为UID，然后拼在一起，就可以组成为TSUID。在OpenTSDB中，所有数据存储在一张叫做tsdb的表中，这是为了充分利用hbase有序和region分布式的特点。所有的值都保存在唯一列簇t中。TSD启动后会接收到监控数据，包括指标（metric_uid）、时间戳、数据、tag标签，tag标签包括tag名称ID和tag值ID。
根据HBase rowkey有序的原则，rowkey为 [… ]，UID默认编码为3 Bytes，而时间戳为4 Bytes编码。例如：proc.loadavg.5m 1292148123 42 host=debugo01
对于指标proc.loadavg.5m的ID为：[0, 0, 1], 标签名称的ID为：[0, 0, 1] debugo01标签值的ID为：[0, 0, 1]，他们组成rowkey：

1 2 3 4 5

[ 0 , 0 ,    1 , 77 , 4 , - 99 , 32 , 0 , 0 , 1 , 0 , 0 ,    1 ] ` -- -- -- - '  `------------'    ` -- -- - '  `------' metric ID   base timestamp   name ID   value ID                              ` -- -- -- -- -- -- -- -'                                  first tag

由此可见，对于metric + tags相同的数据都会连续存放，且metic相同的数据也会连续存放，这样对于scan以及做aggregation都非常有帮助。
Opentsdb使用一个单独的较小的表叫做tsdb-uid用来存储UID映射，包括正向的和反向的。存在两列簇，一个列簇叫做name用来将一个UID映射到一个字符串，另一个列族叫做id，用来将字符串映射到UID。列簇的每一行都至少有以下三列中的一个：
metrics 将metric的名称映射到UID
tagk 将tag名称映射到UID
tagv 将tag的值映射到UID

3. 使用OpenTSDB

首先创建metrics，命令会输出它的UID。

1 2	# sudo -u hbase tsdb mkmetric proc.loadavg.1m metrics proc . loadavg . 1mproc.loadavg.1m : [ 0 , 0 , 1 ]

编写数据加载脚本，脚本来自http://scm.zoomquiet.io/data/20131204123732/index.html

1 2 3 4 5 6 7 8 9 10 11

cat > loadavg - collector .sh << \ EOF #!/bin/bash set - e while true ; do awk - v now = ` date + % s ` - v host = ` hostname ` \ '{ print "put proc.loadavg.1m " now " " $1" host=" host;}' / proc / loadavg    sleep 15 done | nc - w 30 debugo01 14242 EOF chmod + x loadavg - collector .sh nohup . / loadavg - collector .sh &

每隔15秒会输出如下信息到tsd

1 2	put proc . loadavg . 1m 1288946927 0.36 host = debugo01 …

通过Scan UID表可以找到它们对应的UID。

1 2 3

\ x00 \ x00 \ x01                     column = name : metrics , timestamp = 1426212849709 , value = proc . loadavg . 1m          \ x00 \ x00 \ x01                     column = name : tagk , timestamp = 1426214303614 , value = host                                        \ x00 \ x00 \ x01                     column = name : tagv , timestamp = 1426214303641 , value = hadoop01

在Web页面中输入相应的metrics，可以得到数据的图展示：

^^

OpenTSDB所有的配置都在 link. 这里列出来的配置基本都有默认值，但是有些需要根据环境和性能做出改变，具体如下表：

---

配置项	默认值	描述	修改值
tsd.core.preload_uid_cache	false	是否在TSD启动的时候，预热UID缓存数据，为了提升性能，需要开启	true
tsd.core.auto_create_metrics	false	一个新的metric存入tsdb时，是否自动为其生成UID，如果true,存入成功，反之，失败。(按照最大优化性能的目标来说，应该预先为所有的metric生成UID，但是实际中预先不知道所有的metric,所以这个值需要设置为true)	true
tsd.http.cachedir	无	tsd写临时文件的目录	根据实际环境设置，比如/tmp/opentsdb
tsd.http.request.enable_chunked	false	Http写入数据时是否支持一次写入大批量的数据	true
tsd.http.request.max_chunk	4096	写入的批量数据的上限	根据需要增大，比如65535
tsd.http.staticroot	无	opentsdb页面的静态资源文件目录	安装目录下 ./build/staticroot
tsd.network.port	无	tsd读写数据的端口	根据实际配置 比如9099
tsd.query.timeout	0	tsd查询的timeout,如果为0,则不会timeout	合理配置。 比如200
tsd.storage.enable_appends	false	2.2版本，tsd 写数据到HBase有两种方式，一种是每来一条数据append到hbase, 一种是先缓存大量数据到tsd内存，然后进行compaction，一些性写入。推荐Append方式	true
tsd.storage.enable_compaction	true	append打开，这种就关闭	false
tsd.storage.fix_duplicates	false	相同时间存储相同metric的时候(重复数据)，最新写入的覆盖前面的值	true
tsd.storage.hbase.zk_basedir	/hbase	hbase 的zk的目录	根据实际配置
tsd.storage.hbase.zk_quorum	localhost	hbase 的zk地址	根据实际配置

实际使用中，还需要根据metric的具体情况调整一些配置项，比如salt, uid.width等。

参考

http://scm.zoomquiet.io/data/20131204123732/index.html
http://www.cnblogs.com/gsblog/p/4029894.html

2 3 4 5 6

# curl -i -X POST -d '{"metric":"proc.loadavg.15m", "timestamp":1413015492, "value":8, "tags":{"host":"10.0.101.145"}}' http://10.0.101.145:4242/api/put?details HTTP / 1.1 200 OK Content - Type : application / json ; charset = UTF - 8 Content - Length : 36   { "errors" : [ ] , "failed" : 0 , "success" : 1 } 统计总记录数： 因为metric必填，所以只能循环统计相加 参数类似如下： { "start": 1508428800, "end":1509168535, "queries": [ { "aggregator": "sum", "metric": "meter.current.phase.b",         "downsample": "0all-count" }] }