Grafana对接PostgreSQL单查询时Status Timeline异常如何解决

大部分同类问题都是数据格式不匹配、面板配置错、时间序列不连续这三类原因，按以下步骤排查即可：

1. 先修正查询返回的字段格式 #

别只看字段数量对不对，字段类型、语义、别名错了都会导致渲染完全不符合预期：

• 时间字段必须是PostgreSQL的timestamp/timestamptz类型，不能直接返回字符串、存为bigint的unix时间戳。如果是数值型时间戳必须用to_timestamp(你的时间字段)做类型转换，字段别名固定用time，不要用ts、create_time这类自定义别名，避免Grafana识别失败。
• 状态值字段（你提到的变量计数值）不能是连续波动的数值，Status Timeline只渲染离散状态，如果你直接传原始计数值，Grafana会把每个不同的数值都当成独立状态，最终渲染成密密麻麻的碎块。需要在SQL里先做离散映射，比如：

  CASE
    WHEN cnt_value > 0 THEN '运行中'
    WHEN cnt_value = 0 THEN '离线'
    ELSE '异常'
  END AS status
  

• 分组字段（你提到的计数变量名称）必须是字符串类型，用来作为时间轴每一行的展示名称，不要传数值型ID。

2. 修正面板查询与转换配置 #

很多人SQL写对了，配置错了一样出不来效果：

• 如果你返回的是长格式三列表（时间、状态值、变量名），查询配置里的Format选项必须选Table，不能选默认的Time series。选完之后到面板的Transform标签页添加Partition by values转换：分组字段选你的变量名称列，值字段选状态值列，时间字段选你的time列，这一步是长格式数据能正确按行分组渲染的核心。
• 如果你返回的是宽格式表（时间、变量A状态、变量B状态、变量C状态），Format选Time series即可，不需要额外加转换。
• 到面板的Standard options配置里，把Null value处理设为Connected，避免两个状态点之间因为空值出现断条；Min interval设为和你数据采样间隔一致的值，不要设太大导致状态点采样丢失。
• 初期调试可以先关掉面板配置里的Show value选项，避免状态块过窄时值文本挤成一团，等渲染形状正常后再按需开启，同时在Value mapping里给不同状态配置对应展示颜色。

3. 解决时间点不连续导致的细条/空白问题 #

如果你的数据是状态变更才写入的日志型数据（不是固定间隔采样的时序数据），直接查原始表只会在每个状态变更的时间点渲染一个细条，中间全是空白。需要在SQL里补全连续时间点，匹配每个时间点对应的状态，参考模板：

WITH time_buckets AS (
  -- 生成当前查询时间范围内的连续时间点，间隔按实际采样精度调整
  SELECT generate_series(
    $__timeFrom()::timestamptz,
    $__timeTo()::timestamptz,
    '30 seconds'::interval
  ) AS time
),
state_change_log AS (
  SELECT
    log_time,
    metric_name,
    status_value,
    -- 取每个指标当前状态的结束时间点
    LEAD(log_time) OVER (PARTITION BY metric_name ORDER BY log_time) AS end_time
  FROM your_metric_table
  WHERE log_time BETWEEN $__timeFrom() AND $__timeTo()
)
SELECT
  t.time,
  s.metric_name,
  s.status_value
FROM time_buckets t
LEFT JOIN state_change_log s
  ON t.time >= s.log_time AND (s.end_time IS NULL OR t.time < s.end_time)
WHERE s.metric_name IS NOT NULL
ORDER BY t.time

4. 版本兼容问题 #

如果你用的是Grafana 9.0之前的版本，原生Status Timeline插件存在长格式数据识别bug，升级到9.5以上或者10.x稳定版即可，不需要额外调整配置。

内容的提问来源于stack exchange，提问作者Jorge Lopez Marcos