feat: Auto-detect trace duration and render in adaptive time units (HDX-3909)

[MikeShi42]

Summary

When a chart uses a trace source with a Duration Expression, the chart now automatically defaults to adaptive time unit formatting (e.g., 120.41s, 45ms, 3µs) instead of requiring users to manually select a format. Users can still override the format through the existing display settings.

Key changes:

1. New duration output type in NumberFormatSchema — renders values adaptively as µs, ms, s, min, or h based on magnitude, instead of the clock-style hh:mm:ss format
2. Auto-detection via exact match — getTraceDurationNumberFormat() checks if any chart select valueExpression exactly equals the trace source's durationExpression. Only applies for unit-preserving aggregate functions (avg, min, max, sum, quantile, any, last_value, etc.) — skips count and count_distinct
3. useResolvedNumberFormat() hook — resolves the effective numberFormat for a chart: returns the user's explicit format if set, otherwise auto-detects duration format for trace sources
4. UI form update — Added "Duration" option to the number format selector with input unit picker (seconds/ms/µs/ns)
5. Display settings drawer — Shows the auto-detected format by default so users can see what's being applied
6. Heatmap support — Updated DBHeatmapChart tick formatter to use formatDurationMs for duration-formatted values

Components updated: DBTimeChart, DBNumberChart, DBListBarChart, DBPieChart, DBTableChart, DBHeatmapChart, DBSearchHeatmapChart, DBEditTimeChartForm, ChartDisplaySettingsDrawer

How to test locally or on Vercel

1. Create a chart from a trace source with a unit-preserving aggFn (e.g., avg/p95/p99/min/max of the Duration column)
2. Verify the chart y-axis and tooltips now show values like 120.41s or 45ms instead of raw numbers
3. Open the chart display settings and verify the "Duration" output format is shown as the default
4. Change the aggFn to count or count_distinct — verify duration formatting is NOT applied
5. Change the format to something else (e.g., "Number") and verify the override persists
6. Switch back to "Duration" and pick different input units (seconds, ms, µs, ns) — the preview should update correctly
7. Check that non-trace-source charts are unaffected (no auto-detection triggers)
8. Verify the search heatmap chart for traces still shows proper duration labels
9. Reset to defaults in the display settings drawer and verify it returns to the auto-detected duration format

References

• Linear Issue: HDX-3909

Linear Issue: HDX-3909

  

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3beb3be

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Apr 10, 2026 11:46am

[github-actions]

E2E Test Results

✅ All tests passed • 130 passed • 3 skipped • 1074s

Status	Count
✅ Passed	130
❌ Failed	0
⚠️ Flaky	3
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

PR Review

feat: Auto-detect trace duration and render in adaptive time units (HDX-3909)

Well-structured feature with good test coverage. A few issues worth addressing:

• ⚠️ formatDurationMs silent fallthrough near 1ms boundary — When ms is ~0.9995 (i.e., µsRounded >= 1000 but ms < 1), the ms < 1 block doesn't return and falls through to the ms < 1000 branch. This produces a correct result but the code is fragile. Add an explicit return for this edge case or restructure the µs block to avoid silent fallthrough.

• ⚠️ useEffect reset in ChartDisplaySettingsDrawer resets form on every prop change — useEffect(() => { reset(appliedDefaults); }, [appliedDefaults, reset]) will reset the entire form anytime settings or defaultNumberFormat changes reference. If settings is computed inline (not memoized at call sites), the user's in-progress form edits will be silently discarded. Verify that all callers memoize the settings prop, or add a guard (e.g. only reset when drawer is not open).

• ⚠️ heatmap and histogram in DURATION_PRESERVING_AGG_FNS — These aggregate functions produce frequency distributions (bucket counts), not values that preserve the unit of the input. Including them means a heatmap chart over Duration would auto-format y-axis bucket boundaries as duration, which is correct, but the bucket count values would not. Verify this is intentional and the bucket values vs. tick values are handled separately.

• ✅ Exact-match detection strategy is correct and well-tested; test suite covers edge cases thoroughly.

• ✅ useResolvedNumberFormat properly prioritizes explicit numberFormat over auto-detection.

[pulpdrew]

This matches Duration/1e6 and results in the wrong factor being applied.

it('detects duration ms expression reference without parentheses', () => {
    const result = getTraceDurationNumberFormat(TRACE_SOURCE, [
      { valueExpression: 'Duration/1e6' },
    ]);
    expect(result).toEqual({
      output: 'duration',
      factor: 0.001,
    });
  });

There are also other cases, like when the expression has spaces in it Duration / 1e6, (Duration) / 1e6 that don't work as expected - real parsing would be very nice here.

For this fallback case, maybe the condition should just be exact match to avoid over-matching?

Suggested change

	if (expr.includes(durationExpr)) {
	const precision = source.durationPrecision ?? 9;
	return {
	output: 'duration',
	factor: Math.pow(10, -precision),
	};
	}
	}
	if (expr === durationExpr) {
	const precision = source.durationPrecision ?? 9;
	return {
	output: 'duration',
	factor: Math.pow(10, -precision),
	};
	}
	}

[pulpdrew]

Could we update the OpenAPI Specs as well?

• https://github.com/hyperdxio/hyperdx/blob/main/packages/api/src/routers/external-api/v2/dashboards.ts#L188
• Run yarn docgen in the api directory

[github-actions]

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats

• Files changed: 22
• Lines changed: 281 (+ 316 in test files, excluded from tier calculation)
• Branch: cursor/HDX-3909-trace-duration-unit-rendering-14bb
• Author: MikeShi42

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[MikeShi42]

@claude can you resolve merge conflicts with main? DBEditTimeChartForm was refactored into packages/app/src/components/DBEditTimeChartForm folder, so we just need to move some of our changes into the new refactored components.

[github-actions]

Claude encountered an error —— View job

---

Resolving merge conflicts with main

• Gather context: understand current branch state and conflicts
• Explore refactored DBEditTimeChartForm folder structure in main
• Identify changes from this PR that need to be moved into the new structure
• Apply changes to the refactored components
• Run lint to verify no issues
• Commit and push resolved changes