/api/query

/api/query可能是 API 中最有用的端点，它可以从存储系统中提取由选定的序列化程序确定的各种格式的数据。可以通过 1.0 查询字符串格式或正文内容提交查询。

查询 API 端点

/query端点记录在下面。从 2.2 开始，可以使用DELETE动词删除匹配查询的数据。必须启用配置参数tsd.http.query.allow_delete才能删除。删除的数据将返回到查询结果中。第二次执行查询应返回空结果。

Warning

删除数据是永久性的。还要注意，删除时，开始时间和结束时间范围之外的某些数据可能会被删除，因为数据是按小时存储的。

Verbs

  • GET

  • POST

  • DELETE

Requests

请求参数包括：

NameData TypeRequiredDescriptionDefaultQSRWExample
startString, IntegerRequired查询的开始时间。这可以是相对或绝对时间戳。有关详情，请参见查询或读取数据。 start 1h-ago
endString, IntegerOptional查询的结束时间。如果未提供，则 TSD 将在服务器上采用本地系统时间。这可能是相对或绝对时间戳。有关详情，请参见查询或读取数据。current timeend 1s-ago
queriesArrayRequired一个或多个子查询用于选择要返回的时间序列。这些可能是 Metricsm或 TSUID tsuids查询 m 或 tsuids See below
noAnnotationsBooleanOptional是否通过查询返回 Comments。默认设置是为请求的时间间隔返回 Comments，但是此标志可以禁用返回。这会影响本地和全局 Comments，并覆盖globalAnnotationsfalseno_annotations false
globalAnnotationsBooleanOptional查询是否应在请求的时间范围内检索全局 Commentsfalseglobal_annotations true
msResolution(或 ms)BooleanOptional是否以毫秒或秒为单位输出数据点时间戳。建议使用 msResolution 标志。如果未提供此标志，并且在一秒钟内有多个数据点，则将使用查询的聚合函数对这些数据点进行下采样。falsems true
showTSUIDsBooleanOptional是否在结果中输出与时间序列关联的 TSUID。如果将多个时间序列汇总到一组中，则将以排序方式返回多个 TSUIDfalseshow_tsuids true
showSummary (2.2)BooleanOptional是否在结果中显示查询周围的时间摘要。这将在 Map 中创建另一个与数据点对象不同的对象。见查询详细信息和统计信息falseshow_summary true
showStats (2.2)BooleanOptional是否在结果中显示围绕查询的详细计时。这将在 Map 中创建另一个与数据点对象不同的对象。见查询详细信息和统计信息falseshow_stats true
showQuery (2.2)BooleanOptional是否返回带有查询结果的原始子查询。如果请求包含许多子查询，那么这是确定哪些结果属于哪个子查询的好方法。请注意，在*或通配符查询的情况下，这会产生很多重复的输出。falseshow_query true
deleteBooleanOptional可以通过 POST 传递给 JSON，以删除与给定查询匹配的所有数据点。false Wtrue
时区*(2.3)*StringOptional用于基于 calendar 的下采样的可选时区。必须是 TSD 服务器上安装的 JRE 支持的有效timezone数据库名称。UTCtimezone Asia/Kabul
useCalendar (2.3)BooleanOptional是否将基于给定时区的 calendar 用于下采样间隔false true

Sub Queries

OpenTSDB 查询至少需要一个子查询，这是一种选择应在结果集中包含哪个时间序列的方法。有两种类型：

  • Metrics 查询 -提供 Metrics 的全名以及可选的标签列表。这是针对将多个时间序列汇总为一个结果而优化的。

  • TSUID 查询 -共享一个公用度量的一个或多个 TSUID 的列表。这是为获取不需要汇总的单个时间序列而优化的。

一个查询可以包含多个子查询以及这两种类型的任意混合。通过内容主体提交查询时，如果提供了 TSUID 列表，则该特定子查询的 Metrics 和标签将被忽略。

每个子查询可以检索单个或一组时间序列数据，对每个集合执行汇总或分组计算。每个子查询的字段包括：

NameData TypeRequiredDescriptionDefaultExample
aggregatorStringRequired要使用的聚合函数的名称。见/api/aggregators sum
metricStringRequired系统中存储的 Metrics 的名称 sys.cpu.0
rateBooleanOptional返回之前是否应将数据转换为增量。如果度量标准是一个连续递增的计数器，并且您要查看数据点之间的变化率，则此功能很有用。falsetrue
rateOptionsMapOptional单调增加柜台处理选项See belowSee below
downsampleStringOptional可选的缩减采样功能，以减少返回的数据量。See below5m-avg
tagsMapOptional要向下钻取特定的时间序列或按标签分组结果，请以与查询字符串相同的格式提供一个或多个 Map 值。标签在 2.2 中转换为过滤器。请参阅以下有关转换的说明。请注意，如果未指定标签，则系统中的所有 Metrics 都会汇总到结果中。 自 2.2 起已弃用 See Below
过滤器*(2.2)*ListOptional过滤结果中发出的时间序列。请注意，如果未指定任何过滤器，则给定 Metrics 的所有时间序列都会汇总到结果中。 See Below
显式标签*(2.3)*BooleanOptional返回仅包含过滤器中提供的标记键的系列。falsetrue
百分位数*(2.4)*ListOptional获取 Metrics 的直方图数据，并计算数据上给定的百分位列表。百分位数是从 0 到 100 的浮点值。下面有更多详细信息。 [99.9, 95.0, 75.0]
汇总用法*(2.4)*StringOptional提取汇总数据时的可选回退模式。可以是ROLLUP_RAW跳过汇总，ROLLUP_NOFALLBACK仅查询自动检测到的汇总表，ROLLUP_FALLBACK可以按 Sequences 回退到匹配的汇总表，或者ROLLUP_FALLBACK_RAW可以回退到原始表(如果在第一个自动表中未找到任何内容)。ROLLUP_NOFALLBACKROLLUP_RAW

Rate Options

在查询字符串中传递速率选项时，必须将选项括在花括号中。例如：m=sum:rate{counter,,1000}:if.octets.in。如果希望使用默认的counterMax但想提供resetValue，则必须像前面的示例一样添加两个逗号。 rateOptions对象中的其他字段包括以下内容：

NameData TypeRequiredDescriptionDefaultExample
counterBooleanOptional基础数据是否是单调递增的计数器，可能会翻转falsetrue
counterMaxIntegerOptional表示计数器最大值的正整数。Java Long.MaxValue65535
resetValueIntegerOptional一个可选的值，当超过该值时，它将导致聚合器返回0而不是计算出的速率。经常重置数据源以避免虚假尖峰时很有用。065000
dropResetsBooleanOptional是否只是简单地丢弃滚存或重置数据点。falsetrue

Downsampling

下采样规格 const 表示一个间隔，一个时间单位，使用基于 calendar 的下采样的c标志(从 2.3 版本开始)，聚合器和(从 2.2 版本开始)可选填充策略。下采样规格的格式为：

<interval><units>[c]-<aggregator>[-<fill policy>]

For example:

1h-sum
30m-avg-nan
24h-max-zero
1dc-sum
0all-sum

有关降采样，受支持的填充策略列表以及基于 calendar 的降采样如何工作的详细信息，请参见Downsampling。

Filters

OpenTSDB 是 2.2 的新功能，包括跨标记键和值组合的扩展和可插入过滤器。有关在 TSD 中加载的过滤器的列表，请参见/api/config/filters。有关内置过滤器的说明，请参见Query Filters。过滤器可用于查询字符串和 POST 格式的查询中。允许在同一标签键上使用多个过滤器，并在处理时将它们“与”在一起，例如如果我们有两个过滤器host=literal_or(web01)和host=literal_or(web02)，则查询将始终返回空。如果同一标签键包含两个或多个过滤器，并且一个过滤器启用了分组依据，而另一个未启用，则对于该标签键上的所有过滤器，分组依据将有效。与过滤器有关的 POST 查询字段包括：

NameData TypeRequiredDescriptionDefaultExample
typeStringRequired要调用的过滤器的名称。见/api/config/filters regexp
tagkStringRequired用于在其上调用过滤器的标签键 host
filterStringRequired要评估的过滤器表达式，并取决于所使用的过滤器 web.*.mysite.com
groupByBooleanOptional是否按过滤器匹配的每个值对结果进行分组。默认情况下，所有与过滤器匹配的值都将汇总为一个系列。falsetrue

对于 URI 查询，该类型在括号中的过滤器表达式之前。格式为<tagk>=<type>(<filter_expression>)。是否将结果分组取决于过滤器位于哪个大括号中。现在，每个度量查询都支持两个大括号。第一组是* group by 过滤器，第二组是 nongroup by 过滤器，例如{host=wildcard(web*)}{colo=regexp(sjc.*)}。此参数指定 colo 匹配正则表达式“ sjc.”且主机标记值以“ web”开头且结果按主机分组的任何度量。如果您只想过滤而不进行分组，则第一个卷曲集必须为空，例如{}{host=wildcard(web*),colo=regexp(sjc.*)}。此参数指定无色度量，其中 colo 匹配正则表达式“ sjc.*”，并且主机标记值以“ web”开头，并且结果未分组。

Note

正则表达式，带有前缀/后缀/固定值的通配符过滤器或具有多个值的 Literalsors 会导致查询返回的速度变慢，因为必须将每一行数据解析为其字符串值然后进行处理。

Note

向 OpenTSDB 2.2 或更高版本提交 JSON 查询时，请使用tags或filters。只有一个会生效，并且 Sequences 是不确定的，因为 JSON 解析器可能会先反序列化另一个。我们建议对以后的所有查询都使用过滤器。

Filter Conversions

POST 查询tagsMap 和 URI 查询的* group by *大括号中的值将自动转换为过滤器，以提供与现有系统的向后兼容性。自动转换包括：

ExampleDescription
<tagk>=*通配符过滤器，可有效确保系列中存在标签键
<tagk>=value区分大小写的 Literals 或过滤器
<tagk>=value1|value2|valueN区分大小写的 Literals 或过滤器
<tagk>=va*不区分大小写的通配符过滤器。现在，带有任何其他字符串的星号(星号)将成为通配符过滤器的快捷方式

Percentiles

使用 OpenTSDB 2.4，数据库可以存储和查询直方图或摘要数据以进行准确的百分位计算(与内置的百分位聚合器相对)。如果在查询中请求一个或多个百分位数，则 TSD 将显式扫描存储中的直方图(任何编解码器类型)，并且常规数值数据将被忽略。可以同时计算一个以上的百分位数，例如，通常可以通过percentiles[99.999, 99.9, 99.0, 95.0]在一个查询中获取第 99.999、99.9、99.0 和 95％百分位数。 注意 对于某些插件实现(例如 Yahoo Data Sketches 实现)，百分数列表必须以降序排列。

将结果按与常规数据点时间序列相同的 Sequences 进行序列化，以与现有图形系统兼容。但是，将为每个分组依据将百分位数附加到度量标准名称和时间序列，并将返回百分位数。例如，如果用户要求sys.cpu.niceMetrics 要求percentiles[99.9,75.0]，则结果将具有时间序列sys.cpu.nice_pct_99.9和sys.cpu.nice_pct_75.0。

Note

当前，唯一支持的直方图数据下采样和聚合运算符是SUM。这是最常见的用例，因为您可能希望按 colo 对服务器的所有主机进行分组，在这种情况下，我们将对所有直方图求和，然后根据这些和计算百分位。同样，如果您想向下采样到每小时，则再次将分组的直方图随时间累加，最后提取百分位数。

Metrics 查询字符串格式

度量查询字符串子查询的完整规范如下：

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(您实际上可以复制并粘贴该 URL 与其他用户共享)。有关示例，请参见Query Examples。

TSUID 查询字符串格式

TSUID 查询比 Metric 查询更简单。只需传递一个或多个以逗号分隔的十六进制编码的 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"
            ]
        }
    ]
}

2 .2 带过滤器的查询

{
    "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"
            ]
        }
    ]
}

Response

为查询生成的输出在很大程度上取决于所选的序列化器HTTP Serializers。一个请求可能导致返回多组数据，特别是如果该请求包括多个查询或被分组的情况下。响应中每个数据集包含的一些常见字段为：

NameDescription
metric针对时间序列检索的 Metrics 的名称
tags仅在结果针对单个时间序列时返回的标签列表。如果汇总结果，则该值可以为 null 或为空 Map
aggregatedTags如果结果集中包含多个时间序列，即它们进行了汇总，则会显示所有时间序列中常见的标记名列表。
dps聚合器处理后检索到的数据点。每个数据点都包含一个时间戳和一个值，格式由串行器确定。
annotations如果查询在请求的时间范围内检索到时间序列的 Comments，则它们将在此组中返回。每个时间序列的 Comments 将合并为一组，并按start_time排序。聚合器函数不影响 Comments，将为范围返回所有 Comments。
globalAnnotations如果用户要求，查询将在该时间段内扫描全局 Comments，并在该组中返回结果

除非查询出错，否则您通常会收到带有内容的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
        }
    }
]

显示摘要和查询的示例

See 查询详细信息和统计信息

[
    {
        "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
        }
    }
]
Name OpenTSDB 中文文档
Version
Language
Badge
Last Updated 2021-07-03T12:24:36