🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
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) });
}