Grafana KDB+ 后端数据源

什么是 KDB+ 后端数据源？

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

内容

1. 用户入门
2. 变量
   1. 静态变量和多值变量
   2. 时间变量
   3. 查询和链式变量
3. 安全
4. kdb+ 查询
5. 警报
6. 时区
7. 限制
   1. 列
   2. 分组表格处理
   3. 空值和无穷大

用户入门

添加数据源

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

创建仪表盘

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

变量

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

静态变量和多值变量

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

${variable_name}

如果使用 多值 变量（可以选择多个值），请参考 Grafana 关于格式化变量的文档。建议以 csv 格式注入 多值 变量，然后使用 sv 运算符在 kdb+ 中将这些变量拆分并转换为所需类型的列表，例如在以下 select 语句中

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

时间变量

Grafana 会将时间变量（例如 ${__from}、${__to} 等）注入为自 Unix 纪元以来的毫秒数（例如 1594671549254 对应于 2020 年 7 月 13 日 20:19:09）。要在 kdb+ 中使用时间变量，我们需要对其进行操作以匹配 kdb+ 接受的格式。

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

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

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

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

截至 kdb+ 4.0 版本，无法将 ISO-8601 格式的日期时间直接 tok 转换为时间戳。

如果引用的 timestamp 仅需要精确到秒，则可以将其直接以 Unix 时间注入并使用 tok 转换为时间戳。

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

查询和链式变量

这些可以在 查询 变量类型下输入。这些变量在运行面板查询之前会对目标数据源运行查询，并且 Grafana 会根据此元查询构建一个变量/变量列表。输入查询必须返回一个 平面表（参见 限制），其中第一列将用于生成变量。在较旧版本的 Grafana 中，输出可能需要为 字符串 或 符号（在较新的 Grafana 版本中，也支持数字数据类型）。

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

查询变量也可以将其他变量作为其运行的查询的一部分（有时称为 链式 变量）。此格式与静态和多值变量相同（${variable_name}）。

安全性

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

kdb+ 查询

查询作为包含两个项目的同步查询（将由 .z.pg 评估）传递给 kdb+，其 kdb+ 格式如下

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

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

数据源信息对象

用户信息对象

查询信息对象

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

警报

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

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

时区

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

限制

所有查询必须返回一个 平面表（kdb+ 数据类型 98）或一个 分组表（kdb+ 数据类型 99，其中字典的 键 和 值 都是一致的表）。如果将聚合与 分组表 的分组一起使用，则任何聚合列都将 投影 到与数据框的其余部分相同的长度。

Grafana 中的无穷大和空值与 kdb+ 中的空值和无穷大不共享相同的数据类型。将显示一个底层字符串值表示，而不是 kdb+ 中保存的空值或无穷大。建议 Grafana 发送用户根据其数据模式、数据字典处理空值表示。

列

列必须是单个的、恒定数据类型 - 无法将混合列表或嵌套列表作为列（不包括 string 列和分组条目，参见 分组表处理 ）。

分组表处理

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

空值和无穷大

下表显示了如何处理每种数据类型的空值、无穷大和零。