🪢 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 { describe, expect, it } from "vitest";
import { resolveDensity } from "./density";
import {
formatDurationMs,
layout,
prepareTimeline,
type LayoutNode,
type PositionedNode,
type TimelineLayout,
} from "./layout";
import { PX_PER_LETTER, createTextMeasurerFrom } from "./textMeasurer";
import { tooltipPlacement } from "./tooltipPlacement";
import {
MAX_ZOOM_PRECISION_MS,
clampView,
traceSpaceOf,
zoomToSpan,
zoomView,
} from "./viewTransform";
import {
TIMELINE_SHAPES,
longTailTrace,
reporterTrace,
singleSpan,
} from "./__tests__/timelineV2.fixtures";
// Explicit null context: the PX_PER_LETTER fallback, so widths are
// deterministic and jsdom is never asked for a canvas.
const measurer = createTextMeasurerFrom(null);
const BOXES = [
{ width: 320, height: 240 },
{ width: 480, height: 240 },
{ width: 768, height: 640 },
{ width: 1280, height: 640 },
{ width: 1920, height: 900 },
];
function run(
roots: readonly LayoutNode[],
box: { width: number; height: number },
options: Partial<Parameters<typeof layout>[0]> = {},
): TimelineLayout {
const prepared = prepareTimeline(roots, options.collapsed);
return layout({
roots,
box,
density: options.density ?? resolveDensity({ pointer: "fine" }),
measurer,
view: options.view ?? null,
compress: options.compress ?? false,
prepared,
...options,
});
}
const numbersOf = (node: PositionedNode) => [
node.x,
node.width,
node.y,
node.height,
node.labelX,
node.labelWidth,
node.startMs,
node.endMs,
node.firstTokenX ?? 0,
node.durationMs ?? 0,
];
describe("layout", () => {
it("scales to the measured box instead of a fixed canvas", () => {
const roots = singleSpan();
const narrow = run(roots, { width: 320, height: 240 });
const wide = run(roots, { width: 1280, height: 240 });
// Same trace, same fitted view; only the box differs.
expect(narrow.nodes[0]!.width).toBeCloseTo(320, 0);
expect(wide.nodes[0]!.width).toBeCloseTo(1280, 0);
expect(narrow.view).toEqual(narrow.traceSpace);
});
it("keeps every bar and label inside the box for every shape and width", () => {
for (const [shape, makeRoots] of Object.entries(TIMELINE_SHAPES)) {
const roots = makeRoots();
for (const box of BOXES) {
const result = run(roots, box, { compress: true });
for (const node of result.nodes) {
const context = `${shape} @ ${box.width}px, node ${node.id}`;
expect(node.x, context).toBeGreaterThanOrEqual(0);
expect(node.x + node.width, context).toBeLessThanOrEqual(
box.width + 0.001,
);
if (node.labelPlacement !== "hidden") {
expect(node.labelX, context).toBeGreaterThanOrEqual(0);
expect(node.labelX + node.labelWidth, context).toBeLessThanOrEqual(
box.width + 0.001,
);
}
}
for (const tick of result.ticks) {
expect(tick.x, `${shape} @ ${box.width}px tick`).toBeLessThanOrEqual(
box.width + 0.001,
);
}
}
}
});
it("stays finite on degenerate shapes, degenerate boxes and compression", () => {
const boxes = [
...BOXES,
{ width: 0, height: 0 },
{ width: 320, height: 0 },
];
for (const [shape, makeRoots] of Object.entries(TIMELINE_SHAPES)) {
const roots = makeRoots();
for (const box of boxes) {
for (const compress of [false, true]) {
const result = run(roots, box, { compress });
const context = `${shape} @ ${box.width}x${box.height} compress=${compress}`;
expect(Number.isFinite(result.pxPerMs), context).toBe(true);
expect(Number.isFinite(result.contentHeight), context).toBe(true);
expect(Number.isFinite(result.traceSpace.duration), context).toBe(
true,
);
expect(Number.isFinite(result.view.duration), context).toBe(true);
for (const node of result.nodes) {
for (const value of numbersOf(node)) {
expect(Number.isFinite(value), `${context} ${node.id}`).toBe(
true,
);
}
}
for (const tick of result.ticks) {
expect(Number.isFinite(tick.x), context).toBe(true);
}
for (const gap of result.gaps) {
expect(
Number.isFinite(gap.x) && Number.isFinite(gap.width),
context,
).toBe(true);
}
}
}
}
// No roots at all is a shape too.
const empty = run([], { width: 320, height: 240 });
expect(empty.nodes).toEqual([]);
expect(empty.contentHeight).toBe(0);
});
it("places the duration label inside a wide bar and outside a narrow one", () => {
const wide = run(singleSpan(), { width: 1280, height: 240 }).nodes[0]!;
expect(wide.labelPlacement).toBe("inside");
expect(wide.labelX).toBeGreaterThan(wide.x);
// The last span of the reporter trace is 1ms at the right edge: there is no
// room inside the bar, and none after it either.
const narrow = run(reporterTrace(), { width: 320, height: 240 });
const lastSpan = narrow.nodes[narrow.nodes.length - 1]!;
expect(lastSpan.width).toBeLessThan(8);
expect(lastSpan.labelPlacement).toBe("before");
});
it("compression makes a long-tail trace legible and stays reversible", () => {
const roots = longTailTrace();
const box = { width: 320, height: 240 };
const honest = run(roots, box, { compress: false });
const compressed = run(roots, box, { compress: true });
const leafWidth = (result: TimelineLayout) =>
Math.max(...result.nodes.filter((n) => n.depth > 0).map((n) => n.width));
// Fitted honestly, 40ms of work in a 36s trace is a sub-pixel sliver
// pinned to the minimum bar width; compressed, it is a real bar.
expect(leafWidth(honest)).toBe(4);
expect(leafWidth(compressed)).toBeGreaterThan(20);
expect(compressed.gaps.length).toBeGreaterThan(0);
expect(compressed.compression.compressedDurationMs).toBeLessThan(
compressed.realDurationMs,
);
// Round-trip: the axis labels read real time back out of compressed space.
for (const realMs of [0, 40, 18_000, 36_020]) {
expect(
compressed.compression.toRealMs(
compressed.compression.toCompressedMs(realMs),
),
).toBeCloseTo(realMs, 3);
}
});
it("positions only the mounted row window", () => {
const roots = TIMELINE_SHAPES.huge();
const box = { width: 768, height: 640 };
const windowed = run(roots, box, {
rowRange: { startIndex: 100, endIndex: 139 },
});
expect(windowed.nodes).toHaveLength(40);
expect(windowed.rowCount).toBe(10_000);
expect(windowed.nodes[0]!.index).toBe(100);
expect(windowed.nodes[0]!.y).toBe(100 * windowed.rowHeight);
});
});
describe("view transform", () => {
it("clamps the window inside trace space and floors the zoom", () => {
const space = traceSpaceOf(1_000);
expect(clampView({ start: -500, duration: 5_000 }, space)).toEqual({
start: 0,
duration: 1_000,
});
// Panning past the end holds the zoom level and pulls the start back.
expect(clampView({ start: 900, duration: 400 }, space)).toEqual({
start: 600,
duration: 400,
});
expect(
clampView({ start: 0, duration: 0.001 }, space).duration,
).toBeCloseTo(MAX_ZOOM_PRECISION_MS, 6);
expect(clampView({ start: NaN, duration: NaN }, space)).toEqual({
start: 0,
duration: 1_000,
});
// A collapsed trace has nowhere to zoom to.
expect(clampView({ start: 0, duration: 10 }, traceSpaceOf(0))).toEqual({
start: 0,
duration: 0,
});
});
it("zooms about the anchor and zoom-to-span pads both sides", () => {
const space = traceSpaceOf(1_000);
const zoomed = zoomView({ start: 0, duration: 1_000 }, space, {
factor: 2,
anchorRatio: 0.5,
});
expect(zoomed).toEqual({ start: 250, duration: 500 });
const fitted = zoomToSpan({ start: 400, duration: 100 }, space, 0.1);
expect(fitted.start).toBeCloseTo(390, 6);
expect(fitted.duration).toBeCloseTo(120, 6);
});
});
describe("density", () => {
it("resolves from the pointer modality and lines per row", () => {
// Never a function of box height: a short trace in a tall box keeps
// Finder-row density rather than growing into the slack.
expect(resolveDensity({ pointer: "fine" }).rowHeight).toBe(26);
expect(resolveDensity({ pointer: "coarse" }).rowHeight).toBe(44);
// A stacked row (name above bar) needs two text lines' worth.
expect(resolveDensity({ pointer: "fine", lines: 2 }).rowHeight).toBe(38);
expect(resolveDensity({ pointer: "coarse", lines: 2 }).rowHeight).toBe(44);
});
});
describe("textMeasurer", () => {
// Every glyph 10px wide, so a measured width is countable by hand and the
// per-letter fallback (6.5) is visible whenever one is used by mistake.
const tenPerGlyph = {
font: "",
measureText: (text: string) => ({ width: text.length * 10 }),
} as unknown as CanvasRenderingContext2D;
it("measures every unit in a compound label, not just the last", () => {
const measure = createTextMeasurerFrom(tenPerGlyph).measure;
// `1m 35s` is six glyphs, so 60 — and it is only 60 if the leading `m` was
// measured too. Matching a unit only as the whole remainder of the string
// left it on the flat estimate, which is what every label above a minute is.
expect(measure("1m 35s")).toBeCloseTo(60, 6);
expect(measure("1h 30m")).toBeCloseTo(60, 6);
expect(measure("486ms")).toBeCloseTo(50, 6);
expect(measure("1.24s")).toBeCloseTo(50, 6);
// Longest-first matching, so `min` is one unit rather than `m` plus letters.
expect(measure("5min")).toBeCloseTo(40, 6);
expect(measure("∑ 1.24s")).toBeCloseTo(70, 6);
});
it("corrects for a canvas that refused the font it was given", () => {
// A real canvas keeps `10px sans-serif` when it rejects a font string, and
// then measures 10px glyphs for a 12px label — 20% short, silently.
const stubborn: { font: string; measureText: (t: string) => TextMetrics } =
{
font: "10px sans-serif",
measureText: (text: string) =>
({ width: text.length * 10 }) as TextMetrics,
};
Object.defineProperty(stubborn, "font", {
get: () => "10px sans-serif",
set: () => undefined,
});
const measure = createTextMeasurerFrom(
stubborn as unknown as CanvasRenderingContext2D,
"20px test",
).measure;
// Asked for 20px, measured at 10px: every width doubles back to the truth.
expect(measure("abc")).toBeCloseTo(60, 6);
});
it("falls back to a flat per-letter width with no canvas", () => {
expect(createTextMeasurerFrom(null).measure("1m 35s")).toBeCloseTo(
6 * PX_PER_LETTER,
6,
);
});
});
describe("tooltipPlacement", () => {
/** The box the placement implies, given a content size it never asks about. */
const boxOf = (
placement: ReturnType<typeof tooltipPlacement>,
height: number,
) => {
const width = placement.maxWidth;
const flipX = placement.transform.includes("-100%,");
const flipY = placement.transform.endsWith("-100%)");
return {
left: flipX ? placement.left - width : placement.left,
right: flipX ? placement.left : placement.left + width,
top: flipY ? placement.top - height : placement.top,
bottom: flipY ? placement.top : placement.top + height,
};
};
it("never leaves the viewport, at any window size or pointer position", () => {
// Phone through desktop, including the widths where a fixed 320px cap and a
// fixed flip threshold disagree — that combination ran the box off the right
// edge for any pointer just short of the threshold.
for (const viewportWidth of [320, 480, 700, 800, 830, 1024, 1280, 1920]) {
for (const viewportHeight of [300, 568, 658, 900]) {
for (const fraction of [0, 0.1, 0.49, 0.5, 0.51, 0.59, 0.6, 0.61, 1]) {
const clientX = Math.round(viewportWidth * fraction);
const clientY = Math.round(viewportHeight * fraction);
const placement = tooltipPlacement({
clientX,
clientY,
viewportWidth,
viewportHeight,
});
// Two text lines, and then some, since the metrics line can wrap.
const box = boxOf(placement, 80);
const at = `${viewportWidth}x${viewportHeight} @${fraction}`;
expect(box.left, `left ${at}`).toBeGreaterThanOrEqual(0);
expect(box.right, `right ${at}`).toBeLessThanOrEqual(viewportWidth);
expect(box.top, `top ${at}`).toBeGreaterThanOrEqual(0);
expect(box.bottom, `bottom ${at}`).toBeLessThanOrEqual(
viewportHeight,
);
}
}
}
});
it("takes the roomier side of the pointer", () => {
const viewport = { viewportWidth: 1000, viewportHeight: 800 };
// Left of centre: grow right and down, anchored at the pointer.
expect(
tooltipPlacement({ clientX: 100, clientY: 100, ...viewport }).transform,
).toBe("translate(0, 0)");
// Right of centre: grow left and up, anchored by its own far edge.
expect(
tooltipPlacement({ clientX: 900, clientY: 700, ...viewport }).transform,
).toBe("translate(-100%, -100%)");
});
it("spends the room it has, and never more", () => {
const viewport = { viewportWidth: 1000, viewportHeight: 800 };
// Middle of a wide window: the full width is affordable.
expect(
tooltipPlacement({ clientX: 300, clientY: 400, ...viewport }).maxWidth,
).toBe(320);
// 200px from the left edge leaves 200 minus the offset and the margin.
expect(
tooltipPlacement({ clientX: 200, clientY: 400, ...viewport }).maxWidth,
).toBe(320);
expect(
tooltipPlacement({
clientX: 120,
clientY: 400,
viewportWidth: 260,
viewportHeight: 800,
}).maxWidth,
).toBe(260 - 120 - 16);
});
});
describe("formatDurationMs", () => {
it("keeps labels short at every magnitude", () => {
expect(formatDurationMs(0)).toBe("0ms");
expect(formatDurationMs(486)).toBe("486ms");
expect(formatDurationMs(1_240)).toBe("1.24s");
expect(formatDurationMs(36_020)).toBe("36.02s");
expect(formatDurationMs(95_000)).toBe("1m 35s");
expect(formatDurationMs(5_400_000)).toBe("1h 30m");
expect(formatDurationMs(NaN)).toBe("0ms");
});
});