查询或读取数据

OpenTSDB 提供了多种提取，操纵和分析数据的方法。可以通过 CLI 工具，HTTP API 查询数据，并将其视为 GnuPlot 图形。 Grafana和Bosun之类的开源工具也可以访问 TSDB 数据。使用 OpenTSDB 的基于标签的系统进行查询可能有些棘手，因此请通读本文档，并查看以下页面以获取更深入的信息。此页面上的示例查询遵循 HTTP API 格式。

该页面提供了典型查询组件的快速概述。有关每个组件的详细信息，请参见上面的文本或目录中引用的页面。

Query Components

OpenTSDB 提供了许多工具和端点，这些工具和端点允许随着时间的推移不断 Developing 的各种查询规范。原始语法允许进行简单的过滤，聚合和下采样。更高版本增加了对函数和表达式的支持。通常，每个查询具有以下组件：

Parameter Date Type Required Description Example
Start Time 字符串或整数 Required 查询的开始时间。这可以是绝对时间或相对时间。有关详情，请参见日期和时间 24h-ago
End Time 字符串或整数 Optional 查询的结束时间。如果未提供结束时间，则将使用 TSD 上的当前时间。有关详情，请参见日期和时间。 1h-ago
Metric String Required 系统中度量标准的全名。必须为全名，并且始终区分大小写 sys.cpu.user
Aggregation Function String Required 用于组合多个时间序列的 math 函数(即，如何在一个组中合并时间序列) 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

Times

支持人类可读格式或 Unix 样式整数的绝对时间戳。相对时间可用于刷新仪表板。当前，所有查询都能够覆盖单个时间 Span。将来，我们希望提供一个偏移量查询参数，该参数将允许在不同时间段(例如，将上周与一年前进行比较)汇总或绘制 Metrics 的图形。有关允许的内容的详细信息，请参见日期和时间。

尽管 OpenTSDB 可以存储毫秒级的数据，但默认情况下，查询将返回具有第二级分辨率的数据，以提供对现有工具的向后兼容性。如果您每秒存储多个数据点，请确保发出的任何查询都包括一个 1s-<func>下采样器以读取正确的数据。否则将发出不确定的值。

要以毫秒级的分辨率提取数据，请使用/api/query端点并指定msResolution(也可以使用ms，但不建议使用)JSON 参数或查询字符串标志，它将绕过采样(除非指定)，并以 Unix 纪元毫秒的分辨率返回所有时间戳。 。同样，scan命令行 Util 将返回存储中写入的时间戳。

Filters

每个时间序列都包含一个 Metrics 和一个或多个标签名称/值对。在 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处获得8的值，该值会将所有 4 个时间序列汇总并分组为一个。

如果要缩放到特定系列或系列集，可以使用过滤器。例如，我们可以通过start=1356998400&m=sum:sys.cpu.user{host=webserver01}过滤host标签。该查询将返回5的值，只包含host=webserver01的时间序列。要向下钻取特定的时间序列，您必须包括该时间序列的所有标签，例如查询start=1356998400&m=sum:sys.cpu.user{host=webserver01,cpu=0}将返回1。

Note

不一致的标签可能会在查询时导致意外结果。有关详情，请参见Writing Data。另请参见下面的“显式标签”。

有关详细信息，请阅读Query Filters文档。

Aggregation

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

Note

OpenTSDB 默认情况下会聚合数据，并且每个查询都需要一个聚合运算符。对于多个系列，每个聚合器必须在不同的时间戳上处理丢失或数据点。这是通过插值执行的，如果用户不知道 TSDB 在做什么，则可能在查询时导致意外结果。

有关详情，请参见Aggregation。

Downsampling

OpenTSDB 可以摄取大量数据，即使在给定的时间序列中每秒也可以摄取一个数据点。因此查询可能返回大量数据点。从 API 中访问带有大量点的查询结果可能会占用带宽。高频率的数据很容易使 Javascript 图形库不堪重负，因此选择使用 GnuPlot。 GUI 创建的图形可能难以阅读，从而导致粗线，例如以下图形：

可以在查询时使用降采样来减少返回的数据点的数量，以便您可以从图形中提取更好的信息或通过连接传递更少的数据。下采样需要 聚合 函数和 时间间隔 。聚合函数用于使用适当的 math 函数在指定间隔内计算所有数据点中的新数据点。例如，如果使用聚合sum，则该时间间隔内的所有数据点将加在一起成为一个值。如果选择avg，则将返回该间隔内所有数据点的平均值。

使用下采样，我们可以清理前面的图，以获得更有用的信息：

有关详细信息，请参见Downsampling。

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。但是，我们知道计数器很可能会翻转，因此我们可以将 max 设置为65535，现在计算结果为65535 - t0 + t1，我们得到2535。

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

操作 Sequences

了解操作 Sequences 很重要。返回查询结果时，将按以下 Sequences 进行处理：

首页