Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

12.8 KB
Raw Blame
import {
  type DataPoint,
  type FormatMetricOptions,
  type FormattedMetric,
} from "./chart-props";
import { type DashboardWidgetChartType } from "@langfuse/shared/src/db";
import { compactNumberFormatter, numberFormatter } from "@/src/utils/numbers";

export const toFullMetricString = (metric: FormattedMetric): string =>
  `${metric.negative ? "-" : ""}${metric.prefix ?? ""}${metric.main}${metric.suffix ?? ""}`;

/** One recharts row: the time bucket plus a value per series present in it. */
export type TimeSeriesGroupedRow = {
  time_dimension: string;
} & {
  [dimension: string]: number | null | string;
};

/**
 * Groups data by dimension to prepare it for time series breakdowns
 * @param data
 */
export const groupDataByTimeDimension = (
  data: DataPoint[],
): TimeSeriesGroupedRow[] => {
  // First, group by time_dimension
  const timeGroups = data.reduce(
    (acc: Record<string, Record<string, number | null>>, item: DataPoint) => {
      const time = item.time_dimension || "Unknown";
      if (!acc[time]) {
        acc[time] = {};
      }

      // A dimension-less point is a bucket marker (e.g. a gap-filled empty
      // bucket): it keeps the bucket on the axis without adding a series.
      if (item.dimension) {
        acc[time][item.dimension] = item.metric as number | null;
      }

      return acc;
    },
    {},
  );

  // Convert to array format for Recharts
  return Object.entries(timeGroups).map(([time, dimensions]) => ({
    time_dimension: time,
    ...dimensions,
  }));
};

export const getUniqueDimensions = (data: DataPoint[]) => {
  const uniqueDimensions = new Set<string>();
  data.forEach((item: DataPoint) => {
    if (item.dimension) {
      uniqueDimensions.add(item.dimension);
    }
  });
  return Array.from(uniqueDimensions);
};

/**
 * Computes a per-dimension summary value (the sum of a series' numeric metric
 * values) for use in chart legends. Intended for additive metrics only (event
 * counts, token totals, cost); callers gate this behind `legendSummary="sum"`.
 *
 * The null/0 handling is deliberate and is the crux of LFE-10498: a `0` is a
 * REAL value, so a series whose data points sum to `0` keeps its `0` summary.
 * A series with no real data point (no finite numeric metric anywhere) is
 * reported as `null` so the legend can omit a misleading number rather than
 * inventing a `0`. Non-finite values (NaN/Infinity) and the histogram tuple
 * shape are ignored.
 *
 * @returns a Map keyed by dimension; value is the numeric summary or `null`
 *   when the series has no data.
 */
export const getDimensionSummaries = (
  data: DataPoint[],
): Map<string, number | null> => {
  const summaries = new Map<string, number | null>();

  for (const item of data) {
    if (!item.dimension) continue;

    const existing = summaries.has(item.dimension)
      ? summaries.get(item.dimension)!
      : null;

    const metric = item.metric;
    const hasValue = typeof metric === "number" && Number.isFinite(metric);

    if (hasValue) {
      summaries.set(item.dimension, (existing ?? 0) + metric);
    } else if (!summaries.has(item.dimension)) {
      // Track the dimension so it still appears, but without a value yet.
      summaries.set(item.dimension, null);
    }
  }

  return summaries;
};

export const isTimeSeriesChart = (
  chartType: DashboardWidgetChartType,
): boolean => {
  switch (chartType) {
    case "LINE_TIME_SERIES":
    case "AREA_TIME_SERIES":
    case "BAR_TIME_SERIES":
      return true;
    case "HORIZONTAL_BAR":
    case "VERTICAL_BAR":
    case "PIE":
    case "HISTOGRAM":
    case "NUMBER":
    case "PIVOT_TABLE":
      return false;
    default:
      return false;
  }
};

/**
 * Picks a recharts numeric x-axis `interval` (= ticks skipped between two shown
 * ticks) that yields UNIFORM gaps targeting ~`maxTicks` labels. We use this
 * instead of `interval="preserveStartEnd"` + `minTickGap`, whose width-dependent
 * collision dropping skips ticks unevenly (e.g. 6/9, 6/11, 6/13 vanish while
 * 6/1–6/8 stay), making tick density vary by chart width. (LFE-10549)
 */
export const getEvenTickInterval = (
  pointCount: number,
  maxTicks = 8,
): number =>
  pointCount <= maxTicks ? 0 : Math.ceil(pointCount / maxTicks) - 1;

/**
 * Maps chart types to their human-readable display names.
 */
export function getChartTypeDisplayName(
  chartType: DashboardWidgetChartType,
): string {
  switch (chartType) {
    case "LINE_TIME_SERIES":
      return "Line Chart (Time Series)";
    case "AREA_TIME_SERIES":
      return "Area Chart (Time Series)";
    case "BAR_TIME_SERIES":
      return "Bar Chart (Time Series)";
    case "HORIZONTAL_BAR":
      return "Horizontal Bar Chart (Total Value)";
    case "VERTICAL_BAR":
      return "Vertical Bar Chart (Total Value)";
    case "PIE":
      return "Pie Chart (Total Value)";
    case "NUMBER":
      return "Big Number (Total Value)";
    case "HISTOGRAM":
      return "Histogram (Total Value)";
    case "PIVOT_TABLE":
      return "Pivot Table (Total Value)";
    default:
      return "Unknown Chart Type";
  }
}

export function valueFormatter(
  value: number | string,
  unit?: string,
  compact?: boolean,
): string {
  if (typeof value === "string") {
    return value;
  }

  return toFullMetricString(
    formatMetric(value, {
      unit,
      style: compact ? "compact" : "full",
    }),
  );
}

const stripTrailingDecimalZeros = (numStr: string): string =>
  numStr.replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");

const formatFixedMetric = (
  value: number,
  maxFractionDigits: number,
  suffix = "",
  maxCharacters?: number,
): FormattedMetric => {
  for (
    let fractionDigits = maxFractionDigits;
    fractionDigits >= 0;
    fractionDigits--
  ) {
    const main = stripTrailingDecimalZeros(value.toFixed(fractionDigits));
    const formatted = suffix ? { main, suffix } : { main };

    if (
      !maxCharacters ||
      toFullMetricString(formatted).length <= maxCharacters
    ) {
      return formatted;
    }
  }

  const main = Math.round(value).toString();
  return suffix ? { main, suffix } : { main };
};

const formatExponentialMetric = (
  value: number,
  maxCharacters?: number,
): FormattedMetric => {
  const main = value.toExponential(2);
  const formatted = { main };

  if (!maxCharacters || toFullMetricString(formatted).length <= maxCharacters) {
    return formatted;
  }

  for (let significantDigits = 2; significantDigits >= 1; significantDigits--) {
    const shortened = value.toExponential(significantDigits - 1);
    const shortenedFormatted = { main: shortened };
    if (toFullMetricString(shortenedFormatted).length <= maxCharacters) {
      return shortenedFormatted;
    }
  }

  return formatted;
};

const compactUnits = [
  [1e12, "T"],
  [1e9, "B"],
  [1e6, "M"],
  [1e3, "K"],
] as const;

const formatCompactMetric = (
  value: number,
  maxCharacters?: number,
): FormattedMetric => {
  for (let i = 0; i < compactUnits.length; i++) {
    const [divisor, suffix] = compactUnits[i];
    if (value < divisor) {
      continue;
    }

    const formatted = formatFixedMetric(
      value / divisor,
      3,
      suffix,
      maxCharacters,
    );

    if (Number(formatted.main) >= 1000 && i > 0) {
      const [nextDivisor, nextSuffix] = compactUnits[i - 1];
      return formatFixedMetric(
        value / nextDivisor,
        3,
        nextSuffix,
        maxCharacters,
      );
    }

    return formatted;
  }

  if (value >= 1) {
    return formatFixedMetric(value, 3, "", maxCharacters);
  }

  if (value >= 1e-3) {
    return formatFixedMetric(value, 6, "", maxCharacters);
  }

  return formatExponentialMetric(value, maxCharacters);
};

const MIN_DISPLAYED_USD = 0.01;

const durationDivisors = [1, 1_000, 60_000, 3_600_000, 86_400_000] as const;
const durationUnits = [
  "millisecond",
  "second",
  "minute",
  "hour",
  "day",
] as const;

const formatWithConstrainedDecimals = ({
  value,
  maxCharacters,
  maxFractionDigits,
  createFormatter,
}: {
  value: number;
  maxCharacters?: number;
  maxFractionDigits: number;
  createFormatter: (fractionDigits: number) => Intl.NumberFormat;
}): FormattedMetric => {
  let fallback: FormattedMetric | undefined;

  for (
    let fractionDigits = maxFractionDigits;
    fractionDigits >= 0;
    fractionDigits--
  ) {
    let prefix = "";
    let main = "";
    let suffix = "";

    for (const part of createFormatter(fractionDigits).formatToParts(value)) {
      switch (part.type) {
        case "currency":
          prefix += part.value;
          break;
        case "unit":
          suffix += part.value;
          break;
        case "literal":
          break;
        default:
          main += part.value;
      }
    }

    const formatted: FormattedMetric = {
      ...(prefix ? { prefix } : {}),
      main: main || `${prefix}${suffix}`,
      ...(suffix ? { suffix } : {}),
    };

    fallback = formatted;

    if (
      !maxCharacters ||
      toFullMetricString(formatted).length <= maxCharacters
    ) {
      return formatted;
    }
  }

  return fallback ?? { main: value.toString() };
};

/**
 * Formats a metric into structured parts for chart labels, axes, and tooltips.
 *
 * - `unit === "millisecond"` auto-scales across ms/s/min/h/d and can reduce
 *   fractional precision to satisfy `maxCharacters`.
 * - `unit === "USD"` formats with a currency prefix and can reduce fractional
 *   precision to satisfy `maxCharacters`. With `usdPrecision: "cents"` it keeps
 *   at most two decimals and renders non-zero values below one cent as `<$0.01`.
 * - `style === "compact"` uses compact suffixes for large values (`K`, `M`,
 *   `B`, `T`), decimal formatting for `1e-3 <= |value| < 1`, and exponential
 *   notation below `1e-3`.
 * - `style === "full"` preserves more detail for non-zero sub-unit values by
 *   using compact decimal formatting for `1e-3 <= |value| < 1` and exponential
 *   notation below `1e-3`; otherwise it falls back to `numberFormatter`.
 *
 * `maxCharacters` is an optional space constraint that may reduce fractional
 * digits or exponential precision for either style.
 */
export function formatMetric(
  value: number,
  options: FormatMetricOptions,
): FormattedMetric {
  const { unit, style, maxCharacters, usdPrecision } = options;

  const negative = value < 0;
  const absValue = Math.abs(value);

  const magnitudeMaxCharacters =
    negative && maxCharacters ? maxCharacters - 1 : maxCharacters;

  const applyNegative = (formatted: FormattedMetric): FormattedMetric =>
    negative ? { negative: true, ...formatted } : formatted;

  if (unit === "millisecond") {
    const tier = durationDivisors.reduce(
      (acc, divisor, i) => (absValue >= divisor ? i : acc),
      0,
    );

    const normalizedValue = absValue / durationDivisors[tier];
    const maxFractionDigits =
      normalizedValue > 0 && normalizedValue < 1
        ? Math.min(20, 2 - Math.floor(Math.log10(normalizedValue)))
        : 2;

    return applyNegative(
      formatWithConstrainedDecimals({
        value: normalizedValue,
        maxCharacters: magnitudeMaxCharacters,
        maxFractionDigits,
        createFormatter: (fractionDigits) =>
          new Intl.NumberFormat("en-US", {
            style: "unit",
            unit: durationUnits[tier],
            unitDisplay: "narrow",
            notation: "compact",
            minimumFractionDigits: 0,
            maximumFractionDigits: fractionDigits,
          }),
      }),
    );
  }

  if (unit === "USD") {
    const roundsToCents = usdPrecision === "cents";
    if (roundsToCents && absValue > 0 && absValue < MIN_DISPLAYED_USD) {
      return applyNegative({ prefix: "<$", main: "0.01" });
    }
    const keepsSubCentDigits = !roundsToCents && absValue > 0 && absValue < 5;
    const maxFractionDigits = keepsSubCentDigits ? 6 : 2;

    return applyNegative(
      formatWithConstrainedDecimals({
        value: absValue,
        maxCharacters: magnitudeMaxCharacters,
        maxFractionDigits,
        createFormatter: (fractionDigits) =>
          new Intl.NumberFormat("en-US", {
            style: "currency",
            currency: "USD",
            minimumFractionDigits: Math.min(2, fractionDigits),
            maximumFractionDigits: Math.max(0, fractionDigits),
          }),
      }),
    );
  }

  if (style === "compact") {
    if (value === 0) {
      return { main: "0" };
    }

    return applyNegative(formatCompactMetric(absValue, magnitudeMaxCharacters));
  }

  if (value !== 0 && absValue < 1e-3) {
    return applyNegative(
      formatExponentialMetric(absValue, magnitudeMaxCharacters),
    );
  }

  if (value !== 0 && absValue < 1) {
    if (maxCharacters) {
      return applyNegative(
        formatFixedMetric(absValue, 6, "", magnitudeMaxCharacters),
      );
    }

    return applyNegative({ main: compactNumberFormatter(absValue, 3) });
  }

  if (maxCharacters) {
    return applyNegative(
      formatFixedMetric(absValue, 2, "", magnitudeMaxCharacters),
    );
  }

  return applyNegative({ main: numberFormatter(absValue, 0, 2) });
}