用户指南系列 | 使用 Greptime 官方工具高效地进行 PromQL 查询

背景

PromQL 是 Prometheus 监控系统的查询语言，用于对时序数据进行查询、分析和聚合。PromQL 以表达式能力强大、简洁、逻辑清晰著称，GreptimeDB 作为时序数据库当然对其进行了（目前还是部分）支持。目前，GreptimeDB 在 Rust 中重新实现了 PromQL 的解析，并通过接口将能力开放。

通过 GreptimeDB 提供的接口，我们开发出各语言版本的 SDK 并且也在 GreptimeCloud 控制台（下面将它称为 Dashboard）中应用这些接口。本文将简单介绍它在 Dashboard 和 JS-SDK 中的使用。

GreptimeDB 实现了 Prometheus HTTP API 中的 range_query 接口，如下：

bash

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

建表

在开始之前，我们需要下载 GreptimeDB，过程详情请参见 Dashboard｜GitHub。下载并运行 GreptimeDB 后，可在 http://localhost:4000/dashboard/playground 页面的指引下完成建表。

你也可以选择尝试一下我们的云服务，目前处于限免预览期：https://console.greptime.cloud/

我们通过 SQL 进行建表，下面是一个简单的参考：

shell

CREATE TABLE IF NOT EXISTS cpu_metrics (
    hostname STRING,
    environment STRING,
    usage_user DOUBLE,
    usage_system DOUBLE,
    usage_idle DOUBLE,
    ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP TIME INDEX,
    PRIMARY KEY(hostname, environment)
);

这里的 PRIMARY KEY 对应表模型中 标签列（Tag Columns） 的概念，后面将详细说明。

同样，我们可以通过 SQL 插入几条数据：

shell

INSERT INTO cpu_metrics
VALUES
    ('host_0','test',32,58,36,1680307200),
    ('host_1','test',29,65,20,1680307200),
    ('host_1','staging',12,32,50,1680307200),
    ('host_2','staging',67,15,42,1680307200);

表模型

GreptimeDB 的表模型基于关系型数据库，同时考虑到了时序数据的特点，可简单理解为增加了 Timestamp (ts)列，它用于指定 ts 列作为该表的时间索引列。

GreptimeDB 中的所有数据都被组织成表，它由四个部分组成：表名 Table Name（指标）、标签列（Tag Columns）、度量列（Field Columns）和时间索引列（Timestamp）。

这里有一点需要注意，GreptimeDB 将全部的标签列（Tag Columns）作为 Primary Key 使用。

表模型详情可参见 GreptimeDB 文档。

Dashboard

下图是 Dashboard 对 range_query 的简单使用：

这里可以通过界面交互的方式，进行时间范围的选择以及 Step 值的设置，对应着 start, end, step 三个参数。可以简单选择一个最近时间，也可选取一个时间段；
参数 db 会被自动带上，值为当前 dashboard 所使用的 db 值，无需过多关注；
用户只需要关注 query 的写入即可；
需要注意的是，当指标的 value 值中出现非 Double 类型的时候，PromQL 的计算函数将不可用，例如：（Tips: 第一行为 Timestamp，二三行为 Primary Key，后面几行则为 Field Columns）

此时的 up 是一个 String 类型的 value，当我们对 bilibili_video_list_info_new 这个指标进行运算的时候便会获得一个报错，如下图所示：

为什么指标中会出现 String 类型的 value 呢？其原因在于，在 GreptimeDB 中，我们需要使用 SQL 语句进行建表操作，此时可以允许非 Double 类型的 value 存在（此处表的概念可近似理解为指标）。

如果希望在 GreptimeDB 中更好地使用 PromQL 语句进行查询，建议不要将 value 指定为其他非 Double 类型。

greptime-js-sdk

如果想在自己的 Node.js 项目或者网站中使用 GreptimeDB，可以使用我们的 JS-SDK。

地址：https://github.com/GreptimeTeam/greptime-js-sdk

安装：

shell

npm i greptime

简单使用：

javascript

// use in your project
import greptime from 'greptime'

const { sql, promql} = greptime({
    host: 'your_host',
    dbname: 'your_dbname',
    username: 'your_username',
    password: 'your_password'
})

// if you download the greptime and run it locally, you can use {} as the parameter ⬇️
const { sql, promql} = greptime({})

// to use promql ⬇️
const resOfDuration = await promql.query('your_metrics')
    .duration('5m')
    .step('1s')
    .run()

// or select time bucket ⬇️
const res = await promql.query('your_metrics')
    .start('start_time')
    .end('end_time')
    .step('1s')
    .run()

首先我们调用 greptime() 函数，将{ host, dbname, username, password } 作为参数。
- 你可以在 GreptimeCloud 中创建一个 service 来获取以上参数（service 为云端数据库）。
- 或者在 GreptimeDB Download 页面下载 Greptime 数据库并在本地运行（如上 Dashboard），这样则可以使用 { } 作为参数传递。
greptime() 函数返回 SQL 与 PromQL 两个实例，SQL 实例中包括建表与增删查等操作，这里便不展开讨论。
我们一起来看看 PromQL 实例，PromQL 实现了链式调用，更方便开发者使用与理解，下面是 PromQL 相关函数说明：

函数说明
query: 必须，需传入一个指标名或 PromQL 中的函数 sum(), avg() 等，类型为 String。例如：query('avg(your_metrics)')。
start，end：可选，且与下面的duration 二选一。起始时间与结束时间，需成对出现，需传入一个时间戳，类型为 number。
duration：可选，需传入一个时间段，类型为 String，例如：duration('10m')，不传入参数则默认为'5m'，意思为选取 5 分钟前到当前时间这个时间段。若不使用 duration 或（start, end) 函数，则默认duration('5m')。
step：可选，传入一个查询步长，类型为 String，例如：step('10s')，若不使用 step 则默认查询步长为'1s'。
run：必须，无参数，用于执行 PromQL 查询操作。