OpenTSDB 查询数据

Querying or Reading Data

原文地址 http://opentsdb.net/docs/build/html/user_guide/query/index.html

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

• Understanding Metrics and Time Series
• Dates and Times
• Query Filters
• Aggregation
• Downsampling
• Query Performance
• Query Examples
• Query Details and Stats

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

Query Components

OpenTSDB 提供了许多工具和端点，允许随时间演变的各种查询规范。 原始语法允许简单的过滤、聚合和下采样。 后来的版本增加了对函数和表达式的支持。 一般来说，每个查询都有以下组件：

ParameterDate TypeRequiredDescriptionExampleStart TimeString or IntegerRequired查询的开始时间。 这可以是绝对时间或相对时间。 See Dates and Times for details24h-agoEnd TimeString or IntegerOptional查询的结束时间。 如果未提供结束时间，则将使用 TSD 上的当前时间。 See Dates and Times for details.1h-agoMetricStringRequired系统中指标的全名。 必须是完整名称，并且始终区分大小写sys.cpu.userAggregation FunctionStringRequired用于组合多个时间序列的数学函数（即如何将时间序列合并为一个组）sumFilterStringOptional过滤标签值以减少在查询或组中选取的时间序列数量，并在各种标签上聚合。host=*,dc=laxDownsamplerStringOptional一个可选的间隔和函数，用于减少跨时间返回的数据点数量1h-avgRateStringOptional用于计算结果每秒变化率的可选标志rateFunctionsStringOptional附加过滤、时移等数据操作功能（仅在gexp端点/api/query/gexp )highestMax(…)ExpressionsStringOptional跨时间序列的数据操作功能，例如将一个序列除以另一个。 （仅在 exp 端点 /api/query/exp）(m2 / (m1 + m2)) * 100 Times

支持人类可读格式或 Unix 样式整数的绝对时间戳。 相对时间可用于刷新仪表板。 目前，所有查询都能够覆盖单个时间跨度。 将来，我们希望提供一个偏移查询参数，允许在不同时间段内聚合或绘制度量标准，例如比较上周和 1 年前。 有关允许的详细信息，请参阅日期和时间。

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

要以毫秒分辨率提取数据，请使用 /api/query 端点并指定 msResolution（ms 也可以，但不推荐）JSON 参数或查询字符串标志，它将绕过向下采样（除非指定）并返回 Unix 中的所有时间戳 纪元毫秒分辨率。 此外，Scan命令行实用程序将返回写入存储的时间戳。

Filters

每个时间序列都由一个指标和一个或多个标签name/value对组成。 在 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 time, aggregator and metric最低要求制作一个简单的查询，例如：start=1356998400&m=sum:sys.cpu.user，我们将在 1356998400 处获得 8 的值，它将所有 4 个时间序列聚合并分组为 一。

如果我们想放大一个特定的系列或一组系列，我们可以使用过滤器。 例如，我们可以通过以下方式过滤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。

Note

查询时，不一致的标签可能会导致意外结果。 有关详细信息，请参阅写入数据。 另请参阅下面的显式标签。

Read the Query Filters documentation for details.

Aggregation

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

Note

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

See Aggregation for details.

Downsampling

OpenTSDB 可以摄取大量数据，甚至是给定时间序列每秒一个数据点。 因此查询可能会返回大量数据点。 从 API 访问具有大量点的查询结果可能会占用带宽。 高频率的数据很容易淹没 Javascript 图形库，因此选择使用 GnuPlot。 GUI 创建的图形可能难以阅读，导致出现如下图(图片来自Opentsdb官网)所示的粗线：

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

使用下采样，我们可以清理之前的图表(图片来自Opentsdb官网)以获得更有用的东西：

For details, see Downsampling.

Rate

许多数据源以不断递增的计数器形式返回值。一个例子是网站点击计数器。当您启动 Web 服务器时，它的命中计数器可能为 0。五分钟后，该值可能为 1,024。再过五分钟，它可能是 2,048。计数器的图形将是一条向右倾斜的直线，并不总是很有用。 OpenTSDB 提供了一个速率转换函数，用于计算值随时间的变化率。这会将计数器转换为带有尖峰的线条，以显示活动何时发生，并且可能会更有用。

比率是值的一阶导数。它被定义为(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。如果正常速率是每秒几个点，这个特殊的尖峰，点之间有 30 秒，将产生 2,134.5 的速率尖峰！为了避免这种情况，我们可以设置 resetValue，当速率超过这个值时，它会返回一个数据点 0，以避免在任一方向出现尖峰。对于上面的例子，如果我们知道我们的比率几乎从不超过100，我们可以将 resetValue 配置为 100，当计算上面的数据点时，它将返回 0 而不是 2,134.5。默认值 0 表示将忽略重置值，不会抑制任何速率。

Order of Operations

理解操作顺序很重要。 返回查询结果时，以下是处理发生的顺序：

1. Filtering
2. Grouping
3. Downsampling
4. Interpolation
5. Aggregation
6. Rate Conversion
7. Functions
8. Expressions