feat(explore): heat maps fixed buckets (#117083)

instead of having buckets based on the interval the users choose, we'll
provide a default bucket size that's at least 15px. The logic here is a
little interesting because the backend only supports a select number of
intervals for the x-axis. What i've done is found the closest interval
(made a new function for this) based off the pixel calculation and then
passing that in to the y-axis bucket calculation to get a square bucket.

Since there is no need for the interval selector i've disabled it!

Closes DAIN-1658
(but there's still discussion going on about this)

Author: nikkikapadia

static/app/utils/duration/millisecondsToInterval.spec.tsx

@@ -0,0 +1,113 @@
+import {millisecondsToClosestInterval} from 'sentry/utils/duration/millisecondsToInterval';
+
+const TEST_INTERVALS = [
+  '1m',
+  '2m',
+  '5m',
+  '10m',
+  '15m',
+  '30m',
+  '1h',
+  '2h',
+  '3h',
+  '4h',
+  '6h',
+  '12h',
+  '1d',
+];
+
+describe('millisecondsToClosestInterval()', () => {
+  it.each([
+    [60_000, '1m'],
+    [2 * 60_000, '2m'],
+    [5 * 60_000, '5m'],
+    [10 * 60_000, '10m'],
+    [15 * 60_000, '15m'],
+    [30 * 60_000, '30m'],
+    [3600_000, '1h'],
+    [6 * 3600_000, '6h'],
+    [24 * 3600_000, '1d'],
+  ])('returns an exact string for valid granularity (%s)', (ms, expected) => {
+    expect(millisecondsToClosestInterval(ms, TEST_INTERVALS)).toBe(expected);
+  });
+
+  it.each([
+    // 45s is between 30s and 1m — equidistant, ties go to larger
+    [45_000, '1m'],
+    // 50s is closer to 1m (60s) than to 30s
+    [50_000, '1m'],
+    // 4m is closer to 5m than to 2m
+    [4 * 60_000, '5m'],
+    // 7.5m is between 5m and 10m — equidistant, ties go to larger
+    [7.5 * 60_000, '10m'],
+    // 90m is between 1h and 2h — equidistant, ties go to larger
+    [90 * 60_000, '2h'],
+    // 100m is closer to 2h than to 1h
+    [100 * 60_000, '2h'],
+  ])(
+    'rounds to the nearest interval when between two valid granularities (%s)',
+    (ms, expected) => {
+      expect(millisecondsToClosestInterval(ms, TEST_INTERVALS)).toBe(expected);
+    }
+  );
+
+  it.each([
+    [1_000, '1m'],
+    [5_000, '1m'],
+  ])(
+    'clamps to the smallest valid interval for values below the minimum (%s)',
+    (ms, expected) => {
+      expect(millisecondsToClosestInterval(ms, TEST_INTERVALS)).toBe(expected);
+    }
+  );
+
+  it.each([
+    [48 * 3600_000, '1d'],
+    [7 * 86400_000, '1d'],
+  ])(
+    'clamps to the largest valid interval for values above the maximum (%s)',
+    (ms, expected) => {
+      expect(millisecondsToClosestInterval(ms, TEST_INTERVALS)).toBe(expected);
+    }
+  );
+
+  it.each([
+    [0, undefined],
+    [-60_000, undefined],
+    [Infinity, undefined],
+  ])('returns undefined for invalid inputs (%s)', (ms, expected) => {
+    expect(millisecondsToClosestInterval(ms, TEST_INTERVALS)).toBe(expected);
+  });
+
+  describe('less availableIntervals option', () => {
+    const availableIntervals = ['1m', '5m', '1h'];
+
+    it.each([
+      // 90s is closer to 1m (diff=30s) than to 15s (diff=75s) among available intervals
+      [90_000, '1m'],
+      // 3m is equidistant between 1m and 5m — ties go to larger
+      [3 * 60_000, '5m'],
+      // exact match still works
+      [5 * 60_000, '5m'],
+    ])('restricts selection to the provided available intervals (%s)', (ms, expected) => {
+      expect(millisecondsToClosestInterval(ms, availableIntervals)).toBe(expected);
+    });
+
+    it.each([[1_000, '1m']])(
+      'clamps to the first available interval for values below the minimum (%s)',
+      (ms, expected) => {
+        expect(millisecondsToClosestInterval(ms, availableIntervals)).toBe(expected);
+      }
+    );
+
+    it.each([
+      [48 * 3600_000, '1h'],
+      [7 * 86400_000, '1h'],
+    ])(
+      'clamps to the last available interval for values above the maximum (%s)',
+      (ms, expected) => {
+        expect(millisecondsToClosestInterval(ms, availableIntervals)).toBe(expected);
+      }
+    );
+  });
+});

static/app/utils/duration/millisecondsToInterval.tsx

@@ -0,0 +1,70 @@
+import {intervalToMilliseconds} from 'sentry/utils/duration/intervalToMilliseconds';
+import {RangeMap, type Range} from 'sentry/utils/number/rangeMap';
+
+/**
+ * Converts a millisecond value to the closest valid interval string.
+ * If the milliseconds value is not one of the exact valid interval durations,
+ * it will return the closest valid interval string (based on rounding rules).
+ * @param ms - The milliseconds value to convert.
+ * @param availableIntervals - Array of available interval strings (e.g. '1m', '5m', '1h') to choose from.
+ * @returns The closest valid interval string.
+ */
+export function millisecondsToClosestInterval(
+  ms: number,
+  availableIntervals: string[]
+): string | undefined {
+  if (ms <= 0 || !Number.isFinite(ms)) {
+    return undefined;
+  }
+
+  // sort the intervals in ascending order in case they are not in order already
+  const sortedIntervals = availableIntervals.sort(
+    (a, b) => intervalToMilliseconds(a) - intervalToMilliseconds(b)
+  );
+
+  // calculate the MIDPOINT value ranges to allow the interval to be chosen.
+  // For example if the available intervals are [1m, 5m, 1h, 4h, 6h, 1d], the valid interval range
+  // boundaries would be the numbers exactly in between the intervals.
+  // so for example:
+  // - anything from 0 -> 3m would give the 1m interval,
+  // - anything from 3m -> 32.5m would give the 5m interval (because it's closer to 5m than to 1h),
+  // - anything from 32.5m -> 2.5h would give the 1h interval,
+  // - anything from 2.5h -> 5h would give the 4h interval,
+  // - anything from 5h -> 12h would give the 6h interval,
+  // - anything from 12h -> Infinity would give the 1d interval,
+  const intervalRanges: Array<Range<string>> = [];
+  for (let i = 0; i < sortedIntervals.length; i++) {
+    const range: Range<string> = {min: 0, max: 0, value: sortedIntervals[i]!};
+    if (i < sortedIntervals.length - 1) {
+      // min value should cover end of the previous interval (or 0 if there is no previous interval)
+      if (i === 0) {
+        range.min = 0;
+      } else {
+        range.min = intervalRanges[i - 1]!.max;
+      }
+      // max value should cover up until the value that is considered "closest" to the interval.
+      // Any value up to halfway between the current and next interval would take the current interval.
+      const halfIntervalDifference = Math.round(
+        Math.abs(
+          intervalToMilliseconds(sortedIntervals[i]!) -
+            intervalToMilliseconds(sortedIntervals[i + 1]!)
+        ) / 2
+      );
+      range.max = intervalToMilliseconds(sortedIntervals[i]!) + halfIntervalDifference;
+      intervalRanges.push(range);
+    } else if (sortedIntervals.length > 1) {
+      // last interval should cover all values close to and greater than the last interval
+      range.min = intervalRanges[i - 1]?.max ?? 0;
+      range.max = Infinity;
+      intervalRanges.push(range);
+    } else {
+      range.min = 0;
+      range.max = Infinity;
+      intervalRanges.push(range);
+    }
+  }
+
+  const intervalRangeMap = new RangeMap(intervalRanges ?? []);
+  const closestInterval = intervalRangeMap.get(ms);
+  return closestInterval;
+}

static/app/views/explore/metrics/metricPanel/index.tsx

@@ -18,6 +18,7 @@ import {t} from 'sentry/locale';
 import type {PageFilters} from 'sentry/types/core';
 import type {DataUnit} from 'sentry/utils/discover/fields';
 import {intervalToMilliseconds} from 'sentry/utils/duration/intervalToMilliseconds';
+import {millisecondsToClosestInterval} from 'sentry/utils/duration/millisecondsToInterval';
 import {
   ChartIntervalUnspecifiedStrategy,
   useChartInterval,
@@ -73,6 +74,7 @@ import {ChartType} from 'sentry/views/insights/common/components/chart';
 
 const RESULT_LIMIT = 50;
 const TWO_MINUTE_DELAY = 120;
+const PIXELS_PER_X_BUCKET = 15;
 
 const CHART_TYPE_TO_ICON: Record<ChartType, 'line' | 'area' | 'bar' | 'heatmap'> = {
   [ChartType.LINE]: 'line',
@@ -125,12 +127,14 @@ export function MetricPanel({
   const visualizes = useMetricVisualizes();
   const setVisualizes = useSetMetricVisualizes();
   const setAggregateFields = useSetMetricAggregateFields();
+
+  const isHeatmap = visualize.chartType === ChartType.HEATMAP;
+
   // use the biggest interval for the heat map as this produces better patterns
   const [interval, setInterval, intervalOptions] = useChartInterval({
-    unspecifiedStrategy:
-      visualize.chartType === ChartType.HEATMAP
-        ? ChartIntervalUnspecifiedStrategy.USE_BIGGEST
-        : ChartIntervalUnspecifiedStrategy.USE_SMALLEST,
+    unspecifiedStrategy: isHeatmap
+      ? ChartIntervalUnspecifiedStrategy.USE_BIGGEST
+      : ChartIntervalUnspecifiedStrategy.USE_SMALLEST,
   });
 
   const [title, setTitle] = useState<string | undefined>(() => {
@@ -162,7 +166,6 @@ export function MetricPanel({
     staleTime: Infinity,
   });
 
-  const isHeatmap = visualize.chartType === ChartType.HEATMAP;
   const hasHeatMap = canUseMetricsHeatMap(organization);
 
   const {result: timeseriesResult} = useMetricTimeseries({
@@ -175,15 +178,21 @@ export function MetricPanel({
 
   const chartContainerRef = useRef<HTMLDivElement>(null);
   const {width: chartContainerWidth} = useDimensions({elementRef: chartContainerRef});
-  const yBuckets = getHeatmapYBuckets(selection, interval, chartContainerWidth);
+  const xBucketInterval = getHeatmapXBucketInterval(
+    selection,
+    interval,
+    chartContainerWidth,
+    intervalOptions
+  );
+  const yBuckets = getHeatmapYBuckets(selection, xBucketInterval, chartContainerWidth);
 
   const heatmapApiOptions = metricHeatmapApiOptions({
     traceMetric,
     enabled: hasHeatMap && isHeatmap && !isMetricOptionsEmpty && yBuckets > 0,
     organization,
     selection,
     query: userQuery,
-    interval,
+    interval: xBucketInterval,
     yBuckets,
   });
   const heatmapResult = useQuery({
@@ -258,7 +267,8 @@ export function MetricPanel({
         onChange={option => handleChartTypeChange(option.value)}
       />
       <CompactSelect
-        value={interval}
+        value={isHeatmap ? xBucketInterval : interval}
+        disabled={isHeatmap}
         onChange={({value}) => setInterval(value)}
         trigger={triggerProps => (
           <OverlayTrigger.Button
@@ -397,7 +407,6 @@ function getHeatmapYBuckets(
   if (intervalInMs <= 0 || chartContainerWidth <= 0) {
     return 0;
   }
-
   const xBuckets = Math.round(timeRangeInMs / intervalInMs);
   if (xBuckets <= 0) {
     return 0;
@@ -406,6 +415,28 @@ function getHeatmapYBuckets(
   return Math.max(1, Math.round(xBuckets * (STACKED_GRAPH_HEIGHT / chartContainerWidth)));
 }
 
+/**
+ * Computes the X-axis bucket interval for the heatmap API.
+ * The X-axis bucket interval is derived from the container width and the number of
+ * pixels per X bucket.
+ */
+function getHeatmapXBucketInterval(
+  selection: PageFilters,
+  interval: string,
+  chartContainerWidth: number,
+  intervalOptions: Array<{label: string; value: string}>
+): string {
+  const timeRangeInMs = getDiffInMinutes(selection.datetime) * 60 * 1000;
+  const msPerXBucket = Math.round(
+    timeRangeInMs / (chartContainerWidth / PIXELS_PER_X_BUCKET)
+  );
+  const xBucketInterval = millisecondsToClosestInterval(
+    msPerXBucket,
+    intervalOptions.map(option => option.value)
+  );
+  return xBucketInterval || interval;
+}
+
 /**
  * The heatmap API response doesn't include the metric unit because the
  * query uses the generic `value` field. This function patches the Y-axis