OpenTSDB HTTP API之/api/query

Posted 顧棟

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了OpenTSDB HTTP API之/api/query相关的知识，希望对你有一定的参考价值。

文章目录

/api/query

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

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

Query API Endpoints

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

Warning

删除数据是永久性的。 还要注意，删除时，由于数据是按小时存储的，因此可能会删除一些超出开始和结束时间边界的数据。

Verbs

  • GET
  • POST
  • DELETE

Requests

请求参数包括：

NameData TypeRequiredDescriptionDefaultQSRWExample
startString, IntegerRequired查询的开始时间。 这可以是相对或绝对时间戳。See Querying or Reading Data for details.start1h-ago
endString, IntegerOptional查询的结束时间。 如果未提供，TSD 将假定服务器上的本地系统时间。 这可以是相对或绝对时间戳。 See Querying or Reading Data for details.current timeend1s-ago
queriesArrayRequired一个或多个子查询用于选择要返回的时间序列。 这些可能是指标 m 或 TSUID tsuids 查询m or tsuidsSee below
noAnnotationsBooleanOptional是否通过查询返回注释。 默认是为请求的时间跨度返回注释，但此标志可以禁用返回。 这会影响本地和全局注释并覆盖“globalAnnotations”falseno_annotationsfalse
globalAnnotationsBooleanOptional查询是否应检索请求的时间跨度的全局注释falseglobal_annotationstrue
msResolution (or ms)BooleanOptional是否以毫秒或秒为单位输出数据点时间戳。 建议使用 msResolution 标志。 如果未提供此标志并且在一秒钟内有多个数据点，则将使用查询的聚合函数对这些数据点进行下采样falsemstrue
showTSUIDsBooleanOptional是否在结果中输出与时间序列关联的 TSUID。 如果将多个时间序列聚合为一组，则会以排序的方式返回多个 TSUIDfalseshow_tsuidstrue
showSummary (2.2)BooleanOptional是否在结果中显示围绕查询的时间摘要。 这会在地图中创建另一个与数据点对象不同的对象。 See Query Details and Statsfalseshow_summarytrue
showStats (2.2)BooleanOptional是否在结果中显示围绕查询的详细时间。 这会在地图中创建另一个与数据点对象不同的对象。 See Query Details and Statsfalseshow_statstrue
showQuery (2.2)BooleanOptional是否与查询结果一起返回原始子查询。 如果请求包含许多子查询，那么这是确定哪些结果属于哪个子查询的好方法。 请注意，在使用 * 或通配符查询的情况下，这可能会产生大量重复输出。falseshow_querytrue
deleteBooleanOptional可以通过 POST 传递给 JSON 以删除与给定查询匹配的任何数据点。falseWtrue
timezone (2.3)StringOptional基于日历的下采样的可选时区。 必须是 TSD 服务器上安装的 JRE 支持的有效 timezone 数据库名称。UTCtimezoneAsia/Kabul
useCalendar (2.3)BooleanOptional是否使用基于给定时区的日历进行下采样间隔falsetrue

Sub Queries

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

  • Metric Query - 指标的全名与可选的标签列表一起提供。 这是为将多个时间序列聚合成一个结果而优化的。
  • TSUID Query - 共享公共指标的一个或多个 TSUID 的列表。 这针对获取不需要聚合的单个时间序列进行了优化。

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

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

NameData TypeRequiredDescriptionDefaultExample
aggregatorStringRequired要使用的聚合函数的名称。 See /api/aggregatorssum
metricStringRequired存储在系统中的指标的名称sys.cpu.0
rateBooleanOptional数据在返回之前是否应转换为增量。 如果指标是一个持续递增的计数器并且您想要查看数据点之间的变化率，这将非常有用。falsetrue
rateOptionsMapOptional单调递增的计数器处理选项See belowSee below
downsampleStringOptional一个可选的下采样函数，用于减少返回的数据量。See below5m-avg
tagsMapOptional要深入查看特定时间序列或按标签对结果进行分组，请提供一个或多个与查询字符串格式相同的地图值。 标签在 2.2 中被转换为过滤器。 请参阅以下有关转换的说明。 请注意，如果未指定标签，则系统中的所有指标都将汇总到结果中。 *在 2.2 中已弃用 *See Below
filters (2.2)ListOptional过滤结果中发出的时间序列。 请注意，如果未指定过滤器，则给定指标的所有时间序列都将聚合到结果中。See Below
explicitTags (2.3)BooleanOptional返回仅包含过滤器中提供的标签键的系列falsetrue
percentiles (2.4)ListOptional获取指标的直方图数据并计算数据的给定百分位数列表。 百分位数是从 0 到 100 的浮点值。更多详细信息如下。[99.9, 95.0, 75.0]
rollupUsage (2.4)StringOptional获取汇总数据时的可选回退模式。 可以是ROLLUP_RAW跳过汇总，ROLLUP_NOFALLBACK只查询自动检测到的汇总表，ROLLUP_FALLBACK按顺序回退到匹配的汇总表，或者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 如果一个间隔、一个时间单位、使用基于日历的下采样的 c 标志（从 2.3 开始）、一个聚合器和（从 2.2 开始）一个可选的填充策略。 下采样规范的格式是：

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

示例

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

See Downsampling for details on downsampling, a list of supported fill policies and how calendar based downsampling operates.

Filters

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

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

对于 URI 查询，类型在括号中的过滤器表达式之前。 格式为<tagk>=<type>(<filter_expression>)。 结果是否分组取决于过滤器所在的大括号。现在每个指标查询支持两个大括号。 第一组是按过滤器分组，第二组是非按过滤器分组，例如{host=wildcard(web*)}{colo=regexp(sjc.*)}。 这指定了 colo 与正则表达式“sjc.*”匹配且主机标记值以“web”开头且结果按主机分组的任何指标。 如果您只想过滤而不分组，则第一个卷曲集必须为空，例如 {}{host=wildcard(web*),colo=regexp(sjc.*)}。 这指定了 colo 与正则表达式“sjc.*”匹配且主机标记值以“web”开头且结果未分组的任何指标。

Note

正则表达式、带有 pre/post/in-fix 或文字 or 具有许多值的通配符过滤器可能会导致查询返回速度较慢，因为每行数据都必须解析为它们的字符串值然后进行处理。

Note

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

Filter Conversions

POST 查询标签映射中的值和 URI 查询的大括号组自动转换为过滤器，以提供与现有系统的向后兼容性。 自动转换包括：

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

Percentiles

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

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

Note

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

Metric Query String Format

指标查询字符串子查询的完整规范如下：

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（您实际上可以复制和粘贴以与其他用户共享）。 For examples, please see Query Examples.

TSUID Query String Format

TSUID 查询比 Metric 查询更简单。 只需传递一个或多个以逗号分隔的十六进制编码 TSUID 的列表：

tsuid=<aggregator>:<tsuid1>[,...<tsuidN>]

Example Query String Requests

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

Example Content Request

请参阅序列化程序文档以获取请求信息：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 query with filters

{
    "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 序列化程序。 一个请求可能会导致返回多组数据，特别是当请求包含多个查询或请求分组时。 响应中每个数据集包含的一些常见字段是：

NameDescription
metric为时间序列检索的指标名称
tags仅当结果是针对单个时间序列时才返回标签列表。 如果聚合结果，则此值可能为 null 或空映射
aggregatedTags如果结果集中包含多个时间序列，即它们被聚合，这将显示在所有时间序列中找到的共同标记名称列表。
dps由聚合器处理后检索的数据点。 每个数据点由时间戳和值组成，格式由序列化器确定。
annotations如果查询在请求的时间跨度内检索到时间序列的注释，它们将在该组中返回。 每个时间序列的注释将合并为一组并按“start_time”排序。 聚合器函数不影响注解，所有注解都将返回范围。
globalAnnotations如果用户请求，查询将扫描时间跨度内的全局注释以及在该组中返回的结果

除非查询出现错误，否则您通常会收到带有内容的“200”状态。 但是，如果您的查询找不到任何数据，它将返回一个空结果集。 对于 JSON 序列化程序，结果将是一个空数组：

[]

对于 JSON 序列化程序，时间戳将始终是 Unix 纪元风格的整数，后跟作为整数或浮点数的值。 例如，默认输出是"dps"{"<timestamp>":<value>}。 默认情况下，时间戳将以秒为单位。 如果设置了 msResolution 标志，则时间戳将以毫秒为单位。

Example Aggregated Default Response

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

Example Aggregated Array Response

[
    {
        "metric": "tsd.hbase.puts",
        "tags": {},
        "aggregatedTags": [
            "host"
        ],
        "dps": [
            [
                1365966001,
                25595461080
            ],
            [
                1365966061,
                25595542522
            ],
...
            [
                1365974221,
                25722266376
            ]
        ]
    }
]

Example Multi-Set Response

对于以下示例，两个 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
        }
    }
]

Example With Show Summary and Query

See Query Details and Stats

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

以上是关于OpenTSDB HTTP API之/api/query的主要内容，如果未能解决你的问题，请参考以下文章

OpenTSDB http写数据报400 （Received an unsupported chunked）

hbase备份还原opentsdb数据之Export/Import（增量+全量）

OpenTSDB原理系列-线程模型

使用 HTTP POST 将 OpenTSDB 写入 Bigtable 不起作用（使用 Kubernetes（

opentsdb basic install

opentsdb探索之路——部分设计与实现