Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

13.1 KB
Raw Blame
import type { AggregatedMetricPoint, HistoryTimeRange, ResourceType } from '@/api/charts';
import { formatBytes } from '@/utils/format';

export interface HistoryChartProps {
  resourceType: ResourceType;
  resourceId: string;
  metric: string;
  height?: number;
  color?: string;
  label?: string;
  unit?: string;
  range?: HistoryTimeRange;
  onRangeChange?: (range: HistoryTimeRange) => void;
  hideSelector?: boolean;
  compact?: boolean;
  hideLock?: boolean;
  data?: AggregatedMetricPoint[];
  /**
   * False pauses stored reads and polling while keeping the readings already
   * shown, e.g. for a chart inside a drawer tab that is mounted but hidden.
   */
  enabled?: boolean;
}

export interface HistoryChartHoverPoint {
  value: number;
  timestamp: number;
  x: number;
  y: number;
}

export interface HistoryChartTooltipLayout {
  x: number;
  y: number;
  width: number;
  height: number;
}

export const HISTORY_CHART_RANGES: HistoryTimeRange[] = [
  '1h',
  '6h',
  '12h',
  '24h',
  '7d',
  '14d',
  '30d',
  '90d',
];

export const HISTORY_CHART_MIN_LEFT_INSET = 40;

// The one label every history range picker shows for an option, so a drawer,
// a disk and a pool never name the same range three ways.
const HISTORY_RANGE_OPTION_LABELS: Record<HistoryTimeRange, string> = {
  '30m': '30 minutes',
  '1h': '1 hour',
  '6h': '6 hours',
  '12h': '12 hours',
  '24h': '24 hours',
  '7d': '7 days',
  '14d': '14 days',
  '30d': '30 days',
  '90d': '90 days',
};

export const formatHistoryRangeOptionLabel = (range: HistoryTimeRange): string =>
  HISTORY_RANGE_OPTION_LABELS[range] ?? range;

const HISTORY_CHART_RANGE_LABELS: Record<HistoryTimeRange, string> = {
  '30m': '30-minute',
  '1h': '1-hour',
  '6h': '6-hour',
  '12h': '12-hour',
  '24h': '24-hour',
  '7d': '7-day',
  '14d': '14-day',
  '30d': '30-day',
  '90d': '90-day',
};

export interface HistoryChartAccessibleDescriptionInput {
  data: AggregatedMetricPoint[];
  error: string | null;
  isLocked: boolean;
  loading: boolean;
  range: HistoryTimeRange;
  unit?: string;
}

export function formatHistoryChartTooltipValue(value: number, unit?: string): string {
  if (unit === '%' && value > 0 && value < 0.1) return '<0.1%';
  if (unit === '%') return `${value.toFixed(1)}%`;
  if (unit === 'B/s') return `${formatBytes(value)}/s`;
  if (unit === 'C') return `${Math.round(value)}°C`;
  if (!unit) return formatBytes(value);
  return `${Number.isInteger(value) ? value : value.toFixed(1)} ${unit}`;
}

export function getHistoryChartAccessibleLabel(label?: string): string {
  return `${label?.trim() || 'History'} chart`;
}

export function getHistoryChartAccessibleDescription({
  data,
  error,
  isLocked,
  loading,
  range,
  unit,
}: HistoryChartAccessibleDescriptionInput): string {
  const rangeLabel = HISTORY_CHART_RANGE_LABELS[range] ?? `${range} history`;
  if (loading) return `Loading ${rangeLabel} history data.`;
  if (error) return `${rangeLabel} history data could not be loaded.`;
  if (isLocked) return `${rangeLabel} history data is unavailable on the current plan.`;
  if (data.length === 0) return `No ${rangeLabel} history data is available.`;

  const first = data[0];
  const latest = data[data.length - 1];
  const minimum = getHistoryChartDataMin(data)!;
  const maximum = getHistoryChartDataMax(data)!;
  const formatTimestamp = (timestamp: number) => new Date(timestamp).toLocaleString();
  const formatValue = (value: number) => formatHistoryChartTooltipValue(value, unit);

  if (data.length === 1) {
    return `${rangeLabel} history contains 1 data point at ${formatTimestamp(latest.timestamp)}: ${formatValue(latest.value)}.`;
  }

  const direction =
    latest.value > first.value
      ? 'increased'
      : latest.value < first.value
        ? 'decreased'
        : 'remained unchanged';
  const changeSummary =
    direction === 'remained unchanged'
      ? `Values remained unchanged at ${formatValue(latest.value)}.`
      : `Values ${direction} from ${formatValue(first.value)} to ${formatValue(latest.value)}.`;

  return `${rangeLabel} history contains ${data.length} data points from ${formatTimestamp(first.timestamp)} to ${formatTimestamp(latest.timestamp)}. ${changeSummary} Minimum ${formatValue(minimum)}. Maximum ${formatValue(maximum)}.`;
}

export function getHistoryChartRefreshIntervalMs(range: HistoryTimeRange) {
  switch (range) {
    case '7d':
    case '14d':
      return 30000;
    case '30d':
      return 60000;
    case '90d':
      return 120000;
    default:
      return 10000;
  }
}

export function getHistoryChartDefaultColor(metric: string, color?: string) {
  if (color) return color;
  if (metric === 'cpu') return '#8b5cf6';
  if (metric === 'memory') return '#f59e0b';
  if (metric === 'disk') return '#10b981';
  return '#3b82f6';
}

export function getHistoryChartDataMin(points: AggregatedMetricPoint[]) {
  if (points.length === 0) return null;
  let min = Infinity;
  for (const point of points) {
    const value = point.min != null ? point.min : point.value;
    if (value < min) min = value;
  }
  return min;
}

export function getHistoryChartDataMax(points: AggregatedMetricPoint[]) {
  if (points.length === 0) return null;
  let max = -Infinity;
  for (const point of points) {
    const value = point.max != null ? point.max : point.value;
    if (value > max) max = value;
  }
  return max;
}

export type HistorySource = 'store' | 'memory' | 'live' | 'mock_synthetic';

/**
 * Names where a History reply's readings came from. `store` is the history
 * store; `memory` means the store had nothing for the range, so the readings
 * are the recent ones Pulse holds in memory; `live` is one current reading
 * because no history exists yet. Demo data reads like stored history.
 */
export function getHistoryReadoutLabel(
  source: HistorySource | null | undefined,
  inspected: boolean,
): string {
  if (source === 'live') return 'Current';
  if (source === 'memory') return inspected ? 'Recorded' : 'Latest recorded';
  return inspected ? 'Stored' : 'Latest stored';
}

/** A short badge and its explanation for a reply that is not stored history. */
export function getHistorySourceNotice(
  source: HistorySource | null | undefined,
): { badge: string; detail: string } | null {
  if (source === 'memory') {
    return {
      badge: 'Recent only',
      detail: 'Recent readings only. The history store has none for this range yet.',
    };
  }
  if (source === 'live') {
    return {
      badge: 'Current only',
      detail: 'No history for this range yet. Showing the current reading.',
    };
  }
  return null;
}

/** True when any stored bucket's lowest and highest readings differ. */
export function hasHistoryChartSpread(points: readonly AggregatedMetricPoint[]): boolean {
  return (
    points.length > 1 &&
    points.some((point) => (point.max ?? point.value) > (point.min ?? point.value))
  );
}

export function getHistoryChartScale(points: AggregatedMetricPoint[], unit?: string) {
  const minValue = 0;
  const isPercentLike = unit === '%';
  const isByteLike = !unit || unit === 'B/s';
  let maxValue = 100;
  if (points.length > 0) {
    const rawMax = Math.max(...points.map((point) => point.max || point.value));
    maxValue = isPercentLike ? Math.max(100, rawMax) : Math.max(1, rawMax * 1.15);
  }

  return {
    isPercentLike,
    isByteLike,
    minValue,
    maxValue,
  };
}

export function getHistoryChartYAxisLabels(
  {
    minValue,
    maxValue,
    isPercentLike,
    isByteLike,
  }: {
    minValue: number;
    maxValue: number;
    isPercentLike: boolean;
    isByteLike: boolean;
  },
  unit?: string,
) {
  const ticks = [0, 0.5, 1].map((pct) => {
    const scaleValue = minValue + pct * (maxValue - minValue);
    let label: string;
    if (isPercentLike) {
      label = `${Math.round(scaleValue)}%`;
    } else if (isByteLike) {
      label = formatHistoryChartTooltipValue(scaleValue, unit);
    } else {
      label = `${Math.round(scaleValue)}`;
    }
    return { pct, label };
  });
  const labels = withoutRepeatedHistoryAxisLabels(ticks.map((tick) => tick.label));
  return ticks.map((tick, index) => ({ ...tick, label: labels[index] }));
}

/**
 * Gridline labels in axis order. A middle label that reads the same as a
 * neighbour (a small range rounded, or "<1K/s" twice on a quiet link) says
 * nothing and crowds the axis, so it is left blank; the gridline stays. The
 * end labels always remain.
 */
export function withoutRepeatedHistoryAxisLabels(labels: string[]): string[] {
  return labels.map((label, index) =>
    index > 0 &&
    index < labels.length - 1 &&
    (label === labels[index - 1] || label === labels[index + 1])
      ? ''
      : label,
  );
}

/**
 * Time ticks left to right without one that reads the same as the tick
 * before it: a short window at a coarse label ("Oct 2" four times, or
 * "11:00 AM" twice) states its time once.
 */
export function withoutRepeatedHistoryTimeTicks<T extends { label: string }>(
  ticks: readonly T[],
): T[] {
  return ticks.filter((tick, index) => index === 0 || tick.label !== ticks[index - 1].label);
}

const HISTORY_CHART_TIME_LABEL_GAP = 12;

/**
 * How many evenly spaced time labels fit along a plot of `plotWidth` pixels
 * when the widest label is `labelWidth` pixels, from `maxCount` down to the
 * first and last time. Labels are centred on their times, so neighbours need
 * a label's width plus a gap between their centres.
 */
export function getHistoryChartTimeTickCount(
  plotWidth: number,
  labelWidth: number,
  maxCount = 4,
): number {
  if (!(plotWidth > 0) || !(labelWidth > 0)) return maxCount;
  for (let count = maxCount; count > 2; count--) {
    if (plotWidth / (count - 1) >= labelWidth + HISTORY_CHART_TIME_LABEL_GAP) return count;
  }
  return 2;
}

export function getHistoryChartLeftInset(labelWidths: number[]) {
  const widestLabel = Math.max(0, ...labelWidths);
  return Math.max(HISTORY_CHART_MIN_LEFT_INSET, Math.ceil(widestLabel) + 8);
}

export function getHistoryChartRightInset(lastTimeLabelWidth: number) {
  return Math.max(0, Math.ceil(lastTimeLabelWidth / 2) + 2);
}

export function formatHistoryChartTimeLabel(timestamp: number, range: HistoryTimeRange) {
  const date = new Date(timestamp);
  if (range === '30d' || range === '90d' || range === '14d' || range === '7d') {
    return date.toLocaleDateString([], { month: 'short', day: 'numeric' });
  }
  return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
}

export function createHistoryChartGeometry({
  width,
  height,
  startTime,
  endTime,
  minValue,
  maxValue,
  leftInset = HISTORY_CHART_MIN_LEFT_INSET,
  rightInset = 0,
}: {
  width: number;
  height: number;
  startTime: number;
  endTime: number;
  minValue: number;
  maxValue: number;
  leftInset?: number;
  rightInset?: number;
}) {
  const timeSpan = Math.max(1, endTime - startTime);
  const plotWidth = width - leftInset - rightInset;
  const singleTimestamp = startTime === endTime;
  const getX = (timestamp: number) =>
    singleTimestamp
      ? leftInset + plotWidth / 2
      : leftInset + ((timestamp - startTime) / timeSpan) * plotWidth;
  const getTimestamp = (x: number) =>
    singleTimestamp ? startTime : startTime + ((x - leftInset) / plotWidth) * timeSpan;
  const getY = (value: number) =>
    height - 20 - ((value - minValue) / (maxValue - minValue)) * (height - 40);

  return {
    timeSpan,
    getX,
    getTimestamp,
    getY,
  };
}

export function findHistoryChartClosestPoint(
  points: AggregatedMetricPoint[],
  hoverTimestamp: number,
) {
  let closest = points[0];
  let minDiff = Math.abs(points[0].timestamp - hoverTimestamp);
  for (const point of points) {
    const diff = Math.abs(point.timestamp - hoverTimestamp);
    if (diff < minDiff) {
      minDiff = diff;
      closest = point;
    }
  }
  return closest;
}

export function getHistoryChartTooltipLayout({
  hoveredPoint,
  chartWidth,
  chartHeight,
}: {
  hoveredPoint: HistoryChartHoverPoint;
  chartWidth: number;
  chartHeight: number;
}): HistoryChartTooltipLayout {
  const width = 156;
  // Allow a wrapped local timestamp plus the reading at normal text size.
  const height = 64;
  const margin = 8;
  const pointGap = 12;
  const minX = margin;
  const maxX = Math.max(minX, chartWidth - width - margin);
  const minY = margin;
  const maxY = Math.max(minY, chartHeight - height - margin);
  const clampX = (value: number) => Math.min(Math.max(value, minX), maxX);
  const clampY = (value: number) => Math.min(Math.max(value, minY), maxY);

  const rightX = hoveredPoint.x + pointGap;
  const leftX = hoveredPoint.x - width - pointGap;
  const canPlaceRight = rightX <= maxX;
  const canPlaceLeft = leftX >= minX;
  const rightRoom = chartWidth - margin - hoveredPoint.x;
  const leftRoom = hoveredPoint.x - margin;
  const x =
    canPlaceRight && (!canPlaceLeft || rightRoom >= leftRoom)
      ? rightX
      : canPlaceLeft
        ? leftX
        : clampX(hoveredPoint.x - width / 2);

  let y = clampY(hoveredPoint.y - height / 2);
  const overlapsHoveredPoint =
    hoveredPoint.x >= x &&
    hoveredPoint.x <= x + width &&
    hoveredPoint.y >= y &&
    hoveredPoint.y <= y + height;
  if (overlapsHoveredPoint) {
    const showBelow = hoveredPoint.y < height + margin;
    y = showBelow ? clampY(hoveredPoint.y + pointGap) : clampY(hoveredPoint.y - height - pointGap);
  }
  return { x, y, width, height };
}