即时查询功能介绍
夜莺即时查询类似 Prometheus 自带的 Graph UI，主要用于调试 PromQL。调试好的 PromQL 可以继续用于告警规则、仪表盘、指标视图等场景。
为了提升用户体验，夜莺在 PromQL 查询、结果展示、时间戳可读性、单位转换、历史记录和多 Panel 对比等方面做了一些优化。图中标注了多个字母，下面按字母逐项说明。
阅读时可以先记住两个视图：
| 视图 | 接口 | 适合场景 | 展示方式 |
|---|---|---|---|
| Table 视图 | /api/v1/query |
查询某个时刻的最新值或即时结果 | 表格/向量结果 |
| Graph 视图 | /api/v1/query_range |
查询一段时间内的趋势 | 折线图 |
a. 数据源类型
时序数据源方面，开源版本支持 Prometheus Like 数据源类型和 TDEngine，商业版本还支持 ClickHouse、InfluxDB、MySQL 等其他类型。
b. 数据源选择
数据源管理位于：集成中心-数据源。类似 Grafana 那种方式，配置各种数据源。如果即时查询的数据源列表为空，则要先去集成中心配置数据源。
c. autocomplete
是否启用 PromQL 的自动补全，默认开启。如果你的 TSDB 有巨量数据，可以关闭自动补全，以防 OOM。
d. 内置指标
内置指标是提前整理好的一些 PromQL，方便用户快速查询。新版本夜莺安装完成后，会自动导入一些内置指标。你也可以添加自己常用的 PromQL，菜单位置在 时序指标-指标视图。
内置指标是存在关系库中的，跟 TSDB 中的数据是两码事，请注意。
e. PromQL 编辑器
这个位置就是写 PromQL 的地方。按 Shift+Enter 可以换行。你要查什么数据，就在这里输入什么指标，然后点击查询即可。PromQL 是玩转 Prometheus、夜莺的必备技能，如果你还不了解 PromQL，可以学习这个系列：PromQL入门教程。
f. 小地球 icon
点击小地球 icon，弹层里会展示指标列表，这是从 TSDB 中实时获取的指标列表，方便你快速查询。和内置指标的来源不同。
g. 历史记录
历史记录是你之前查询的 PromQL，方便你快速查找。这个数据保存在浏览器的 local storage 里。
h. Table 视图
查询结果分两个视图。Table 视图调用 /api/v1/query 接口，是 instant query，用于查看某个时间点的查询结果。Graph 视图调用 /api/v1/query_range 接口，是 range query，用于查看一段时间内的趋势，结果渲染为折线图。
i. 时间戳选择
按照 Prometheus 的规范，instant query 需要传参 time，即时间戳，这个时间戳是秒级的，如果你想查询历史上的某个时刻的数据，可以通过这个时间戳选择器选择对应的时间。
当然了，返回的结果中的时间戳是经过对齐的，不是真实的时间戳，如果想真实查看历史数据以及时间戳，应该使用带有时间范围的 PromQL，比如下图所示：
上例中 PromQL 后面加了 [1m]，表示查询过去 1 分钟的数据。此时返回的数据中的时间戳是真实的。另外为了方便用户查看，夜莺会自动把时间戳展示为人类可读的时间，并且会自动计算两个时间戳之间的差值，即那个 +15 就表示两个时间戳之间相差 15 秒。这种展示方式非常便于排查问题。
如果你搞不懂什么情况下返回的时间戳是真实的，什么情况下不是，可以阅读上面提到的 PromQL 的系列教程，或者问问 GPT、Google，这里不再赘述。
j. 单位选择
返回的数据可以选择单位，展示会更直观。如果你不确定应该选什么单位，就选择 none，即展示原始值，不做单位换算。
k. vector 结果
PromQL 查询结果是一堆 vector，即一堆时间序列。这个位置展示的是查询结果。绿色的是指标名，大括号里是标签，标签是 key=value 的形式，方便你区分不同的时间序列。
如果对 Prometheus 的数据格式不清楚，也可以阅读上面提到的 PromQL 的系列教程。这里不再赘述。
l. 结果
这个位置展示的是时间序列的结果值，上面的单位就是对这个结果生效的，可以随意调整单位看看这个结果值的变化。
m. Graph 视图
如果想查看某个指标最新的值，就使用 Table 视图走即时查询，如果想查看某个指标的历史走势图，就用 Graph 视图。
n. 时间范围
Graph 视图是展示历史趋势的，自然要选择一个时间范围。
o. step 参数
Prometheus 体系里查询历史数据，需要传参 step，即步长，这个步长是秒级的，夜莺默认会根据你选择的时间范围自动计算，你也可以手动调整。step 参数的作用是控制返回的数据点个数，如果你的时间范围很大，数据点很多，可以调大 step，减少数据点个数，以减轻前端渲染压力。
由于引入了 step 机制，所以 Graph 视图里返回的数据，其时间戳不是真实数据的真实时间戳，而是跟你查询的时间和 step 参数有关。具体可以参考 PromQL 的系列教程。
p. 折线图
默认就是使用折线图来展示数据。
q. 堆叠图
堆叠图通常用不到。只有少数场景看堆叠图会相对方便，比如同时在一个图里展示内存使用量和内存剩余量。但堆叠图的 y 轴值可能让人困惑，如果不理解堆叠图的含义，建议平时直接忽略。
r. 分享按钮
点击分享按钮，打开一个光秃秃的页面，可以拷贝 URL 链接分享给你的同事。你的同事即便没有登录夜莺，也可以查看这个图。但是这有个前提，就是夜莺的配置文件里需要把匿名查看开启。而显然，这样安全性不好，所以默认匿名查看是关闭的。
s. Unit
和 Table 视图里的单位是一个意思。
t. Show legend
是否展示图例，点击一下看看效果，效果一目了然。即时查询页面空间比较多，所以一般都是展示 Legend。
u. Multi Tooltip
这个设置，如果图上只有一条线，看不出区别，如果图上有两条线以上，就可以看出区别了。
选中，鼠标移动到图上的某个点，会显示 Tooltip，Tooltip 里会展示所有线的信息，如果不选中，Tooltip 只会展示鼠标所在的那条线的信息。
v. Tooltip 排序
如果选中了 Multi Tooltip，则可以对 Tooltip 里的数据排序，方便查看。
w. 增加 Panel
有时想对比多个数据一起查看，可以增加 Panel。对于新增加的 Panel 如果想关闭，点击 Panel 右上角的小 x 即可。
常见使用路径
如果你是第一次使用即时查询，可以按这个顺序操作：
- 在
集成中心-数据源中确认已有可用数据源。 - 进入即时查询页面，选择数据源类型和具体数据源。
- 在 PromQL 编辑器中输入指标或表达式，也可以从内置指标或小地球指标列表中选择。
- 使用 Table 视图检查即时结果，确认标签和值是否符合预期。
- 切换到 Graph 视图，选择时间范围和 step，观察历史趋势。
- 根据需要调整单位、图例、Tooltip 和 Panel。
- 将调试好的 PromQL 复用到告警规则、仪表盘或指标视图中。
FAQ
Q1：Table 视图和 Graph 视图应该怎么选？
A：看最新值或某个时间点结果，用 Table 视图；看历史趋势，用 Graph 视图。
Q2：为什么 Graph 视图里的时间戳不一定是真实采样时间？
A：Graph 视图走 range query，会受到查询时间范围和 step 参数影响，返回结果会按 step 对齐。
Q3：内置指标和小地球里的指标有什么区别？
A：内置指标是夜莺关系库中预先整理的 PromQL；小地球弹层展示的是从 TSDB 实时获取的指标列表。
总结
夜莺即时查询是可视化的基础功能。通过即时查询可以方便调试 PromQL，调试好的 PromQL 可以用在告警规则、仪表盘等地方。本文详细介绍了即时查询页面的所有功能点。希望对你有所帮助。
