/api/query/exp
该端点允许使用表达式查询数据。该查询分为多个部分。
允许两个设置操作(或联接)。所有时间序列的并集或相交。
例如，我们可以在主机字段上使用 group by 来计算“ a b”。单独查询的两个 Metrics 将为每个主机发出一个时间序列，例如也许是“ web01”，“ web02”和“ web03”的代表。假设 Metrics“ a”具有所有 3 个主机的值，但 Metrics“ b”缺少“ web03”。
使用交集运算符，该表达式将有效地添加“ a.web01 b.web01”和“ a.web02 b.web02”，但是将跳过为“ web03”发出任何内容。请注意，如果看到的输出较少，或者在相交后没有可用序列的错误，请注意这一点。
使用联合运算符，该表达式将添加web01和web02系列，但对于度量标准“ b”，它将用度量标准的填充策略值替代结果。
Note
从 2.3 版本开始支持
Verbs
- POST
Requests
实施的各个部分包括：
"time"
时间部分是必需的，并且是单个 JSON 对象。这会影响时间范围和所有请求 Metrics 的可选减少。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| start | Integer | Required | 查询的开始时间。这可能是相对的，绝对的人类可读性或绝对的 Unix Epoch。 | 1h-ago, 2015/05/05-00:00:00 | |
| aggregator | String | Required | 用于所有 Metrics 的全局聚合功能。可以按每个 Metrics 覆盖它。 | sum | |
| end | Integer | Optional | 查询的结束时间。如果不考虑的话，结尾就是现在 | now | 1h-ago, 2015/05/05-00:00:00 |
| downsampler | Object | Optional | 减少返回的数据点数。格式定义如下 | None | See below |
| rate | Boolean | Optional | 是否将所有 Metrics 计算为速率，即每秒的值。这是在表达式之前计算的。 | false | true |
E.g.
"time":{ "start":"1h-ago", "end":"10m-ago", "downsampler":{"interval":"15m","aggregator":"max"}
Downsampler
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| interval | String | Required | 下采样间隔，即将原始值汇总到的时间间隔。格式为<#><unit>，例如15m | 1h | |
| aggregator | String | Required | 用于减少数据点的聚合功能 | avg | |
| fillPolicy | Object | Optional | 用于填充缺少数据点的存储桶的策略 | None | See Below |
Fill Policies
这些用于替换“丢失”的值，即当期望数据点但在存储中找不到数据点时。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| policy | String | Required | 要使用的策略的名称。值在下表中列出 | zero | |
| value | Double | Optional | 对于标量填充，可以在替换期间使用的可选值 | NaN | 42 |
| Name | Description |
|---|---|
| nan | 如果聚合函数中的所有值均为 NaN 或“缺失”，则发出 NaN。对于聚合器，NaN 被视为“哨兵”值，这会使函数跳过这些值。请注意，如果系列在表达式中发出 NaN，则 NaN 具有传染性，并将使该表达式的输出为 NaN。在序列化时，将运行 NaN。 |
| null | 在序列化时发出 Null。在计算过程中，这些值被视为 NaN。 |
| zero | 缺少值时发出零 |
| scalar | 缺少数据点时，发出用户定义的值。必须使用value指定值。该值可以是整数或浮点数。 |
请注意，如果您尝试提供与该类型不兼容的值，则查询将引发异常。例如。用 NaN 提供非 NaN 的值将引发错误。
E.g.
{"policy":"scalar","value":"1"}
"filters"
过滤器用于根据标签键和值选择各种时间序列。必须至少指定一个过滤器(目前)，并至少提供一个聚合函数。字段包括：
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| id | String | Required | 过滤器的唯一 ID。不能与任何 Metrics 或表达式 ID 相同 | f1 | |
| tags | Array | Optional | 标签值过滤器列表 | None | See below |
E.g.
"filters":[
"id":"f1",
"tags":[
{
"type":"wildcard",
"tagk":"host",
"filter":"*",
"groupBy":true
},
{
"type":"literal_or",
"tagk":"colo",
"filter":"lga",
"groupBy":false
}
]
]
Filter Fields
在“标签”字段中，您可以具有一个或多个过滤器。过滤器列表可通过/api/config/filters端点找到。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| type | String | Required | API 中过滤器的名称 | regexp | |
| tagk | String | Required | 我们过滤所依据的标记键名称，例如* host 或 colo * | host | |
| filter | String | Required | 要过滤的值。这取决于使用的过滤器。详情请参阅 API | web.*mysite.com | |
| groupBy | Boolean | Optional | 是否按与该过滤器匹配的标记值对结果进行分组。例如。按主机分组将为每个主机返回一个结果。不按主机分组会(使用聚合功能)将度量标准的所有结果聚合为一个系列 | false | true |
"metrics"
Metrics 列表确定表达式中包含哪些 Metrics。必须至少有一个 Metrics。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| id | String | Required | Metrics 的唯一 ID。这必须是一个简单的字符串，没有标点或空格 | cpunice | |
| filter | String | Required | 提取此 Metrics 时要使用的过滤器。它必须与过滤器数组中的过滤器匹配 | f1 | |
| metric | String | Required | OpenTSDB 中 Metrics 的名称 | system.cpu.nice | |
| aggregator | String | Optional | 可选的聚合函数，仅针对此 Metrics 重载time中的全局函数 | time的聚合器 | count |
| fillPolicy | Object | Optional | 如果未使用降采样，则可以将其包括在内，以确定在计算中要运行什么。它还将覆盖下采样策略 | zero fill | See above |
E.g.
{"id":"cpunice", "filter":"f1", "metric":"system.cpu.nice"}
"expressions"
Metrics 上的一个或多个表达式的列表。表达式“必须”中的变量引用度量标准 ID 字段或表达式 ID 字段。支持嵌套表达式，但是如果检测到自引用或循环依赖项，则将引发异常。到目前为止，仅支持基本操作，例如加，减，乘，除，取模
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| id | String | Required | 表达式的唯一 ID | cpubusy | |
| expr | String | Required | 要执行的表达式 | a b/1024 | |
| join | Object | Optional | 设置操作或“联接”以执行跨集合的系列操作。 | union | See below |
| fillPolicy | Object | Optional | 在嵌套表达式中使用表达式且没有值时，表达式的可选填充策略 | NaN | See above |
E.g.
{
"id": "cpubusy",
"expr": "(((a + b + c + d + e + f + g) - g) / (a + b + c + d + e + f + g)) * 100",
"join": {
"operator": "intersection",
"useQueryTags": true,
"includeAggTags": false
}
}
Joins
联接对象控制如何将给定度量的各种时间序列合并到表达式中。目前支持的两个基本操作是联合和相交运算符。其他标志控制联接行为。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| operator | String | Required | 要使用的运算符，并集或交集 | intersection | |
| useQueryTags | Boolean | Optional | 计算联接键时是否仅使用过滤器中明确定义的标签 | false | true |
| includeAggTags | Boolean | Optional | 是否在联接键中包括从系列中聚合的标记键 | true | false |
"outputs"
这些确定输出行为，并允许您从结果中消除某些表达式或包括原始 Metrics。默认情况下，如果缺少此部分，则所有表达式以及仅表达式将被序列化。该字段是一个或多个输出对象的列表。稍后将添加带有标志的更多字段以影响输出。
| Name | Data Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
| id | String | Required | Metrics 或表达式的 ID | e | |
| alias | String | Optional | 系列的可选描述性名称 | System Busy |
E.g.
{"id":"e", "alias":"System Busy"}
Note
目前所有对象的id字段不能包含空格，特殊字符或句点。
Complete Example
{
"time": {
"start": "1y-ago",
"aggregator":"sum"
},
"filters": [
{
"tags": [
{
"type": "wildcard",
"tagk": "host",
"filter": "web*",
"groupBy": true
}
],
"id": "f1"
}
],
"metrics": [
{
"id": "a",
"metric": "sys.cpu.user",
"filter": "f1",
"fillPolicy":{"policy":"nan"}
},
{
"id": "b",
"metric": "sys.cpu.iowait",
"filter": "f1",
"fillPolicy":{"policy":"nan"}
}
],
"expressions": [
{
"id": "e",
"expr": "a + b"
},
{
"id":"e2",
"expr": "e * 2"
},
{
"id":"e3",
"expr": "e2 * 2"
},
{
"id":"e4",
"expr": "e3 * 2"
},
{
"id":"e5",
"expr": "e4 + e2"
}
],
"outputs":[
{"id":"e5", "alias":"Mega expression"},
{"id":"a", "alias":"CPU User"}
]
}
Response
输出将包含outputs数组中的对象列表，结果将在一个数组数组中表示每个时间序列，然后是每个系列的元数据和整个查询。还包括原始查询和一些摘要统计信息。字段包括：
| Name | Description |
|---|---|
| id | 输出匹配的表达式 ID |
| dps | 结果数组。每个子数组均以时间戳(以毫秒为单位)作为第一个(偏移 0)值开始。剩余的值是应用 group by 时每个系列的结果。 |
| dpsMeta | 查询周围的元数据，包括第一个和最后一个时间戳，结果“集”或子数组的数目以及表示的序列数。 |
| datapoints | 聚合后返回给用户的数据点总数 |
| meta | 有关结果集中每个时间序列的数据。字段如下 |
meta 部分包含有关输出数组中每个时间序列的有序信息。数组中的第一个元素将始终具有metrics值timestamp且没有其他数据。
| Name | Description |
|---|---|
| index | 元指向的数据点数组中的索引 |
| metrics | 表达式中包含的不同度量标准名称 |
| commonTags | 标记所有在整个时间序列中通用的键和值，并汇总到结果序列中 |
| aggregatedTags | 标记键出现在所得系列的所有系列中，但值不同 |
| dps | 发出的数据点数 |
| rawDps | 包装到结果中的原始值数 |
Example Responses
{
"outputs": [
{
"id": "Mega expression",
"dps": [
[
1431561600000,
1010,
1030
],
[
1431561660000,
"NaN",
"NaN"
],
[
1431561720000,
"NaN",
"NaN"
],
[
1431561780000,
1120,
1140
]
],
"dpsMeta": {
"firstTimestamp": 1431561600000,
"lastTimestamp": 1431561780000,
"setCount": 4,
"series": 2
},
"meta": [
{
"index": 0,
"metrics": [
"timestamp"
]
},
{
"index": 1,
"metrics": [
"sys.cpu",
"sys.iowait"
],
"commonTags": {
"host": "web01"
},
"aggregatedTags": []
},
{
"index": 2,
"metrics": [
"sys.cpu",
"sys.iowait"
],
"commonTags": {
"host": "web02"
},
"aggregatedTags": []
}
]
},
{
"id": "sys.cpu",
"dps": [
[
1431561600000,
1,
2
],
[
1431561660000,
3,
0
],
[
1431561720000,
5,
0
],
[
1431561780000,
7,
8
]
],
"dpsMeta": {
"firstTimestamp": 1431561600000,
"lastTimestamp": 1431561780000,
"setCount": 4,
"series": 2
},
"meta": [
{
"index": 0,
"metrics": [
"timestamp"
]
},
{
"index": 1,
"metrics": [
"sys.cpu"
],
"commonTags": {
"host": "web01"
},
"aggregatedTags": []
},
{
"index": 2,
"metrics": [
"sys.cpu"
],
"commonTags": {
"host": "web02"
},
"aggregatedTags": []
}
]
}
],
"statsSummary": {
"datapoints": 0,
"rawDatapoints": 0,
"aggregationTime": 0,
"serializationTime": 33,
"storageTime": 77,
"timeTotal": 148.63
},
"query": {
"name": null,
"time": {
"start": "1y-ago",
"end": null,
"timezone": null,
"downsampler": null,
"aggregator": "sum"
},
"filters": [
{
"id": "f1",
"tags": [
{
"tagk": "host",
"filter": "web*",
"group_by": true,
"type": "wildcard"
}
]
}
],
"metrics": [
{
"metric": "sys.cpu",
"id": "a",
"filter": "f1",
"aggregator": null,
"fillPolicy": {
"policy": "nan",
"value": "NaN"
},
"timeOffset": null
},
{
"metric": "sys.iowait",
"id": "b",
"filter": "f1",
"aggregator": null,
"fillPolicy": {
"policy": "nan",
"value": "NaN"
},
"timeOffset": null
}
],
"expressions": [
{
"id": "e",
"expr": "a + b"
},
{
"id": "e2",
"expr": "e * 2"
},
{
"id": "e3",
"expr": "e2 * 2"
},
{
"id": "e4",
"expr": "e3 * 2"
},
{
"id": "e5",
"expr": "e4 + e2"
}
],
"outputs": [
{
"id": "e5",
"alias": "Woot!"
},
{
"id": "a",
"alias": "Woot!2"
}
]
}
}
