Prometheus Query Language
GreptimeDB 可以作为 Grafana 中 Prometheus 的替代品,因为 GreptimeDB 支持 PromQL(Prometheus Query Language)。GreptimeDB 在 Rust 中重新实现了 PromQL,并通过接口将能力开放,包括 Prometheus 的 HTTP API、GreptimeDB 的 HTTP API 和 SQL 接口。
Prometheus 的 HTTP API
GreptimeDB 实现了兼容 Prometheus 的一系列 API,通过 /v1/prometheus
路径对外提
供服务:
- Instant queries
/api/v1/query
- Range queries
/api/v1/query_range
- Series
/api/v1/series
- Label names
/api/v1/labels
- Label values
/api/v1/label/<label_name>/values
这些接口的输入和输出与原生的 Prometheus HTTP API 相同,用户可以把 GreptimeDB 当
作 Prometheus 的直接替换。例如,在 Grafana 中我们可以设置
http://localhost:4000/v1/prometheus/
作为其 Prometheus 数据源的地址。
访问 Prometheus 文档 获得更详细的说明。
你可以通过设置 HTTP 请求的 db
参数来指定 GreptimeDB 中的数据库名。
例如,以下查询将返回 public
数据库中 process_cpu_seconds_total
指标的 CPU 使用率:
curl -X POST \
-H 'Authorization: Basic {{authorization if exists}}' \
--data-urlencode 'query=irate(process_cpu_seconds_total[1h])' \
--data-urlencode 'start=2024-11-24T00:00:00Z' \
--data-urlencode 'end=2024-11-25T00:00:00Z' \
--data-urlencode 'step=1h' \
'http://localhost:4000/v1/prometheus/api/v1/query_range?db=public'
如果你使用启用了身份验证的 GreptimeDB,则需要 Authorization header,请参阅鉴权。
该 API 的查询字符串参数与原始 Prometheus API 的查询字符串参数相同。
你需要在 HTTP 的 query param 设置 db
参数,或者通过 --header 'x-greptime-db-name: <database name>'
设置在 HTTP 请求头中。
输出格式与 Prometheus API 完全兼容:
{
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {
"job": "node",
"instance": "node_exporter:9100",
"__name__": "process_cpu_seconds_total"
},
"values": [
[
1732618800,
"0.0022222222222222734"
],
[
1732622400,
"0.0009999999999999788"
],
[
1732626000,
"0.0029999999999997585"
],
[
1732629600,
"0.002222222222222175"
]
]
}
]
}
}
SQL
GreptimeDB 还扩展了 SQL 语法以支持 PromQL。可以用 TQL
(Time-series Query Language)为关键字开始写入参数和进行查询。该语法如下:
TQL [EVAL|EVALUATE] (<START>, <END>, <STEP>) <QUERY>
<START>
指定查询开始时间范围,<END>
指定查询结束时间。 <STEP>
识别查询步幅。它们均可为无引号数字(表示<START>
和<END>
的 UNIX 时间戳,以及<STEP>
的秒数持续时间),或带引号的字符串(表示<START>
和<END>
的 RFC3339 时间戳,以及<STEP>
的字符串格式的持续时间)。
例如:
TQL EVAL (1676738180, 1676738780, '10s') sum(some_metric)
你可以在所有支持 SQL 的地方编写上述命令,包括 GreptimeDB HTTP API、SDK、PostgreSQL 和 MySQL 客户端等。
GreptimeDB 的扩展
指定数值列
基于表模型,GreptimeDB 支持在单个表(或在 Prometheus 中称为指标)中查询多个字段。默认情况下,查询将应用于每个值字段 (field)。或者也可以使用特殊的过滤器 __field__
来查询特定的字段:
metric{__field__="field1"}
反选或正则表达式也都支持
metric{__field__!="field1"}
metric{__field__=~"field_1|field_2"}
metric{__field__!~"field_1|field_2"}
指定数据库
不同于 Prometheus,GreptimeDB 包含数据库概念。如果要进行跨数据库的 PromQL 查询,
可以使用 __database__
来指定数据库名称。
metric{__database__="mydatabase"}
注意 __database__
仅支持 =
匹配。
局限
尽管 GreptimeDB 支持丰富的数据类型,但 PromQL 的实现仍然局限于以下类型:
- timestamp:
Timestamp
- tag:
String
- value:
Double
GreptimeDB 目前已实现了大部分(超过 90%)的 PromQL 功能。您可以在下方查看详细的兼容性列表,或者通过此 issue 了解我们最新的功能支持情况。
选择器引用不存在的列时,其行为与 Prometheus 一致:不报错且选择器会被静默忽略。但若 __name__
选择器引用了不存在的指标(或等效形式),GreptimeDB 则会报告错误。
支持字符串和浮点数,与 PromQL 的规则相同。