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，如下示例：

shell

  1. curl -X GET \
  2.   -H 'Authorization: Basic {{authorization if exists}}' \
  3.   -G \
  4.   --data-urlencode 'db=public' \
  5.   --data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
  6.   --data-urlencode 'start=1667446797' \
  7.   --data-urlencode 'end=1667446799' \
  8.   --data-urlencode 'step=1s' \
  9.   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 接口相同。

json

  1. {
  2.   "code": 0,
  3.   "output": [
  4.     {
  5.       "records": {
  6.         "schema": {
  7.           "column_schemas": [
  8.             {
  9.               "name": "ts",
  10.               "data_type": "TimestampMillisecond"
  11.             },
  12.             {
  13.               "name": "AVG(system_metrics.cpu_util)",
  14.               "data_type": "Float64"
  15.             },
  16.             {
  17.               "name": "AVG(system_metrics.memory_util)",
  18.               "data_type": "Float64"
  19.             },
  20.             {
  21.               "name": "AVG(system_metrics.disk_util)",
  22.               "data_type": "Float64"
  23.             }
  24.           ]
  25.         },
  26.         "rows": [
  27.           [
  28.             1667446798000,
  29.             80.1,
  30.             70.3,
  31.             90
  32.           ],
  33.           [
  34.             1667446799000,
  35.             80.1,
  36.             70.3,
  37.             90
  38.           ]
  39.         ]
  40.       }
  41.     }
  42.   ],
  43.   "execution_time_ms": 5
  44. }

SQL

GreptimeDB 还扩展了 SQL 语法以支持 PromQL。可以用 TQL（Time-series Query Language）为关键字开始写入参数和进行查询。该语法如下：

sql

  1. TQL [EVAL|EVALUATE] (<START>, <END>, <STEP>) <QUERY>

<START> 指定查询开始时间范围，<END> 指定查询结束时间。 <STEP> 识别查询步幅。它们均可为无引号数字（表示<START>和<END>的 UNIX 时间戳，以及<STEP>的秒数持续时间），或带引号的字符串（表示<START>和<END>的 RFC3339 时间戳，以及<STEP>的字符串格式的持续时间）。

例如:

sql

  1. TQL EVAL (1676738180, 1676738780, '10s') sum(some_metric)

你可以在所有支持 SQL 的地方编写上述命令，包括 GreptimeDB HTTP API、SDK、PostgreSQL 和 MySQL 客户端等。

局限

尽管 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
    quantileTBD

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)

  • 不支持:

    FunctionProgress
    absentTBD
    scalarTBD
    sgnTBD
    sortTBD
    sort_descTBD
    timestampTBD
    acoshTBD
    asinhTBD
    atanhTBD
    sinhTBD
    coshTBD
    tanhTBD
    degTBD
    radTBD
    other multiple input fnsTBD

Range Functions

  • 支持:

    FunctionExample
    ideltaidelta(metric[5m])
    <aggr>_over_timecount_over_time(metric[5m])

  • 不支持:

    FunctionExample
    stddev_over_timeTBD
    stdvar_over_timeTBD
    changesTBD
    deltaTBD
    rateTBD
    derivTBD
    increaseTBD
    ideltaTBD
    irateTBD
    resetTBD