OpenTSDB使用总结-(3)

查询数据

功能介绍

从OpenTSDB数据库中查询数据。
URI

URI格式

POST {OpenTSDB URL}/api/query

请求

请求样例

{
    "start": 1504527820,
    "end": 1504557820,
    "queries": [
        {
            "aggregator": "sum",
            "metric": "cpu.system",
            "rate": "true",
            "filters": [
                {
                   "type":"regexp",
                   "tagk":"host",
                   "filter":"web[0-9]+.lax.mysite.com",
                   "groupBy":true
                },
                {
                   "type":"literal_or",
                   "tagk":"dc",
                   "filter":"lax|dal",
                   "groupBy":false
                },
            ]
        }
    ]
}

参数说明

表1 请求参数说明

名称	类型	是否必须	描述
start	Integer	是	起始时间，单位秒。查询结果包含该时间的值。说明：建议使用4334400秒到4291718400秒之间的时间，即从1970/02/20 12:00:00到2106/01/01 00:00:00，也可以为0。否则可能导致查询结果不正确。
end	Integer	否	结束时间，单位秒，默认值为OpenTSDB的当前系统时间。查询结果包含该时间的值。说明：建议使用4334400秒到4291718400秒之间的时间，即从1970/02/20 12:00:00到2106/01/01 00:00:00。否则可能导致查询结果不正确。
queries	Array	是	可以有多个查询，请参见[表2]。
delete	Boolean	否	如果为true,符合条件的查询结果数据都会被删除。说明：删除数据是以一小时的数据为单位的。即查询结果关联的所有小时的数据都会被删除。
noAnnotations	Boolean	否	是否返回注释信息。 true：不返回。false：返回。默认为false。
globalAnnotations	Boolean	否	是否返回时间跨度内的全局注释。 true：返回。false：不返回。默认为false。
showTSUIDs	Boolean	否	是否在结果中返回与时间序列关联的TSUID。 true：如果多个时间序列被聚合成一个集合，则多个TSUID将以排序方式返回。false：不返回。默认为false。
showSummary	Boolean	否	是否在结果中返回时间摘要，详细信息请参见http://opentsdb.net/docs/build/html/user_guide/query/stats.html true：返回。false：不返回。默认为false。
showStats	Boolean	否	是否在结果中返回详细时间，详细信息请参见http://opentsdb.net/docs/build/html/user_guide/query/stats.html true：返回。false：不返回。默认为false。
showQuery	Boolean	否	是否返回带查询结果的原始子查询。 true：返回。false：不返回。默认为false。
msResolution	Boolean	否	默认情况下，查询结果中的时间戳是以秒为单位的。如果设置为true，则查询结果中的时间戳以毫秒为单位。

表2 子查询参数说明

名称	类型	是否必须	描述
aggregator	String	是	聚合函数，请参见aggregator说明。
metric	String	是	指标项。
rate	Boolean	否	是否返回倾斜率。 true：返回。false：不返回。默认为false。
downsample	String	否	降时间精度采样，请参见downsample说明
filters	List	否	过滤器，可以设置多个过滤器，请参见表5。
explicitTags	Boolean	否	是否只返回filter指定的tag。 true：返回。false：不返回。默认为false。
useMultiGets	Boolean	否	是否使用MultiGet方式查询数据，默认为false。只有当“filters”的“type”为“literal_or”，同时“explicitTags”为“true”时才会起作用。

downsample说明-重采样

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

格式：

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

“Interval” ：时间数值，unit：时间单位，s秒，m分，h小时，d天。示例：1h ， 30m， 24h
“aggregator” :聚合策略，将一段时间点聚合为一个数据点的策略。参见[aggregator说明]。
“fill policy” : 补值策略，当使用aggreator计算一段时间内的汇聚值时，遇到中间缺少的数据点时，会使用一定的策略补充数据。补值策略请参见表4。

aggregator说明

aggregator在降精度downsample和多条时间线聚合时使用。通过算子将多个数据点汇聚成一个数据点。汇聚的算子请参见表3

表3-算子

算子	描述	补值方式
avg	平均值	线性插值
count	数据点数	补0
dev	计算标准偏差	线性插值
ep50r3	用R-3方法计算的50%都大于	线性插值
ep50r7	用R-7方法计算的50%都大于	线性插值
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

表4-补值策略参数

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

表5-filter参数

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

表6-filter-type参数

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

相应

响应样例

[
    {
        "metric": "tsd.hbase.puts",
        "tags": {
            "host": "tsdb-1.mysite.com"
        },
        "aggregatedTags": [],
        "dps": {
            "1365966001": 3758788892,
            "1365966061": 3758804070,
...
            "1365974281": 3778141673
        }
    },
    {
        "metric": "tsd.hbase.puts",
        "tags": {
            "host": "tsdb-2.mysite.com"
        },
        "aggregatedTags": [],
        "dps": {
            "1365966001": 3902179270,
            "1365966062": 3902197769,
...
            "1365974281": 3922266478
        }
    }
]

参数说明

表7 响应参数说明

名称	描述
metric	指标名
tags	未做聚合的tagv，如果存在聚合，这个值为空。
aggregateTags	如果存在聚合，显示做聚合操作的tagv。
dps	数据点对，数据点由时间戳和值组成并做了序列化。说明：如果值是浮点数，那么是以双精度（Double）方式进行显示，可根据需要转换为单精度（Float）或双精度（Double）浮点数。
annotations	注释信息
globalAnnotations	时间跨度内的全局注释