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. Null 值和无穷值

用户入门指南

添加数据源

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

创建仪表盘

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

变量

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

静态和多值变量

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

${variable_name}

如果使用 Multi-value 变量，其中一次可以选择多个值，请参阅 Grafana 关于格式化变量的文档。 我们建议以 csv 格式注入 Multi-value 变量，然后使用 sv 运算符在 kdb+ 中将它们拆分并转换为所需类型的列表，例如在以下 select 语句中

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

时间变量

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

这可以通过将 *毫秒* 调整为 *秒* （除以 1000），使用 .Q.f 转换为十进制字符串，然后 tokking 为时间戳来完成

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

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

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

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

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

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

查询和链式变量

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

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

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

安全性

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

kdb+ 查询

查询以双项同步查询的形式传递给 kdb+（将由 .z.pg 评估），格式如下 kdb+

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

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

数据源信息对象

用户信息对象

查询信息对象

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

查询的 __from 和 __to 时间范围 (2 item timestamp list)

警报

在创建警报之前，请在 “Alerting -> contact points” 下创建联系点。 然后在 “Alerting -> notification policy” 下创建通知策略。

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

时区

kdb+ 以时区无关的形式存储其时间戳和日期时间； 这些将被 Grafana 解释为没有时区偏移 (UTC)，因此我们建议用户将使用此插件的任何仪表板的时区设置为 UTC。 这可以在 Dashboard settings - Time options - Timezone 中完成。

限制

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

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

列

列必须是单一的常量数据类型 - 列中不能有混合列表或嵌套列表（排除 string 列和分组条目，请参阅下面的 分组表处理）。

分组表处理

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

空值和无穷大