Grafana KDB+ 后端数据源

什么是 KDB+ 后端数据源？

AquaQ 的 kdb+ 后端数据源是一个插件，增加了从 Grafana 查询 kdb+ 的能力。它支持 Grafana 的许多核心功能，包括静态/查询变量、告警以及对 Grafana 查询 API 的支持。

目录

1. 用户入门
2. 变量
   1. 静态和多值变量
   2. 时间变量
   3. 查询和链式变量
3. 安全性
4. kdb+ 查询
5. 告警
6. 时区
7. 限制
   1. 列
   2. 分组表处理
   3. Null 和 Infinity

用户入门

添加数据源

1. 导航到 设置 -> 数据源。
2. 点击 添加数据源 并导航到 kdb-backend-datasource。
3. 输入 KDB+ 实例的 URL 和端口，以及用户名和密码（如果需要 - 如果未提供，这些将默认为 ""）。
4. 输入超时值（毫秒），默认为 1000 毫秒。
5. 点击 保存并测试。
6. 底部应显示一条提示：kdb+ 连接成功。

创建 Dashboard

1. 从左侧工具栏导航到 创建 - Dashboard。
2. 创建一个空面板。新的 Dashboard 会默认包含一个空面板。可以使用右上角任务栏的 添加面板 按钮添加新面板。
3. 在 KDB+ 查询 字段下输入有效的 KDB+ 查询，例如 ([] time:reverse .z.p-0D00:05*til 20;val:til 20) 。
4. 可选地，可以在 超时（毫秒）输入字段中定义自定义超时。默认值为 10 000 毫秒。
5. 点击右上角面板可视化上方的 刷新 Dashboard 按钮。数据应显示在可视化中。
6. 点击页面左上角的 返回 (Esc) 按钮退出查询编辑器并返回 Dashboard。
7. 可以使用右上角的 保存 Dashboard 按钮保存 Dashboard。如果需要，可以为 Dashboard 设置自动刷新速率，点击右上角 刷新 Dashboard 按钮旁边的下拉菜单并设置您所需的刷新速率。可以在 Dashboard 设置 中添加自定义刷新速率。

变量

此插件可以处理静态和查询变量。它还允许用户链式查询。

静态和多值变量

可以使用 Grafana 的标准格式（即逗号分隔列表）在 自定义 变量类型下输入这些变量。然后，静态变量可以在查询中以如下形式使用

${variable_name}

如果使用可以同时选择多个值的多值变量，请参考 Grafana 关于变量格式化的文档。我们建议以 csv 格式注入多值变量，然后在 kdb+ 中使用 sv 操作符将其分割并转换为所需类型的列表，例如在以下 select 语句中

select from trade where exchange in `$\",\" vs "${multi_variable_name:csv}"

时间变量

时间变量（例如 ${__from} , ${__to} 等）由 Grafana 注入，表示自 Unix epoch 以来的毫秒数（例如 1594671549254 对应于 Jul 13 2020 20:19:09）。要在 kdb+ 中使用时间变量，我们需要对其进行处理，使其符合 kdb+ 接受的格式。

可以通过将毫秒除以 1000 转换为秒，然后使用 .Q.f 转换为十进制字符串，再 tok 为时间戳来实现

("P"$.Q.f[3] ${__from}%1000)

或者，可以将 Grafana 注入的时间变量格式化为 ISO-8601 格式，并在 kdb+ 中将其 tok 为 datetime 数据类型

("Z"$"${__from:date}")

从 kdb+ 4.0 版本开始，ISO-8601 格式的日期时间不能直接 tok 为时间戳。

如果引用的 timestamp 只需要精确到秒，那么可以直接注入 unix 时间并 tok 为时间戳

("P"$"${__from:date:seconds}")

查询和链式变量

可以在 Query 变量类型下输入这些变量。这些变量在面板查询运行之前对目标数据源运行一个查询，Grafana 从这个元查询构建一个变量/变量列表。输入查询必须返回一个 flat table（参见 限制），其第一列将用于生成变量。在旧版本的 Grafana 中，输出可能需要是 strings 或 symbols（在新版本的 Grafana 中，也支持数字数据类型）。

有一个可选的 Timeout 字段，如果未定义，将默认为 10 000 毫秒。变量更新后，按下 Update 按钮，页面底部将显示返回变量的预览。

查询变量也可以在其运行的查询中包含其他变量（有时称为 Chained 变量）。其格式与静态和多值变量相同（${variable_name}）

安全性

默认情况下，用户名和密码都传递空字符串 ""，可以在数据源设置中覆盖。还支持 TLS - 通过 TLS 客户端认证 开关启用。在提供的字段中输入客户端 TLS 密钥和客户端 TLS 证书。要跳过服务器对 TLS 证书的验证，请使用 跳过 TLS 验证 开关。如果启用了 使用 CA 证书 开关，则可以使用自定义证书颁发机构证书 - 如果 kdb+ 数据源运行的是自定义签名的证书，则使用此选项。

kdb+ 查询

查询以包含两个元素的同步查询形式（将由 .z.pg 评估）传递给 kdb+，形式如下

({[x] value x[`Query;`Query]};**QUERYDATA**)

**QUERYDATA** 是一个字典（kdb+ 类型 99），其嵌套结构如下

数据源信息对象

用户信息对象

查询信息对象

注意：RefID、MaxDataPoints、Interval 和 TimeRange 键在 HEALTHCHECK 类型的查询中不存在。

告警

在创建告警之前，请在 告警 -> 联系点 下创建一个联系点。然后在 告警 -> 通知策略 下创建一个通知策略。

要在面板上创建告警，请导航到相关的 Dashboard，然后从此处选择编辑选项，导航到 告警 菜单。填写相关的 规则名称、类型 和 文件夹。输入您的 kdb+ 查询并运行查询。您将能够使用表达式来查询此查询中的数据。接下来设置告警条件，确保选择表达式并设置评估持续时间。最后在 告警详情 中设置自定义标签。

时区

kdb+ 以时区无关的形式存储其时间戳和日期时间；Grafana 将其解释为没有时区偏移（UTC），因此我们建议用户将使用此插件的任何 Dashboard 的时区设置为 UTC。这可以在 Dashboard 设置 - 时间选项 - 时区 中完成。

限制

所有查询必须返回 flat table（kdb+ 数据类型 98）或 grouped table（kdb+ 数据类型 99，其中字典的 key 和 value 都是同构表）。如果在 grouped tables 的分组旁边使用聚合，则任何聚合列将被投影到与数据框其余部分相同的长度。

Grafana 中的 Infinity 和 null 与 kdb+ 中的数据类型不同。显示的是底层字符串值表示，而不是 kdb+ 中持有的 null 或 infinity 值。建议 Grafana 用户根据其数据模式、数据字典来处理 null 表示。

列

列必须是单一的、恒定的数据类型 - 不能有混合列表或嵌套列表作为列（字符串列和分组条目除外，参见下面的 分组表处理）。

分组表处理

如果评估的查询向 Grafana 返回一个 grouped table，则 Grafana 将每个分组作为单独的帧返回。每个帧的名称是每个分组键的字符串表示（如果存在多个键，则用分号分隔）。

Null 和 Infinity

下表显示了每种数据类型如何处理 null、infinity 和 zero