On this page
/api/query/last
此端点(2.1 及更高版本)为访问单个时间序列的最新值提供支持。当仅需要最后一个数据点时,它可以对常规查询进行优化。可以使用元数据计数器的时间戳或通过从当前系统时间向后扫描来定位最后一点。
Note
为了使此端点能够通过扫描匹配的时间序列来使用度量字符串查询,元数据表必须存在并且已使用Metadata中指定的方法之一用计数器或 TSMeta 对象填充。您必须设置tsd.core.meta.enable_tsuid_tracking
或tsd.core.meta.enable_realtime_ts
。具有 backscan 参数的查询将跳过元表。
与标准查询端点相似,有两种方法可以用来选择哪个时间序列应返回数据:
Metrics 查询 -与常规 Metrics 查询类似,您可以发送 Metrics 名称和(可选)一组标记对。如果启用了实时元,则 TSD 将扫描元数据表以查看是否有任何时间序列与查询匹配。对于每个匹配的时间序列,它将扫描最新的数据点并返回它。但是,如果禁用了 meta,则 TSD 将尝试查找提供的确切度量和标记集,只要给出了反向扫描值即可(自 2.1.1 开始)。
TSUID 查询 -如果您知道要访问其数据的时间序列的 TSUID,只需提供一个 TSUID 列表。
此外,有两种方法可以找到每个时间序列的最后一个数据点:
计数器方法 -如果未提供反向扫描值且启用了 meta,则默认值为在每个时间序列的 meta 数据表中查找数据点计数器。该计数器记录 TSD 写入最新数据点的时间。端点查找时间戳并“获取”正确的数据行,以获取行中的最后一点。这在大多数情况下都会起作用,但是请注意,如果您回填较旧的数据(通过导入或只是将数据点带有旧的时间戳记),则计数器列的时间戳记可能不准确。此方法最适合用于连续更新的数据。
反向扫描 -或者,您可以指定小时数,以从执行查询的 TSD 的当前系统时间开始回溯时间。例如,如果您将反向扫描时间指定为 24 小时,则 TSD 将首先在具有当前小时数的行中查找数据。如果该行为空,它将在此之前一小时查找数据。它将 continue 这样做,直到找到数据点或超过小时限制。如果您经常按时间 Sequences 写入数据点,则此方法很有用。还要注意,反向扫描值越大,查询完成所需的时间就越长,因为它们可能会进一步向后扫描数据。
所有查询将仅返回与查询匹配且找到数据点的时间序列的结果。结果是每个时间序列的单个数据点的列表。由于时间戳可能无法对齐,因此无法对单个数据点执行汇总,TSD 仅返回单个点,因此无法进行插值。
Verbs
GET
POST
Requests
常用参数包括:
Name | Data Type | Required | Description | Default | QS | RW | Example | |
---|---|---|---|---|---|---|---|---|
queries | Array | Required | 一个或多个查询的列表,用于确定要为其获取最后一个数据点的时间序列。 | 时间序列 | tsu | |||
resolveNames | Boolean | Optional | 是否将结果的 TSUID 解析为其度量和标记名称。 | false | resolve | true | ||
backScan | Integer | Optional | 过去几个小时要搜索数据。如果设置为 0,则使用时间序列的元数据计数器的时间戳。 | 0 | back_scan | 24 |
请注意,您可以在一个请求中混合使用多个度量和 TSUID 查询。
Metrics 查询字符串格式
度量查询字符串子查询的完整规范如下:
timeseries=<metric_name>[{<tag_name1>=<tag_value1>[,...<tag_nameN>=<tag_valueN>]}]
它类似于常规 Metrics 查询,但不允许进行聚合,速率,下采样或分组运算符。请注意,如果提供后扫描值以避免使用元表,则必须提供所有标记和值以匹配要查找的确切时间序列。反向扫描当前不会根据给定的 Metrics 和标签进行过滤,但会查找特定的系列。
TSUID 查询字符串格式
TSUID 查询比 Metric 查询更简单。只需传递一个或多个以逗号分隔的十六进制编码的 TSUID 的列表即可:
tsuids=<tsuid1>[,...<tsuidN>]
示例查询字符串请求
http://localhost:4242/api/query/last?timeseries=proc.stat.cpu{host=foo,type=idle}×eries=proc.stat.mem{host=foo,type=idle}
http://localhost:4242/api/query/last?tsuids=000001000002000003,000001000002000004&back_scan=24&resolve=true
内容请求示例
{
"queries": [
{
"metric": "sys.cpu.0",
"tags": {
"host": "web01",
"dc": "lga"
}
},
{
"tsuids": [
"000001000002000042",
"000001000002000043"
]
}
],
"resolveNames":true,
"backScan":24
}
Response
输出将是一个 0 或更多数据点的数组,具体取决于找到的数据。如果特定时间序列的数据点不在指定的时间内,则该数据点将不会出现在输出中。输出字段取决于是否设置了resolve
标志。
Name | Description |
---|---|
metric | 时间序列的度量标准名称。仅当resolve 设置为 true 时返回。 |
tags | 时间序列的标签列表。仅当resolve 设置为 true 时返回。 |
timestamp | 写入数据点时的 Unix 时代时间戳(以毫秒为单位) |
value | 用双引号括起来的数据点的值作为字符串 |
tsuid | 时间序列的十六进制 TSUID |
除非查询出错,否则您通常会收到带有内容的200
状态。但是,如果您的查询找不到任何数据,它将返回一个空结果集。对于 JSON 序列化程序,结果将是一个空数组:
[]
Example Responses
[
{
"timestamp": 1377118201000,
"value": "1976558550",
"tsuid": "0023E3000002000008000006000001"
},
{
"timestamp": 1377118201000,
"value": "1654587485",
"tsuid": "0023E3000002000008000006001656"
}
]
[
{
"metric": "tsd.hbase.rpcs",
"timestamp": 1377186301000,
"value": "2723265185",
"tags": {
"type": "put",
"host": "tsd1"
},
"tsuid": "0023E3000002000008000006000001"
},
{
"metric": "tsd.hbase.rpcs",
"timestamp": 1377186301000,
"value": "580720",
"tags": {
"type": "put",
"host": "tsd2"
},
"tsuid": "0023E3000002000008000006017438"
}
]