写在前面,这里是补充宇毅的博客内容翻译几篇文档,补充下java代码的一些实现,参考文献和其他文章列表放在末尾
翻译原文档http://opentsdb.net/docs/build/html/api_http/query/index.html
这篇文章是接上篇OpenTSDB的/ API / query(opentsdb的查询的api)简介(一)https://blog.csdn.net/jyj1100/article/details/81326660
这篇文章讲的是http查询需要的api,通过以下的结构可以实现查询和返回。尤其是子查询这种结构,与UI介绍的有很大区别,值得注意。建议和文章《OpenTSDB 查询介绍——opentsdb关于查询的基础知识和UI操作》对比来看https://blog.csdn.net/jyj1100/article/details/81324017
过滤器
OpenTSDB是2.2的新功能,包括跨标签键和值组合的扩展和可插入过滤器。有关TSD中加载的过滤器列表,请参阅/ api / config / filters。有关内置过滤器的说明,请参阅查询过滤器。过滤器可用于查询字符串和POST格式的查询。允许在同一标记键上使用多个过滤器,并且在处理时,它们将进行AND运算,例如,如果我们有两个过滤器host=literal_or(web01)
并且host=literal_or(web02)
查询将始终返回空。如果同一个标记键包含两个或更多个过滤器,而另一个没有,则另一个不启用,则对于该标记键上的所有过滤器,group by实际上将为true。与过滤器相关的POST查询字段包括:
名称 | 数据类型 | 是否为必须 | 描述 | 默认 | 例 |
---|---|---|---|---|---|
type | String | 是 | 要调用的过滤器的名称。请参见/ api / config / filters | regexp | |
tagk | String | 是 | 用于调用过滤器的标记键 | host | |
filter | String | 是 | 要评估的过滤器表达式,并取决于所使用的过滤器 | web.*.mysite.com | |
groupBy | Boolean | 否 | 是否按过滤器匹配的每个值对结果进行分组。默认情况下,与筛选器匹配的所有值都将聚合到一个系列中。 | false | true |
对于URI查询,该类型在括号中的过滤器表达式之前。格式是<tagk>=<type>(<filter_expression>)
。结果是否分组取决于过滤器所在的大括号。现在每个度量标准查询支持两个花括号。第一组是按过滤器分组,第二组是过滤器的非组,例如{host=wildcard(web*)}{colo=regexp(sjc.*)}
。这指定了colo与正则表达式“sjc。”匹配且主机标记值以“web”开头并且结果按主机分组的所有度量。如果您只想在没有分组的情况下进行过滤,那么第一个卷曲集必须为空,例如`{}{host=wildcard(web),colo=regexp(sjc.)}`。这指定了nany指标,其中colo与正则表达式“sjc。”匹配,主机标记值以“web”开头,结果未分组。
注意
正则表达式,具有前/后/入内定义的通配符过滤器或具有许多值的文字过滤器可能导致查询返回较慢,因为必须将每行数据解析为其字符串值然后进行处理。
注意
向OpenTSDB 2.2或更高版本提交JSON查询时,请使用tags
OR filters
。只有一个会生效,顺序是不确定的,因为JSON解析器可能会先反序列化一个。我们建议您使用过滤器以备将来查询。
过滤转化次数
POST查询tags
映射中的值和按 URI大括号查询的组将自动转换为过滤器,以提供与现有系统的向后兼容性。自动转换包括:
例 | 描述 |
---|---|
<tagk>=* | 通配符过滤器,有效地确保标记键存在于系列中 |
<tagk>=value | 区分大小写的字符OR过滤器 |
<tagk>=value1|value2|valueN | 区分大小写的字符OR过滤器 |
<tagk>=va* | 不区分大小写的通配符过滤器。带有任何其他字符串的星号(星号)现在变为通配符过滤器快捷方式 |
百分(Percentiles)
使用OpenTSDB 2.4,数据库可以存储和查询直方图或摘要数据,以进行准确的百分位数计算(与内置百分位数聚合器相反)。如果在查询中请求一个或多个百分位数,则TSD将显式扫描存储器以获取直方图(任何编解码器类型),并且将忽略常规数字数据。可以同时计算多个百分位数,例如,通过在一个查询中获取99.999,99.9,99.0和95百分位数可能是常见的。注意对于某些插件实现(例如Yahoo Data Sketches实现),百分位列表必须按降序排序。percentiles[99.999, 99.9, 99.0, 95.0]
结果与常规数据点时间序列相同,以与现有图形系统兼容。但是,百分位数将附加到度量标准名称,并且将返回每个分组和百分位数的时间序列。例如,如果用户要求percentiles[99.9,75.0]
超过sys.cpu.nice
指标,则结果将包含时间序列sys.cpu.nice_pct_99.9
和sys.cpu.nice_pct_75.0
。
注意
目前,直方图数据上唯一支持的下采样和聚合运算符是SUM
。这是最常见的用例,因为您可能希望通过colo对服务器的所有主机进行分组,在这种情况下,我们将对所有直方图求和,然后根据总和计算百分位数。同样,如果要对每小时进行缩减采样,则会对分组的直方图再次求和,最后提取百分位数。
度量标准查询字符串格式
度量标准查询字符串子查询的完整规范如下:
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>]}]
起初它可能有点令人生畏,但你可以把它分解成组件。如果您感到困惑,请尝试使用内置GUI以您希望的方式绘制图形,然后查看URL以查看查询的格式。对任何表单字段的更改将更新URL(您可以实际复制和粘贴以与其他用户共享)。有关示例,请参阅查询示例。
TSUID查询字符串格式
TSUID查询比度量标准查询更简单。只需传递由逗号分隔的一个或多个十六进制编码的TSUID列表
tsuid=<aggregator>:<tsuid1>[,...<tsuidN>]
示例查询字符串请求
http://localhost:4242/api/query?start=1h-ago&m=sum:rate:proc.stat.cpu{host=foo,type=idle}
http://localhost:4242/api/query?start=1h-ago&tsuid=sum:000001000002000042,000001000002000043
示例内容请求
有关请求信息,请参阅序列化程序文档:HTTP Serializers。以下示例适用于默认的JSON序列化程序
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"tags": {
"host": "*",
"dc": "lga"
}
},
{
"aggregator": "sum",
"tsuids": [
"000001000002000042",
"000001000002000043"
]
}
]
}
使用过滤器查询
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"filters": [
{
"type":"wildcard",
"tagk":"host",
"filter":"*",
"groupBy":true
},
{
"type":"literal_or",
"tagk":"dc",
"filter":"lga|lga1|lga2",
"groupBy":false
}
]
},
{
"aggregator": "sum",
"tsuids": [
"000001000002000042",
"000001000002000043"
]
}
]
}
响应
为查询生成的输出很大程度上取决于所选的序列化程序HTTP Serializers。请求可能导致返回多组数据,特别是如果请求包括多个查询或请求分组。响应中每个数据集包含的一些常见字段将是:
名称 | 描述 |
---|---|
metric | 为时间系列检索的度量标准的名称 |
tags | 仅当结果针对单个时间系列时,才会返回标记列表。如果聚合了结果,则此值可能为null或空映射 |
aggregatedTags | 如果结果集中包含多个时间序列,即它们已聚合,则会显示在所有时间序列中共同找到的标记名称列表。 |
dps | 聚合器处理后检索的数据点。每个数据点由时间戳和值组成,格式由序列化程序确定。 |
annotations | 如果查询在请求的时间跨度内检索了时间序列的注释,则它们将在此组中返回。每个时间序列的注释将合并为一个集合并按其排序start_time 。聚合器函数不会影响注释,将为跨度返回所有注释。 |
globalAnnotations | 如果用户请求,查询将在时间跨度内扫描全局注释,并在此组中返回结果 |
除非查询出错,否则通常会收到200
包含内容的状态。但是,如果您的查询找不到任何数据,它将返回一个空结果集。对于JSON序列化程序,结果将是一个空数组:
[]
对于JSON序列化程序,时间戳将始终为Unix纪元样式整数,后跟值作为整数或浮点。例如,默认输出为"dps"{"<timestamp>":<value>}
。默认情况下,时间戳将以秒为单位。如果msResolution
设置了标志,则时间戳将以毫秒为单位。
聚合默认响应示例
[
{
"metric": "tsd.hbase.puts",
"tags": {},
"aggregatedTags": [
"host"
],
"annotations": [
{
"tsuid": "00001C0000FB0000FB",
"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": 1365966062
}
],
"globalAnnotations": [
{
"description": "Notice",
"notes": "DAL was down during this period",
"custom": null,
"endTime": 1365966164,
"startTime": 1365966064
}
],
"tsuids": [
"0023E3000002000008000006000001"
],
"dps": {
"1365966001": 25595461080,
"1365966061": 25595542522,
"1365966062": 25595543979,
...
"1365973801": 25717417859
}
}
]
聚合数组响应示例
[
{
"metric": "tsd.hbase.puts",
"tags": {},
"aggregatedTags": [
"host"
],
"dps": [
[
1365966001,
25595461080
],
[
1365966061,
25595542522
],
...
[
1365974221,
25722266376
]
]
}
]
示例多集响应
对于以下示例,两个TSD正在运行,查询为:http://localhost:4242/api/query?start=1h-ago&m=sum:tsd.hbase.puts{host=*}
。这将返回两个显式时间系列。
[
{
"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
}
}
]
显示摘要和查询的示例
请参阅查询详细信息和统计信息
[
{
"metric": "tsd.hbase.puts",
"tags": {},
"aggregatedTags": [
"host"
],
"query": {
"aggregator": "sum",
"metric": "tsd.hbase.puts",
"tsuids": null,
"downsample": null,
"rate": true,
"explicitTags": false,
"filters": [
{
"tagk": "host",
"filter": "*",
"group_by": true,
"type": "wildcard"
}
],
"rateOptions": null,
"tags": { }
},
"dps": {
"1365966001": 25595461080,
"1365966061": 25595542522,
"1365966062": 25595543979,
...
"1365973801": 25717417859
}
},
{
"statsSummary": {
"datapoints": 0,
"rawDatapoints": 56,
"aggregationTime": 0,
"serializationTime": 20,
"storageTime": 6,
"timeTotal": 26
}
}
]
OpenTSDB系列
OpenTSDB的/ API / PUT(opentsdb的输入的api)简介https://blog.csdn.net/jyj1100/article/details/81323705
OpenTSDB使用/ API / PUT进行数据存储的java实现https://blog.csdn.net/jyj1100/article/details/81330623
(转)opentsdb查询的简介——基础知识和UI操作https://blog.csdn.net/jyj1100/article/details/81324017
OpenTSDB的/ API / query(opentsdb的查询的api)简介(一)https://blog.csdn.net/jyj1100/article/details/81326660
OpenTSDB的/ API / query(opentsdb的查询的api)简介(二)https://blog.csdn.net/jyj1100/article/details/81329290
OpenTSDB使用/ API / query进行数据查询的java实现https://blog.csdn.net/jyj1100/article/details/81347817
其他OpenTSDB系列文章见
OpenTSDB系列目录https://blog.csdn.net/jyj1100/article/details/83450282