OpenTSDB 查询过滤器

Query Filters

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

任何数据库系统的一个关键功能是使用某种形式的过滤来获取完整数据集的子集。 OpenTSDB 从 1.x 版开始提供过滤功能，并从 2.2 及更高版本开始扩展功能。 过滤器目前对标签值进行操作。 这意味着在获取数据时，必须完全按照它们在数据库中出现的方式指定任何指标和标签键。

Example Data

由于下面解释了每个过滤器，因此使用了以下数据集。 它由单个指标和在各种标签上定义的多个时间序列组成。 作为示例，仅在 T1 处给出了一个数据点。

TS#	Metric	Tags	Value @ T1
1	sys.cpu.system	dc=dal host=web01	3
2	sys.cpu.system	dc=dal host=web02	2
3	sys.cpu.system	dc=dal host=web03	10
4	sys.cpu.system	host=web01	1
5	sys.cpu.system	host=web01 owner=jdoe	4
6	sys.cpu.system	dc=lax host=web01	8
7	sys.cpu.system	dc=lax host=web02	4

Grouping

分组，也称为分组依据，是使用所需的聚合函数和过滤器将多个时间序列合并为一个的过程。 默认情况下，OpenTSDB 按指标对所有内容进行分组，以便如果查询返回 10 个带有 sum 聚合器的时间序列，则所有 10 个序列将随着时间的推移加在一起以得出一个值。 有关如何合并时间序列的详细信息，请参阅聚合。

为了避免在没有任何聚合的情况下对每个底层时间序列进行分组和获取，请使用 2.2 版中包含的 none 聚合器。 或者，您可以使用 OpenTSDB 2.2 及更高版本禁用基于每个过滤器的分组。 有关如何执行此操作的信息，请参阅 API 文档。

OpenTSDB 1.x - 2.1

在最初的 OpenTSDB 版本和 2.1 之前，只有两种类型的过滤器可用，并且它们被隐式配置为分组。 允许的两个运算符是：

• ***** - 星号（或通配符）将为检测到的每个唯一标签值返回一个单独的结果。 例如。 如果标签键 host 与 web01 和 web02 配对，那么将发出两组，一组在 web01 上，一组在 web02 上。
• | - 管道（或literal_or）将返回一个单独的结果仅指定的确切标签值。 IE。 它将仅匹配具有给定标签值的时间序列，并在每个匹配项上进行分组。

每个查询可以提供多个过滤器，并且结果总是被 AND 运算在一起。 这些过滤器仍可用于 2.x 及更高版本。

Examples

以下示例使用 v1 HTTP URI 语法，其中 m 参数包含聚合器、冒号，然后是用等号分隔的括号中的度量和标签过滤器。

Example 1: http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01}

Time Series Included	Tags	Aggregated Tags	Value @ T1
1, 4, 5, 6	host=web01		16

In this case the aggregated tags set will be empty as time series 4 and 5 have tags that are not in common with the entire set.

Example 2: http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=web01,dc=dal}

Time Series Included	Tags	Aggregated Tags	Value @ T1
1	host=web01,dc=dal		3

Example 3: http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{host=*,dc=dal}

Time Series Included	Tags	Aggregated Tags	Value @ T1
1	host=web01,dc=dal		3
2	host=web02,dc=dal		2
3	host=web03,dc=dal		10

This time we provided the * for the host and an explicit match for dc. This will group on the host tag key and return a time series per unique host tag value, in this case 3 series.

Example 4: http://host:4242/q?start=1h-ago&m=sum:sys.cpu.system{dc=dal|lax}

Time Series Included	Tags	Aggregated Tags	Value @ T1
1, 2, 3	dc=dal	host	15
6, 7	dc=lax	host	12

Here the | operator is used to match only the values for the dc tag key that are provided in the query. Therefore the TSD will group together any time series with those values. The host tag is moved to the Aggregated Tags list as every time series in the set has a host tag and there are multiple values for the tag key.

Warning

Because these filters are limited, if users write time series like #1, #4 and #5, unexpected results can be returned as a result of aggregating time series that may have one common tag but varying additional tags. This problem is somewhat addressed with 2.3 and Explicit Tags.

OpenTSDB 2.2

在 OpenTSDB 2.2 中添加了一个更灵活的过滤器框架，允许禁用分组以及其他过滤器类型，例如正则表达式和通配符。 过滤器框架是可插入的，以允许绑定到外部系统，例如资产管理或供应系统。

允许在同一个标签键上使用多个过滤器，并且在处理时，它们会进行 AND 运算，例如 如果我们有两个过滤器 host=literal_or(web01) 和 host=literal_or(web02)查询将始终返回空。 如果为同一个标签键包含两个或多个过滤器，并且一个已启用 group by 而另一个未启用，则 group by 将对该标签键上的所有过滤器有效。

Warning

某些类型的过滤器可能会导致查询执行得比其他过滤器慢，尤其是正则表达式、通配符和不区分大小写的过滤器。 在从存储中获取数据之前，过滤器被处理以创建基于 UID 的数据库过滤器，因此使用区分大小写的literal_or 过滤器总是比regexp 更快，因为我们可以将字符串解析为UID 并将它们发送到存储系统进行过滤。 相反，如果您要求使用前置、后置或中缀过滤的正则表达式或通配符，TSD 必须使用标签键 UID 从存储中检索所有行，然后对于每个唯一的行，将 UID 解析回字符串，然后在 结果。 此外，具有大量文字列表的过滤器集将在存储后进行处理，以避免为要处理的后备存储创建大量过滤器。 此限制默认为 4096，可以通过tsd.query.filter.expansion_limit 参数进行配置。

Explicit Tags

从 2.3 及更高版本开始，如果您知道给定指标的所有标签键，则可以通过使用显式标签功能大大改善查询延迟。 这个标志有两个好处：

1. 对于具有高基数的指标，后端可以切换到更高效的查询，以从存储中获取更小的数据子集。 （特别是在 2.4 中）
2. 对于具有不同标签的指标，这可用于避免聚合不应包含在最终结果中的时间序列。

显式标签将制作一个底层存储查询，该查询仅获取具有给定标签键的那些行。 这可以让数据库跳过不相关的行并在更短的时间内回答。

Examples

以下示例使用 v2 HTTP URI 语法，其中 m 参数由聚合器、冒号、explicit_tags URI 标志组成，然后是用等号分隔的括号中的指标和标签过滤器。

Example 1: http://host:4242/api/query?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=web01}

Time Series Included	Tags	Aggregated Tags	Value @ T1
4	host=web01		1

这解决了标签键不一致的问题，允许我们只挑选时间序列 #4。

Example 2: http://host:4242/api/query?start=1h-ago&m=sum:explicit_tags:sys.cpu.system{host=*}{dc=*}

Time Series Included	Tags	Aggregated Tags	Value @ T1
1, 6	host=web01	dc	11
2, 7	host=web02	dc	6
3	host=web03,dc=dal		10

此查询使用 v2 URI 语法，通过将 dc 标签键放在第二组花括号中来避免对 dc 标签键进行分组。 这允许我们仅过滤出同时具有 host 和 dc 标签键的时间序列，同时仅对 host 值进行分组。 它跳过时间序列 #4 和 #5。

Note

使用 HBase（0.98 及更高版本）或 Bigtable 时，请确保在配置中启用了 tsd.query.enable_fuzzy_filter（默认启用）。 为后端提供了一个特殊的过滤器，可以跳过查询所需的行，而不是遍历每个行键并比较正则表达式。

Note

在 2.4 中，TSDB 将针对后端发出多个 get 请求，而不是使用扫描器。 这可以通过多种因素减少查询时间，特别是对于高基数时间序列。 但是过滤器必须只包含“literal_or”。

Built-in 2.x Filters

以下列表是 OpenTSDB 中包含的内置过滤器。 额外的过滤器可以作为插件加载。 每个标题都是在 URI 或 JSON 查询中使用的过滤器类型。 编写 URI 查询时，通过将过滤器名称放在标签键的等号后面并将过滤器值放在括号中来使用过滤器。 例如。{host=regexp(web[0-9]+.lax.mysite.com)}。 对于 JSON 查询，只需将过滤器名称用作类型参数，将过滤器值用作过滤器参数，例如

{
  "type": "regexp",
  "filter": "web[0-9]+.lax.mysite.com",
  "tagk": "host",
  "groupBy": false
}

下面的示例使用 URI 语法。

literal_or

获取单个文字值或一个 | 管道分隔的值列表，并以区分大小写的方式返回与结果匹配的任何时间序列。 这是一个非常有效的过滤器，因为它可以将字符串解析为 UID 并将其发送到存储层进行预过滤。 在 SQL 中，这类似于 IN 或 = 谓词。

Examples

• host=literal_or(web01|web02|web03) In SQL: WHERE host IN ('web01', 'web02', 'web03')
• host=literal_or(web01) In SQL: WHERE host = 'web01'

iliteral_or

与 literal_or 相同，但不区分大小写。 请注意，这不像文字那样有效，或者因为它必须对存储中的所有行进行后处理。

not_literal_or

区分大小写的 literal_or 将返回与给定值列表 NOT 匹配的系列。 高效，因为它可以通过存储进行预处理。

not_iliteral_or

不区分大小写的not_literal_or。

wildcard

提供区分大小写的后缀、前缀、中缀和多中缀过滤。 通配符是星号（星号）*。 可以使用多个通配符。 如果只给出星号，则过滤器有效地返回任何包含标签键的时间序列（并且是一个可以预处理的高效过滤器）。 在 SQL 领域，这类似于“LIKE”谓词，但具有更大的灵活性。

Examples

• host=wildcard(*mysite.com) In SQL: WHERE host='%mysite.com'
• host=wildcard(web*)
• host=wildcard(web*mysite.com)
• host=wildcard(web*mysite*)
• host=wildcard(*) This is equivalent to the v1 basic group by operator and is efficient.

iwildcard

与wildcard相同，但不区分大小写。

regexp

使用 POSIX 兼容正则表达式的过滤器从存储中提取。 过滤器使用 Java 的内置正则表达式操作。 根据所使用的查询方法，小心转义特殊字符。

Examples

• regexp(web.*) In SQL: WHERE host REGEXP 'web.*'
• regexp(web[0-9].mysite.com)

Loaded Filters

要在 OpenTSDB 2.2 及更高版本中显示加载的过滤器，请调用 HTTP /api/config/filters 端点。 这将列出加载的插件以及描述和示例用法。

Plugins

当开发人员添加插件时，我们将在此处列出它们。

要开发插件，只需扩展 net.opentsdb.query.filter.TagVFilter 类，根据 Plugins 文档创建 JAR 并将其放在您的插件目录中。 开始时，TSD 将搜索插件并加载它。 如果实现有错误，TSD 将不会启动并记录异常。