fix(traces): add precision to waterfall ticks to prevent duplicate labels (#2652)

 # Summary

On the trace minimap and waterfall viewer, short traces (or traces zoomed in far enough) produced duplicate tick values for values that rounded to the same ms value. Now, we ensure that adjacent tick labels differ by adding precision when adjacent values would round to the same number.

## What changed

- Trace viewer and trace minimap tick labels now show just enough precision to ensure that adjacent values are different
- The trace viewer cursor / tooltip displays precision matching the tick labels

### Before

https://github.com/user-attachments/assets/dd4cbcf2-495c-4b72-b4fc-b5476e78fae9

<img width="1079" height="439" alt="Screenshot 2026-07-16 at 8 45 27 AM" src="https://github.com/user-attachments/assets/8ba7bb1d-acd8-44f0-9a29-5b363ffe1dc8" />


### After

https://github.com/user-attachments/assets/a4a514eb-9593-46f7-99ab-69d37f682545

<img width="1057" height="360" alt="Screenshot 2026-07-16 at 8 45 19 AM" src="https://github.com/user-attachments/assets/4f9838b4-d2ab-434c-8d5e-b1a459681640" />

## How to test in Preview

Pick a relatively short trace and zoom way in. Observe the trace viewer ticks and cursor/tooltip.

## References

Closes HDX-4803
Closes #2650

Author: pulpdrew

.changeset/waterfall-tick-precision.md

@@ -0,0 +1,5 @@
+---
+"@hyperdx/app": patch
+---
+
+fix(traces): Prevent duplicate ticks in waterfall/minimap

packages/app/src/components/TimelineChart/TimelineMinimap.tsx

@@ -113,7 +113,7 @@ export const TimelineMinimap = memo(function ({
       const val = i * interval;
       const frac = val / maxVal;
       if (frac > 1) break;
-      result.push({ frac, label: renderMs(val) });
+      result.push({ frac, label: renderMs(val, interval) });
     }
     return result;
   }, [maxVal]);
@@ -277,7 +277,7 @@ export const TimelineMinimap = memo(function ({
     >
       {ticks.map(({ frac, label }) => (
         <div
-          key={label}
+          key={frac}
           className={styles.tick}
           style={{ left: `${frac * 100}%`, height: MINIMAP_HEIGHT }}
         >

packages/app/src/components/TimelineChart/TimelineMouseCursor.tsx

@@ -8,7 +8,7 @@ import {
 
 import { useStableCallback } from '@/hooks/useStableCallback';
 
-import { renderMs } from './utils';
+import { renderMs, tickIntervalForWidth } from './utils';
 
 import styles from './TimelineChart.module.scss';
 
@@ -107,7 +107,13 @@ export function TimelineMouseCursor({
     const cursorPx = x - labelW; // = xPerc * (clientWidth - labelW)
     cursor.style.transform = `translateX(${cursorPx.toFixed(2)}px)`;
     overlay.style.transform = `translateX(${xPerc < 0.5 ? 12 : -150}px)`;
-    label.textContent = renderMs(Math.max(time, 0));
+    // Format with the same tick interval the X-axis derives from this width, so
+    // the readout carries the same precision (and unit) as the tick labels.
+    const interval = tickIntervalForWidth(
+      maxValRef.current,
+      eventsContentWidth,
+    );
+    label.textContent = renderMs(Math.max(time, 0), interval);
     line.style.height = `${heightRef.current ?? 0}px`;
   });
 

packages/app/src/components/TimelineChart/TimelineXAxis.tsx

@@ -7,19 +7,14 @@ import {
   useRef,
 } from 'react';
 
-import { calculateInterval, renderMs } from './utils';
+import { renderMs, tickIntervalForWidth } from './utils';
 
 import styles from './TimelineChart.module.scss';
 
 export type TimelineXAxisHandle = {
   recompute: () => void;
 };
 
-// Minimum horizontal space reserved per tick label. The widest label we render
-// (e.g. "1.234s") is ~45px; the extra headroom keeps adjacent labels from
-// touching. Tune up for a sparser axis, down for a denser one.
-const MIN_TICK_PX = 56;
-
 export function TimelineXAxis({
   maxVal,
   labelWidth,
@@ -64,8 +59,7 @@ export function TimelineXAxis({
     // recompute after the layout/scale has changed. Both containers span the
     // same width, so measure one and drive both from the same spacing.
     const ticksWidthPx = gridContainer.getBoundingClientRect().width;
-    const maxTicks = Math.max(1, Math.floor(ticksWidthPx / MIN_TICK_PX));
-    const interval = calculateInterval(max, maxTicks);
+    const interval = tickIntervalForWidth(max, ticksWidthPx);
     const numTicks = Math.floor(max / interval);
     const percSpacing = (interval / max) * 100;
     const marginLeft = (i: number) =>
@@ -111,7 +105,7 @@ export function TimelineXAxis({
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       const label = tick.firstElementChild as HTMLDivElement;
       tick.style.marginLeft = marginLeft(i);
-      label.textContent = renderMs(i * interval);
+      label.textContent = renderMs(i * interval, interval);
     }
   }, [maxValRef, heightRef]);
 

packages/app/src/components/TimelineChart/__tests__/utils.test.ts

@@ -1,7 +1,9 @@
 import {
   calculateInterval,
   getMaxEventValue,
+  MIN_TICK_PX,
   renderMs,
+  tickIntervalForWidth,
 } from '@/components/TimelineChart/utils';
 
 describe('renderMs', () => {
@@ -45,6 +47,85 @@ describe('renderMs', () => {
     // 0.9995ms rounds to 1000µs, so it should render as 1ms instead
     expect(renderMs(0.9995)).toBe('1ms');
   });
+
+  describe('with a tick interval (step)', () => {
+    it('adds ms precision so adjacent ticks stay distinct', () => {
+      expect(renderMs(1, 0.5)).toBe('1.0ms');
+      expect(renderMs(1.5, 0.5)).toBe('1.5ms');
+      expect(renderMs(2, 0.5)).toBe('2.0ms');
+      expect(renderMs(2.5, 0.5)).toBe('2.5ms');
+    });
+
+    it('produces no duplicate labels across a 0.5ms-spaced axis', () => {
+      const interval = 0.5;
+      const labels = [];
+      for (let i = 0; i * interval <= 4; i++) {
+        labels.push(renderMs(i * interval, interval));
+      }
+      expect(new Set(labels).size).toBe(labels.length);
+    });
+
+    it('uses two decimals when the interval requires it', () => {
+      expect(renderMs(1, 0.05)).toBe('1.00ms');
+      expect(renderMs(1.05, 0.05)).toBe('1.05ms');
+      expect(renderMs(1.1, 0.05)).toBe('1.10ms');
+    });
+
+    it('keeps integer labels when the interval is a whole number', () => {
+      expect(renderMs(2, 2)).toBe('2ms');
+      expect(renderMs(50, 50)).toBe('50ms');
+    });
+
+    it('adds precision to sub-millisecond (µs) ticks', () => {
+      expect(renderMs(0.5, 0.5)).toBe('500µs');
+      expect(renderMs(0.0005, 0.0005)).toBe('0.5µs');
+      expect(renderMs(0.001, 0.0005)).toBe('1.0µs');
+      expect(renderMs(0.0015, 0.0005)).toBe('1.5µs');
+    });
+
+    it('falls through to ms (with ms precision) when the µs form rounds to 1000', () => {
+      expect(renderMs(0.99996, 0.0005)).toBe('1.0000ms');
+      expect(renderMs(0.9999, 0.05)).toBe('1.00ms');
+      expect(renderMs(0.9996, 0.5)).toBe('1.0ms');
+    });
+
+    it('adds precision to second-scale ticks', () => {
+      expect(renderMs(1000, 500)).toBe('1.0s');
+      expect(renderMs(1500, 500)).toBe('1.5s');
+      expect(renderMs(2000, 500)).toBe('2.0s');
+    });
+
+    describe('edge cases', () => {
+      it('treats a null step like an omitted step (no added precision)', () => {
+        // @ts-expect-error null is not assignable to step, but is guarded at runtime
+        expect(renderMs(1, null)).toBe('1ms');
+        // @ts-expect-error null is not assignable to step, but is guarded at runtime
+        expect(renderMs(0.5, null)).toBe('500µs');
+        // @ts-expect-error null is not assignable to step, but is guarded at runtime
+        expect(renderMs(1500, null)).toBe('1.500s');
+        // @ts-expect-error null is not assignable to step, but is guarded at runtime
+        expect(renderMs(2000, null)).toBe('2s');
+      });
+
+      it('adds no precision for a 0 step', () => {
+        expect(renderMs(1, 0)).toBe('1ms');
+        expect(renderMs(0.5, 0)).toBe('500µs');
+        expect(renderMs(1000, 0)).toBe('1s');
+        expect(renderMs(1500, 0)).toBe('2s');
+      });
+
+      it('adds no precision for a negative step', () => {
+        expect(renderMs(1, -0.5)).toBe('1ms');
+        expect(renderMs(0.5, -0.0005)).toBe('500µs');
+        expect(renderMs(1000, -500)).toBe('1s');
+      });
+
+      it('adds no precision for a non-finite step', () => {
+        expect(renderMs(1, Infinity)).toBe('1ms');
+        expect(renderMs(1, NaN)).toBe('1ms');
+      });
+    });
+  });
 });
 
 describe('calculateInterval', () => {
@@ -111,6 +192,39 @@ describe('calculateInterval', () => {
   });
 });
 
+describe('tickIntervalForWidth', () => {
+  it('budgets ticks by MIN_TICK_PX, matching calculateInterval', () => {
+    // 560px fits 10 ticks (560 / 56), so a 100ms range steps by 10ms.
+    expect(tickIntervalForWidth(100, 10 * MIN_TICK_PX)).toBe(
+      calculateInterval(100, 10),
+    );
+  });
+
+  it('yields finer intervals as the width grows', () => {
+    // A narrow axis packs fewer ticks (coarser interval); a wide one packs more
+    // (finer interval). This is what lets the cursor readout gain precision when
+    // the timeline is zoomed in.
+    const narrow = tickIntervalForWidth(100, 3 * MIN_TICK_PX);
+    const wide = tickIntervalForWidth(100, 20 * MIN_TICK_PX);
+    expect(wide).toBeLessThan(narrow);
+  });
+
+  it('formats a cursor time with the same precision as the tick labels', () => {
+    // A zoomed-in 5ms range across a wide axis steps by a sub-ms interval, so
+    // the readout keeps a decimal instead of rounding to a whole millisecond.
+    const interval = tickIntervalForWidth(5, 20 * MIN_TICK_PX);
+    expect(renderMs(2.3, interval)).toBe('2.3ms');
+    expect(renderMs(2.3)).toBe('2ms');
+  });
+
+  it('reserves at least one tick for tiny widths', () => {
+    expect(tickIntervalForWidth(100, 0)).toBe(calculateInterval(100, 1));
+    expect(tickIntervalForWidth(100, MIN_TICK_PX / 2)).toBe(
+      calculateInterval(100, 1),
+    );
+  });
+});
+
 describe('getMaxEventValue', () => {
   it('returns the max event end plus 10% padding', () => {
     const rows = [

packages/app/src/components/TimelineChart/utils.ts

@@ -13,24 +13,52 @@ export function getMaxEventValue(
   return max * 1.1;
 }
 
-export function renderMs(ms: number) {
+// Number of decimal places needed to render values spaced `step` apart without
+// two adjacent ticks collapsing to the same rounded label. `step` is the tick
+// interval expressed in the same unit the label is rendered in (µs, ms, or s).
+// Intervals are always 1/2/5 × 10ⁿ buckets, so this is simply the number of
+// fractional digits the interval requires (0.5 → 1, 0.05 → 2, 2 → 0, …).
+function decimalsForStep(step: number): number {
+  if (!Number.isFinite(step) || step <= 0) {
+    return 0;
+  }
+  // A small epsilon guards against float noise where e.g. log10(0.001) lands
+  // just below an integer (−3.0000000000000004) and would floor one too far.
+  return Math.max(0, -Math.floor(Math.log10(step) + 1e-9));
+}
+
+/**
+ * Formats the given millisecond duration in an appropriate unit (µs, ms, or s).
+ *
+ * When `step` is provided, precision is added so that (ms - step) and (ms + step)
+ * are formatted as different strings. When `step` is not provided, the value is
+ * is rounded to the nearest integer and formatted without decimals.
+ *
+ * @param ms The millisecond value to format.
+ * @param step Optional tick interval, representing the number of milliseconds between adjacent values.
+ * @returns the formatted string representation.
+ */
+export function renderMs(ms: number, step?: number) {
   if (ms < 1) {
-    const µsRounded = Math.round(ms * 1000);
+    const µs = ms * 1000;
+    const decimals = step != null ? decimalsForStep(step * 1000) : 0;
+    const factor = Math.pow(10, decimals);
 
-    if (µsRounded !== 1000) {
-      return `${µsRounded}µs`;
+    // Only render as µs when it doesn't round up to a full millisecond.
+    if (Math.round(µs * factor) / factor !== 1000) {
+      return `${µs.toFixed(decimals)}µs`;
     }
   }
 
   if (ms < 1000) {
-    return `${Math.round(ms)}ms`;
-  }
-
-  if (ms % 1000 === 0) {
-    return `${Math.floor(ms / 1000)}s`;
+    const decimals = step != null ? decimalsForStep(step) : 0;
+    return `${ms.toFixed(decimals)}ms`;
   }
 
-  return `${(ms / 1000).toFixed(3)}s`;
+  const s = ms / 1000;
+  const decimals =
+    step != null ? decimalsForStep(step / 1000) : ms % 1000 === 0 ? 0 : 3;
+  return `${s.toFixed(decimals)}s`;
 }
 
 // Returns the smallest "human-friendly" interval (a 1/2/5 × 10ⁿ bucket) that
@@ -58,3 +86,15 @@ export function calculateInterval(value: number, maxTicks = 10) {
   }
   return 10 * magnitude;
 }
+
+// Minimum horizontal space reserved per tick label. The widest label we render
+// (e.g. "1.234s") is ~45px; the extra headroom keeps adjacent labels from
+// touching. Tune up for a sparser axis, down for a denser one.
+export const MIN_TICK_PX = 56;
+
+// Derives the tick interval for a timeline of range `maxVal` rendered across
+// `ticksWidthPx` pixels, budgeting ticks by MIN_TICK_PX so labels never overlap.
+export function tickIntervalForWidth(maxVal: number, ticksWidthPx: number) {
+  const maxTicks = Math.max(1, Math.floor(ticksWidthPx / MIN_TICK_PX));
+  return calculateInterval(maxVal, maxTicks);
+}