/api/query

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

查询 API 端点

• /api/query/exp

• /api/query/gexp

• /api/query/last

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

Verbs

• GET

• POST

• DELETE

Requests

请求参数包括：

Sub Queries

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

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

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

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

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

Rate Options

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

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 查询字段包括：

对于 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”开头，并且结果未分组。

Filter Conversions

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

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。

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。一个请求可能导致返回多组数据，特别是如果该请求包括多个查询或被分组的情况下。响应中每个数据集包含的一些常见字段为：

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