OpenTsdb官方文档----查询或读取数据

  OpenTSDB提供了许多提取，处理和分析数据的方法。数据可以通过CLI工具，HTTP API来查询，并且作为为一个GnuPlot图形输出展示。开源工具如Grafana和Bosun可以访问TSDB的数据。使用OpenTSDB的基于标签的系统进行查询可能有点棘手，所以仔细阅读本文档并查看以下页面以获取更深入的信息。此页面上的示例查询遵循HTTP API格式。

查询组件

  OpenTSDB提供了多个工具和接口允许随着时间推移的多样化查询定义。原始语法支持简单的过滤，聚合和降采样。后来的版本增加了对函数和表达式的支持。一般来说，每个查询都有以下组件：

参数	数据类型	Required	描述	示例
Start Time	String或Integer	Required	查询的开始时间。可以是绝对时间或相对时间	24h-ago
End Time	String或Integer	Optional	查询的结束时间。如果未提供结束时间，则当前时间即结束时间	1h-ago
Metric	String	Required	系统中的metric全名。必须是全名并且大小写敏感	sys.cpu.user
Aggregation Function	String	Required	用于组合多个时间序列的数学函数（即如何合并一个组中的时间序列值）	sum
Filter	String	Optional	过滤标签值以减少查询或组中挑选出的时间序列的数量，并聚合各个标签	host=*,dc=lax
Downsampler	String	Optional	可选的时间间隔和函数，用于减少随时间返回的数据点的数量	1h-avg
Rate	String	Optional	用于计算结果的每秒变化率	rate
Functions	String	Optional	数据处理函数，如附加过滤、时间切换等	highestMax(…)
Expressions	String	Optional	数据处理函数，例如将一个序列分化成另一个序列	(m2/(m1 + m2))*100

时间

  支持人类可读的绝对时间戳或Unix风格的整型格式。相对时间通常用来刷新仪表板。当前，所有的查询可以覆盖单一的时间段。未来我们希望提供一个偏移查询参数，这个参数可以在不同的时间段内对指标进行聚合或者绘制图表，比如上周到1年前的比较。

  虽然OpenTSDB可以以毫秒分辨率（精度）存储数据，但大多数查询将以秒级分辨率返回数据，以提供对现有工具的向后兼容性。除非使用指定了降采样算法的查询，否则将使用查询中指定的相同聚合函数将数据自动降采样到1秒。这样，如果多个数据点存储在一个给定的秒数，它们将被聚合并正确返回一个正常的查询。

  要以毫秒分辨率提取数据，请使用/api/query接口并指定msResolution（ms也可以，但不推荐）JSON参数或查询字符串标识，它将绕过采样（除非指定），并以Unix epoch毫秒分辨率返回所有时间戳。另外，scan命令行工具将返回写入存储的时间戳。

过滤器

  每个时间序列由一个指标与一个或多个标签名称/值对组成。在OpenTSDB中，过滤器应用于标签值（当前的TSDB不提供对指标或标签名称的过滤）。由于过滤器在查询中是可选的，如果您仅仅请求指标名称，则具有任意数值或标签值都会在聚合结果中返回。过滤器与SQL语句中的Where子句相似。例如，我们存储了如下数据集：

sys.cpu.user host=webserver01,cpu=0 1356998400 1
sys.cpu.user host=webserver01,cpu=1 1356998400 4
sys.cpu.user host=webserver02,cpu=0 1356998400 2
sys.cpu.user host=webserver02,cpu=1 1356998400 1

  制定一个简单的查询，至少带有起始时间，聚合器和指标，如：

start=1356998400&m=sum:sys.cpu.user

  我们会得到一个在1356998400时间点上将4个时间序列聚合到一组，值为8。
  如果我们想缩放一个特定序列或一系列序列，可以使用过滤器。例如，我们可以通过在host标签上过滤：

start=1356998400&m=sum:sys.cpu.user{host=webserver01}

  该查询将会返回一个值5，仅包含时间序列host=webserver01。要深入到特定的时间序列，必须包含序列的所有标签，如查询:

start=1356998400&m=sum:sys.cpu.user{host=webserver01,cpu=0}

  将会返回1。

聚合

  OpenTSDB的一个强大功能是能够将多个时间序列的即时聚合集成到一组数据点中。原始数据始终可用于存储，但我们可以通过有意义的方式快速提取数据。聚合函数是将单个时间戳的两个或多个数据点合并为单个值的方法。

  注意：
  OpenTSDB默认会聚合数据，并且需要每个查询都有一个聚合运算符。每个聚合器必须处理多个序列的缺失或不同时间戳中的数据点。这通过插值来执行的，如果用户不知道TSDB在做什么，可能会在查询时导致意外的结果。

降采样

  OpenTSDB可以摄取大量数据，即使仅提取给定时间序列中每秒一个数据点也是如此。因此查询可能会返回大量的数据点，从API访问大量点的查询结果可能会消耗许多带宽。高频率的数据很容易压倒Javascript图形库，因此可以选择使用GnuPlot。由GUI创建的图形难以阅读，导致浓密的折线，如下图所示：

  查询时可以使用降采样来减少返回的数据点数量，以便您可以从图表中提取更好的信息或通过连接传递更少的数据。降采样需要一个聚合函数和一个时间间隔。聚合函数用于通过适当的数学函数计算指定区间内所有数据点上的新数据点。例如，如果使用sum聚合，则间隔内的所有数据点将会一起累加为单个值。如果选择avg，则会返回间隔内所有数据点的平均值。
使用降采样，我们可以清理前面的图，以得到更有用的东西：

Rate

  许多数据源以不断递增的计数器的形式返回值。一个例子是一个网站点击计数器。当您启动Web服务器时，它的计数器可能为0。五分钟后，该值可能为1,024。再过五分钟后可能是2,048。计数器的图形是一条直线且向右倾斜，这样的图并不总是非常有用。OpenTSDB提供了一个rate转换函数，用于计算值随时间变化的变化率。这会将计数器转换为带有尖峰的折线（曲线），以便在活动发生时向您展示且更有用。
该比率是这些值的一阶导函数。它被定义为(v2 - v1) / (t2 - t1)，时间以秒为单位。因此你会得到每秒的变化率。目前，毫秒级值之间的变化率默认为每秒计算。

  OpenTSDB 2.0支持特殊的单调递增计数器数据处理，包括设置“翻转”（越界）值和抑制异常波动的能力。当在查询中指定counterMax值时，如果数据点接近该值并且之后的点小于先前的值，则将使用最大值来计算给定两个点的准确率。例如，如果我们用2个字节记录整数计数器，则最大值将是65,535。如果在t0值是64000，在t1值是 1000，每秒所得到的速率将被作为计算-63000。然而我们知道，计数器可能会翻转，因此我们可以将最大值设置为65535，现在计算65535 - t0 + t1将会返回给我们2535。

  跟踪计数器中数据的系统通常在重新启动时恢复为0。发生这种情况时，如果使用最大计数器功能，我们可能会得到一个虚假的结果。例如，如果计数器在t0达到2000，同时有人重新启动服务器时，在t1下一个值可能会500。如果我们设定最大值65535，那么结果就是65535 - 2000 + 500返回64035给我们。如果正常速度是每秒几个点，这个特定的尖峰，在30s中的数据点之间，将创建一个速率尖峰2134.5！为了避免这种情况，我们可以设置resetValue，当速率超过这个值时，返回一个值为0数据点以避免任何一个方向上出现尖峰。对于上面的例子，如果我们知道，速度几乎从来没有超过100，我们可以配置resetValue为100，并且当上面的数据点被计算时，它将返回0而不是2,134.5。默认值0表示重置的值将被忽略，不会抑制rates。（不会影响rates）

运算顺序

  了解运算顺序非常重要。返回查询结果时，以下是处理的顺序：
  1. 过滤
  1. 分组
  1. 降采样
  1. 插值
  1. 聚合
  1. Rate转换
  1. 函数
  1. 表达式

下一篇：
理解指标和时间序列