opentsdb接口文档

功能介绍：

从OPENTSDB数据库中查询数据。

一、请求参数：

表1：请求参数说明

名称	数据类型		必填	描述	缺省	Query String	示例
start	String, Integer		必填	起始时间。查询结果包含该时间的值。时间格式请参见“时间格式说明”		start	1h-ago
end	String, Integer		可选	结束时间，默认值为LEAP TSDB的当前系统时间。查询结果包含该时间的值。	now	end	1s-ago
queries	Array		必填	子查询，可以有多个。详情参见表2子查询		m
msResolution	Boolean		可选	默认情况下，查询结果中的时间戳是以秒为单位的。如果设置为true，则查询结果中的时间戳以毫秒为单位	false	msResolution	true
showSummary	Boolean		可选	查询结果是否显示汇总信息	false	show_summary	true
showStats	Boolean		可选	查询结果是否显示详细信息	false	show_stats	true
showQuery	Boolean		可选	查询结果是否返回原始子查询。如果查询请求包含多个子查询，使用此选项可用以判断各个结果集对应的子查询。 注意： 如果子查询中使用了通配符*，结果集中会产生大量重复结果。	false	show_query	true
useCalendar	Boolean		可选	Downsampling计算时是否使用时区日历。必须是JRE可以识别的时区名称。	false		true
timezone	String		可选	Downsampling计算时所使用的时区日历（如果使用的话）	UTC	timezone	Asia/Kabul

表2：子查询

名称	数据类型	必填	描述	缺省	示例
aggregator	String	必填	聚合函数名称。详情见“aggregator说明”		sum
metric	String	必填	指标项		sys.cpu.0
rate	Boolean	可选	是否返回变化率	false	true
rateOptions	Map	可选	计算变化率时可以使用的额外参数
downsample	String	可选	降低时间精度采样。详情见“downsample说明”		5m-avg
filters	List	可选	filter 根据 tags 对结果进行过滤，可以设置多个过滤器，详情见“Filter参数说明”
explicitTags	Boolean	可选	是否只返回包含且只包含filter指定的tags的时序。 例如： 若数据库中有两个时序数据，其中时序1包含3个tags = { tag1,tag2,tag3 }，时序2包含4个tags = { tag1,tag2,tag3,tag4 }。 当explicitTags=true后，若filter中指定了tag1,tag2,tag3的条件，则结果仅返回时序1；若filter中仅指定了tag1,tag2，则结果中不包含。 精确指定tags可有效提高查询效率。	false	true
percentiles	List	可选	返回数据的百分位数，输入参数为0-100的数值。 输入多个数值可同时返回多个百分位数。		[99.9, 95.0, 75.0]

 

二、时间格式说明：

1、相对时间格式：

<amount><time unit>-ago

 <amount> 表示时间值，<time unit>表示时间单位。比如1h-ago表示从现在开始的一小时之前。时间单位包括：

• ms - Milliseconds
• s - Seconds
• m - Minutes
• h - Hours
• d - Days (24 hours)
• w - Weeks (7 days)
• n - Months (30 days)
• y - Years (365 days)

2、绝对Unix时间格式：

Unix 格式的时间戳。比如1364410924表示 ISO 8601:2013-03-27T19:02:04Z。

3、绝对格式化时间：

支持以下格式的时间：

• yyyy/MM/dd-HH:mm:ss
• yyyy/MM/dd HH:mm:ss
• yyyy/MM/dd-HH:mm
• yyyy/MM/dd HH:mm
• yyyy/MM/dd

三、Aggregator说明：

Aggregator可在聚合多个时序和降低采样downsampling时使用，通过算子将多个数据点汇聚成一个数据点。

聚合算子请参见下表：

算子	描述	补值方式
avg	平均值	线性插值
count	数据点数	补0
dev	计算标准偏差	线性插值
ep50r3	用R-3方法计算的第50百分位	线性插值
ep50r7	用R-7方法计算的第70百分位	线性插值
ep75r3	用R-3方法计算的第75百分位	线性插值
ep75r7	用R-7方法计算的第75百分位	线性插值
ep90r3	用R-3方法计算的第90百分位	线性插值
ep90r7	用R-7方法计算的第90百分位	线性插值
ep95r3	用R-3方法计算的第95百分位	线性插值
ep95r7	用R-7方法计算的第95百分位	线性插值
ep99r3	用R-3方法计算的第99百分位	线性插值
ep99r7	用R-7方法计算的第99百分位	线性插值
ep999r3	用R-3方法计算的第99.9百分位	线性插值
ep999r7	用R-7方法计算的第99.9百分位	线性插值
first	取第一个值	-
last	取最后一个值	-
mimmin	最小值	补最大值
mimmax	最大值	补最小值
min	最小值	线性插值
max	最大值	线性插值
none	不做计算	补0
p50	第50百分位	线性插值
p75	第75百分位	线性插值
p90	第90百分位	线性插值
p95	第95百分位	线性插值
p99	第99百分位	线性插值
p999	第99.9百分位	线性插值
sum	求和	线性插值
zimsum	求和	补0

四、Downsample说明：

当查询的时间跨度很大，例如每秒都将温度作为数据写入LEAP TSDB，每个小时会产生3600条数据点，当查询一周的数据时，会返回604800个数据点。展示如此多数据会显得很乱，通常也不需要这样精确的数据。使用降精度的方式将一段时间的数据点聚合后当作一个数据点，比如将每个小时的数据聚合为1个数据点，这样就会只显示168个数据点。

格式：

<Interval><units>-<aggregator>[c][-<fill policy>]

• • Interval：时间数值。unit：时间单位，s秒，m分，h小时，d天。
  • aggregator：聚合策略。将一段时间内的数据点集聚合为一个数据点的策略。具体取值请参见“聚合算子”。
  • c：表示使用时区日历采样，可选项。此参数需要和timezone 参数配合使用，例如：&timezone=Asia/Kabul
  • fill policy：补值策略，可选项。当使用aggreator计算一段时间内的聚合值时，遇到中间缺少的数据点时，会使用一定的策略补充数据。补值策略如下表所示。

名称	描述
none	默认，不补值
nan	补NaN
null	补null
zero	补0

• • 示例

      1h-sum

      30m-avg-nan

      24h-max-zero

      1dc-sum

      0all-sum

五、Filter参数说明：

名称	类型	必填	描述	示例
type	String	是	filter类型，参见下表	regexp
tagk	String	是	要做filter的tag名	host
filter	String	是	filter的表达式值	web[0-9]+.lax.mysite.com
groupBy	Boolean	否	是否对tagv做groupBy，默认false	false

六、Filter类型：

名称	说明	示例
literal_or	tagv等于或者等于	host=literal_or(web01|web02|web03)
ilteral_or	tagv等于或者等于； 大小写敏感
not_literal_or	tagv不等于或者不等于	host=not_literal_or(web01|web02|web03)
not_iliteral_or	tagv不等于或者不等于； 大小写敏感
wildcard	tagv需满足的通配符	host=wildcard(*mysite.com)
iwildcard	与wildcard作用相反	host=iwildcard (*mysite.com)
regexp	tagv需满足正则表达式	regexp(web[0-9].mysite.com)

七、Filter的Query String格式：

 <tagk>=<type>(<filter_expression>)

例如：{host=wildcard(web*)}

结果集是否group取决于filter在哪个大括号里面，query string里可以有两个大括号，第一个是group filter，第二个是non-group filter。比如： {host=wildcard(web*)}{colo=regexp(sjc.*)}表示该filter需要分组；如果只需要non-group filter，第一个大括号必须置空，比如：{}{host=wildcard(web*),colo=regexp(sjc.*)}表示该filter不分组。

八、Query String查询格式：

当使用GET方式查询时，Query String的完整格式如下：

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>]}]

参见示例

以便于理解。

 

下章介绍：tsdb查询示例