跳到主要内容
版本:0.6

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 中的数据库名。

GreptimeDB 的 HTTP API

GreptimeDB 同样暴露了一个自己的 HTTP API 用于 PromQL 查询,即在当前的 API 路径 /v1 的后方拼接 /promql,如下示例:

curl -X GET \
-H 'Authorization: Basic {{authorization if exists}}' \
-G \
--data-urlencode 'db=public' \
--data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
--data-urlencode 'start=1667446797' \
--data-urlencode 'end=1667446799' \
--data-urlencode 'step=1s' \
http://localhost:4000/v1/promql

接口中的参数和 Prometheus' HTTP API 的 range_query 接口相似:

  • db=<database>:在使用 GreptimeDB 进行鉴权操作时必填。
  • query=<string>:必填。Prometheus 表达式查询字符串。
  • start=<rfc3339 | unix_timestamp>:必填。开始时间戳,包含在内。它用于设置 TIME INDEX 列中的时间范围。
  • end=<rfc3339 | unix_timestamp>:必填。结束时间戳,包含在内。它用于设置 TIME INDEX 列中的时间范围。
  • step=<duration | float>:必填。查询步长,可以使用持续时间格式或秒数的浮点数。

以下是每种参数的类型的示例:

  • rfc3339
    • 2015-07-01T20:11:00Z (default to seconds resolution)
    • 2015-07-01T20:11:00.781Z (with milliseconds resolution)
    • 2015-07-02T04:11:00+08:00 (with timezone offset)
  • unix timestamp
    • 1435781460 (default to seconds resolution)
    • 1435781460.781 (with milliseconds resolution)
  • duration
    • 1h (1 hour)
    • 5d1m (5 days and 1 minute)
    • 2 (2 seconds)
    • 2s (also 2 seconds)

结果格式与HTTP 协议中描述的 /sql 接口相同。

{
"code": 0,
"output": [
{
"records": {
"schema": {
"column_schemas": [
{
"name": "ts",
"data_type": "TimestampMillisecond"
},
{
"name": "AVG(system_metrics.cpu_util)",
"data_type": "Float64"
},
{
"name": "AVG(system_metrics.memory_util)",
"data_type": "Float64"
},
{
"name": "AVG(system_metrics.disk_util)",
"data_type": "Float64"
}
]
},
"rows": [
[
1667446798000,
80.1,
70.3,
90
],
[
1667446799000,
80.1,
70.3,
90
]
]
}
}
],
"execution_time_ms": 5
}

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 支持在单个表(或在 Prometheus 中称为指标)中查询多个字段。默认情况下,查询将应用于每个值字段 (field)。或者也可以使用特殊的过滤器 __field__ 来查询特定的字段:

metric{__field__="field1"}

反选或正则表达式也都支持

metric{__field__!="field1"}

metric{__field__=~"field_1|field_2"}

metric{__field__!~"field_1|field_2"}

局限

尽管 GreptimeDB 支持丰富的数据类型,但 PromQL 的实现仍然局限于以下类型:

  • timestamp: Timestamp
  • tag: String
  • value: Double

目前 GreptimeDB 只支持 PromQL 的一个子集,下方附上了兼容性列表。你也可以在跟踪问题中查看我们最新的兼容性报告。

字符(Literal)

支持字符串和浮点数,与 PromQL 的规则相同。

选择器

  • 支持即时和范围选择器,但唯独不支持 label 和指标名字的不匹配判断,例如 {__name__!="request_count}",等价匹配的情况是支持的,例如 {__name__="request_count}"
  • 支持时间长度和偏移量,但不支持 @ 修改器。

Binary

目前还不支持像 1+1 这样纯粹的 binary 表达式。

  • 支持:

    OperatorExample
    adda + b
    suba - b
    mula * b
    diva / b
    moda % b
    eqlca == b
    neqa != b
    gtra > b
    lssa < b
    gtea >= b
    ltea <= b
  • 不支持:

    OperatorProgress
    powerTBD
    atan2TBD
    andTBD
    orTBD
    unlessTBD

Aggregators

  • 支持:

    AggregatorExample
    sumsum by (foo)(metric)
    avgavg by (foo)(metric)
    minmin by (foo)(metric)
    maxmax by (foo)(metric)
    stddevstddev by (foo)(metric)
    stdvarstdvar by (foo)(metric)
  • 不支持:

    AggregatorProgress
    countTBD
    groupingTBD
    topkTBD
    bottomkTBD
    count_valuesTBD

Instant Functions

  • 支持:

    FunctionExample
    absabs(metric)
    ceilceil(metric)
    expexp(metric)
    lnln(metric)
    log2log2(metric)
    log10log10(metric)
    sqrtsqrt(metric)
    acosacos(metric)
    asinasin(metric)
    atanatan(metric)
    sinsin(metric)
    coscos(metric)
    tantan(metric)
    acoshacosh(metric)
    asinhasinh(metric)
    atanhatanh(metric)
    sinhsinh(metric)
    coshcosh(metric)
    tanhtanh(metric)
    timestamptimestamp()
    histogram_quantilehistogram_quantile(phi, metric)
  • 不支持:

    FunctionProgress
    absentTBD
    scalarTBD
    sgnTBD
    sortTBD
    sort_descTBD
    degTBD
    radTBD
    other multiple input fnsTBD

Range Functions

  • 支持:
    FunctionExample
    ideltaidelta(metric[5m])
    <aggr>_over_timecount_over_time(metric[5m])
    stddev_over_timestddev_over_time(metric[5m])
    stdvar_over_timestdvar_over_time(metric[5m])
    changeschanges(metric[5m])
    deltadelta(metric[5m])
    raterate(metric[5m])
    derivderiv(metric[5m])
    increaseincrease(metric[5m])
    irateirate(metric[5m])
    resetreset(metric[5m])