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,如下示例:

  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 接口相同。

  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)为关键字开始写入参数和进行查询。该语法如下:

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

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

例如:

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

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

多列查询

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

  1. metric{__field__="field1"}

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

  1. metric{__field__!="field1"}
  2. metric{__field__=~"field_1|field_2"}
  3. 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])