app/vmui: display null/NaN/staleNaN values on RawQuery chart

`null` values can be actual `NaN` or `null` values exposed by the exporter, or stale markers
 https://docs.victoriametrics.com/victoriametrics/vmagent/#prometheus-staleness-markers

 Before, vmui Raw Query was silently dropping non-numeric values.
 Displaying such values on chart could improve debugging experience.

Signed-off-by: hagen1778 <roman@victoriametrics.com>

app/vmui/packages/vmui/src/api/types.ts

@@ -3,6 +3,7 @@ export interface MetricBase {
   metric: {
     [key: string]: string;
   };
+  nullTimestamps?: number[];
 }
 
 export interface MetricResult extends MetricBase {

app/vmui/packages/vmui/src/components/Chart/ChartTooltip/ChartTooltip.tsx

@@ -16,6 +16,7 @@ export interface ChartTooltipProps {
   point: { top: number, left: number };
   unit?: string;
   statsFormatted?: SeriesItemStatsFormatted;
+  description?: ReactNode;
   isSticky?: boolean;
   info?: ReactNode;
   marker?: string;
@@ -34,6 +35,7 @@ const ChartTooltip: FC<ChartTooltipProps> = ({
   unit = "",
   info,
   statsFormatted,
+  description,
   isSticky,
   marker,
   duplicateCount = 0,
@@ -173,6 +175,7 @@ const ChartTooltip: FC<ChartTooltipProps> = ({
           ))}
         </table>
       )}
+      {description && <p className="vm-chart-tooltip__description">{description}</p>}
       {info && <p className="vm-chart-tooltip__info">{info}</p>}
     </div>
   ), u.root);

app/vmui/packages/vmui/src/components/Chart/ChartTooltip/style.scss

@@ -143,4 +143,10 @@ $chart-tooltip-y: -1 * ($padding-global + $chart-tooltip-half-icon);
     word-break: break-all;
     white-space: pre-wrap;
   }
+
+  &__description {
+    word-break: break-word;
+    white-space: pre-wrap;
+    opacity: 0.85;
+  }
 }

app/vmui/packages/vmui/src/hooks/uplot/useLineTooltip.ts

@@ -15,19 +15,65 @@ interface LineTooltipHook {
   unit?: string;
 }
 
+// Pixel proximity for detecting hover over null-timestamp X markers drawn at chart bottom.
+const NULL_HOVER_PROX = 8;
+// Half the visual marker height in CSS px (BASE_POINT_SIZE * 1.4 / 2 from scatter.ts).
+// scatter.ts lifts the marker center by this amount above yMin so the icon sits inside
+// the plot area; the hover y-anchor must match that offset.
+const NULL_MARKER_HALF_CSS = 2.8;
+
+interface NullHover {
+  seriesIdx: number;
+  timestamp: number;
+}
+
+const findNullHover = (u: uPlot): NullHover | null => {
+  const cursorLeft = u.cursor.left ?? -1;
+  const cursorTop = u.cursor.top ?? -1;
+  if (cursorLeft < 0 || cursorTop < 0) return null;
+
+  const scaleY = u.scales["1"];
+  if (!scaleY || scaleY.min == null) return null;
+  const yPos = u.valToPos(scaleY.min, "1") - NULL_MARKER_HALF_CSS;
+  if (Math.abs(cursorTop - yPos) > NULL_HOVER_PROX) return null;
+
+  let best: { seriesIdx: number; timestamp: number; dist: number } | null = null;
+  for (let s = 1; s < u.series.length; s++) {
+    const seriesItem = u.series[s] as SeriesItem;
+    if (!seriesItem.show) continue;
+    const nullTs = seriesItem.nullTimestamps;
+    if (!nullTs || !nullTs.length) continue;
+
+    for (let i = 0; i < nullTs.length; i++) {
+      const t = nullTs[i];
+      const xPos = u.valToPos(t, "x");
+      const dist = Math.abs(cursorLeft - xPos);
+      if (dist < NULL_HOVER_PROX && (best === null || dist < best.dist)) {
+        best = { seriesIdx: s, timestamp: t, dist };
+      }
+    }
+  }
+  return best ? { seriesIdx: best.seriesIdx, timestamp: best.timestamp } : null;
+};
+
+const NULL_DESCRIPTION = "\"null\" can be a staleness marker or an actual NaN/null value produced by exporter.";
+
 const useLineTooltip = ({ u, metrics, series, unit }: LineTooltipHook) => {
   const [showTooltip, setShowTooltip] = useState(false);
   const [tooltipIdx, setTooltipIdx] = useState({ seriesIdx: -1, dataIdx: -1 });
+  const [nullTooltip, setNullTooltip] = useState<NullHover | null>(null);
   const [stickyTooltips, setStickyToolTips] = useState<ChartTooltipProps[]>([]);
 
   const resetTooltips = () => {
     setStickyToolTips([]);
     setTooltipIdx({ seriesIdx: -1, dataIdx: -1 });
+    setNullTooltip(null);
   };
 
   const setCursor = (u: uPlot) => {
     const dataIdx = u.cursor.idx ?? -1;
     setTooltipIdx(prev => ({ ...prev, dataIdx }));
+    setNullTooltip(findNullHover(u));
   };
 
   const seriesFocus = (u: uPlot, sidx: (number | null)) => {
@@ -35,7 +81,36 @@ const useLineTooltip = ({ u, metrics, series, unit }: LineTooltipHook) => {
     setTooltipIdx(prev => ({ ...prev, seriesIdx }));
   };
 
+  const getNullTooltipProps = (hit: NullHover): ChartTooltipProps => {
+    const { seriesIdx, timestamp } = hit;
+    const metricItem = metrics[seriesIdx - 1];
+    const seriesItem = series[seriesIdx] as SeriesItem;
+
+    const groups = new Set(metrics.map(m => m.group));
+    const group = metricItem?.group || 0;
+
+    const yMin = u?.scales?.[1]?.min ?? 0;
+    const point = {
+      top: u ? u.valToPos(yMin, seriesItem?.scale || "1") - NULL_MARKER_HALF_CSS : 0,
+      left: u ? u.valToPos(timestamp, "x") : 0,
+    };
+
+    return {
+      u,
+      id: `null_${seriesIdx}_${timestamp}`,
+      title: groups.size > 1 ? `Query ${group}` : "",
+      dates: [dayjs(timestamp * 1000).tz().format(DATE_FULL_TIMEZONE_FORMAT)],
+      value: "null",
+      info: getMetricName(metricItem, seriesItem),
+      description: NULL_DESCRIPTION,
+      marker: `${seriesItem?.stroke}`,
+      point,
+    };
+  };
+
   const getTooltipProps = useCallback((): ChartTooltipProps => {
+    if (nullTooltip) return getNullTooltipProps(nullTooltip);
+
     const { seriesIdx, dataIdx } = tooltipIdx;
     const metricItem = metrics[seriesIdx - 1];
     const seriesItem = series[seriesIdx] as SeriesItem;
@@ -86,7 +161,7 @@ const useLineTooltip = ({ u, metrics, series, unit }: LineTooltipHook) => {
       marker: `${seriesItem?.stroke}`,
       duplicateCount,
     };
-  }, [u, tooltipIdx, metrics, series, unit]);
+  }, [u, tooltipIdx, metrics, series, unit, nullTooltip]);
 
   const handleClick = useCallback(() => {
     if (!showTooltip) return;
@@ -101,8 +176,9 @@ const useLineTooltip = ({ u, metrics, series, unit }: LineTooltipHook) => {
   };
 
   useEffect(() => {
-    setShowTooltip(tooltipIdx.dataIdx !== -1 && tooltipIdx.seriesIdx !== -1);
-  }, [tooltipIdx]);
+    const normalHit = tooltipIdx.dataIdx !== -1 && tooltipIdx.seriesIdx !== -1;
+    setShowTooltip(normalHit || nullTooltip !== null);
+  }, [tooltipIdx, nullTooltip]);
 
   useEventListener("click", handleClick);
 

app/vmui/packages/vmui/src/pages/RawQueryPage/hooks/useFetchExport.ts

@@ -149,15 +149,21 @@ export const useFetchExport = ({ hideQuery, showAllSeries }: FetchQueryParams):
             const pointsToTake = shouldDownsample ? maxPointsPerSeries : totalPoints;
             const step = shouldDownsample ? totalPoints / maxPointsPerSeries : 1;
 
-            const values: [number, number][] = Array.from({ length: pointsToTake }, (_, i) => {
+            const values: [number, number][] = new Array(pointsToTake);
+            const nullTimestamps: number[] = [];
+            for (let i = 0; i < pointsToTake; i++) {
               const idx = shouldDownsample ? Math.floor(i * step) : i;
-              return [rawTimestamps[idx] / 1000, rawValues[idx]];
-            });
+              const ts = rawTimestamps[idx] / 1000;
+              const raw = rawValues[idx];
+              if (raw === null) nullTimestamps.push(ts);
+              values[i] = [ts, raw as number];
+            }
 
             tempData.push({
               group: counter,
               metric: jsonLine.metric,
               values,
+              nullTimestamps,
             } as MetricBase);
           }
 

app/vmui/packages/vmui/src/types/uplot.ts

@@ -11,6 +11,7 @@ export interface SeriesItem extends Series {
     statsFormatted: SeriesItemStatsFormatted;
     median: number;
     hasAlias?: boolean;
+    nullTimestamps?: number[];
 }
 
 export interface HideSeriesArgs {

app/vmui/packages/vmui/src/utils/uplot/scatter.ts

@@ -103,6 +103,28 @@ export const drawPoints = (u: uPlot, seriesIdx: number) => {
     u.ctx.lineWidth = 1.4 * uPlot.pxRatio;
     u.ctx.strokeStyle = u.ctx.fillStyle;
     u.ctx.stroke(squaresPath);
+
+    const nullTs = (series as unknown as { nullTimestamps?: number[] }).nullTimestamps;
+    if (nullTs && nullTs.length) {
+      const xSize = BASE_POINT_SIZE * 1.4 * uPlot.pxRatio;
+      const xHalf = xSize / 2;
+      // Lift the marker by half its size so the entire icon sits inside the plot area
+      // (yMin maps to the plot's bottom edge, so centering on it would clip the lower half).
+      const cy = valToPosY(yMin, scaleY, yDim, yOff) - xHalf;
+      const xPath = new Path2D();
+      for (let i = 0; i < nullTs.length; i++) {
+        const t = nullTs[i];
+        if (t < xMin || t > xMax) continue;
+        const cx = valToPosX(t, scaleX, xDim, xOff);
+        xPath.moveTo(cx - xHalf, cy - xHalf);
+        xPath.lineTo(cx + xHalf, cy + xHalf);
+        xPath.moveTo(cx + xHalf, cy - xHalf);
+        xPath.lineTo(cx - xHalf, cy + xHalf);
+      }
+      u.ctx.lineWidth = 1.6 * uPlot.pxRatio;
+      u.ctx.strokeStyle = u.ctx.fillStyle;
+      u.ctx.stroke(xPath);
+    }
   };
 
   uPlot.orient(u, seriesIdx, orientCallback);

app/vmui/packages/vmui/src/utils/uplot/series.ts

@@ -38,6 +38,7 @@ export const getSeriesItemContext = (data: MetricResult[], hideSeries: string[],
       show: !includesHideSeries(label, hideSeries),
       scale: "1",
       paths: isRawQuery ? drawPoints : undefined,
+      nullTimestamps: d.nullTimestamps,
       ...getSeriesStatistics(d),
     };
   };

docs/victoriametrics/changelog/CHANGELOG.md

@@ -31,6 +31,7 @@ See also [LTS releases](https://docs.victoriametrics.com/victoriametrics/lts-rel
 * FEATURE: [vmsingle](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/), `vminsert` in [VictoriaMetrics cluster](https://docs.victoriametrics.com/victoriametrics/cluster-victoriametrics/) and [vmagent](https://docs.victoriametrics.com/victoriametrics/vmagent/): add `-opentelemetry.labelNameUnderscoreSanitization` command-line flag to control whether to enable prepending of `key` to labels starting with `_` when `-opentelemetry.usePrometheusNaming` is enabled. See [OpenTelemetry](https://docs.victoriametrics.com/victoriametrics/integrations/opentelemetry/) docs and [#9663](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/9663). Thanks to @andriibeee for the contribution.
 * FEATURE: [vmui](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#vmui): improve the [Top Queries](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#top-queries) table UI. Duration columns now display human-readable values (e.g. `1.23s`) instead of raw seconds, memory column shows human-readable sizes (e.g. `1.23 MB`), instant queries are labeled as `instant` instead of empty string, and column headers now show tooltips with descriptions. See [#10790](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/10790).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/victoriametrics/vmagent/): drain in-memory remote write queue on shutdown within the 5-second grace period before falling back to persisting blocks to disk. See [#9996](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/9996)
+* FEATURE: [vmui](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#vmui): display `null` values on `Raw Query` chart. `null` values can be actual `NaN` or `null` values exposed by the exporter, or [stale markers](https://docs.victoriametrics.com/victoriametrics/vmagent/#prometheus-staleness-markers). Before, vmui Raw Query was silently dropping non-numeric values. Displaying such values on the chart could improve the debugging experience. 
 
 * BUGFIX: [stream aggregation](https://docs.victoriametrics.com/victoriametrics/stream-aggregation/): stop emitting stale values for `quantiles(...)` outputs when a time series has no samples during the current aggregation interval. See [#10918](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/10918). Thanks to @alexei38 for the contribution.
 * BUGFIX: [stream aggregation](https://docs.victoriametrics.com/victoriametrics/stream-aggregation/): extend delay on aggregation windows flush by the biggest lag among pushed samples. Before, the delay was calculated as 95th percentile across samples, which could underrepresent outliers and reject them from aggregation as "too old". See [#10402](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/10402).