feat(dashboards): release markers on tile charts

.changeset/release-markers-on-tile-charts.md

@@ -0,0 +1,10 @@
+---
+'@hyperdx/app': minor
+---
+
+Overlay release markers on dashboard tile charts, showing when each version of a
+service first appeared so a deployment can be lined up against a change in the
+data. Markers are scoped to the data each tile is charting and tinted to match
+their service's series color, and are suppressed on charts where they can't be
+tied to a visible line, so an aggregate line spanning many services isn't
+annotated with releases you can't attribute to it.

packages/app/src/ChartUtils.tsx

@@ -198,6 +198,33 @@ export function useTimeChartSettings(
 export const ChartKeyJoiner = ' · ';
 const PreviousPeriodSuffix = ' (previous)';
 
+/**
+ * Finds the color of the series a group value belongs to — e.g. the color of
+ * the `checkout-service` line on a chart grouped by service name.
+ *
+ * Series keys are the group values joined by `ChartKeyJoiner`, prefixed by the
+ * value column name when the chart has more than one, so the group value is
+ * matched against the key's components rather than the whole key. Previous
+ * period series are skipped; they mirror a current period series' color.
+ *
+ * Used to tint chart annotations (release markers) to match the series they
+ * describe, so a marker for one service can't be read as another's.
+ */
+export function getSeriesColorForGroup(
+  lineData: LineData[],
+  group: string,
+): string | undefined {
+  for (const line of lineData) {
+    if (line.isDashed) {
+      continue;
+    }
+    if (line.currentPeriodKey.split(ChartKeyJoiner).includes(group)) {
+      return line.color;
+    }
+  }
+  return undefined;
+}
+
 // Note: roundToNearestMinutes is broken in date-fns currently
 // additionally it doesn't support seconds or > 30min
 // so we need to write our own :(

packages/app/src/DBDashboardPage.tsx

@@ -33,6 +33,7 @@ import {
   displayTypeSupportsPromQLAlerts,
   displayTypeSupportsRawSqlAlerts,
   Granularity,
+  isTimeSeriesDisplayType,
 } from '@hyperdx/common-utils/dist/core/utils';
 import {
   displayTypeRequiresSource,
@@ -108,6 +109,7 @@ import {
   IconPlus,
   IconPresentation,
   IconRefresh,
+  IconRocket,
   IconSearch,
   IconSquaresDiagonal,
   IconTags,
@@ -119,6 +121,7 @@ import {
 } from '@tabler/icons-react';
 
 import { IsolatedChartSyncProvider } from '@/chartSync';
+import { mergeAnnotations } from '@/components/charts/chartAnnotations';
 import { ContactSupportText } from '@/components/ContactSupportText';
 import SnapGridLayout from '@/components/dashboard/SnapGridLayout';
 import DashboardContainer from '@/components/DashboardContainer';
@@ -155,6 +158,7 @@ import useDashboardContainers, {
   TabDeleteAction,
 } from '@/hooks/useDashboardContainers';
 import { useDashboardKioskMode } from '@/hooks/useDashboardKioskMode';
+import { useReleaseAnnotations } from '@/hooks/useReleaseAnnotations';
 import { calculateNextTilePosition, makeId } from '@/utils/tilePositioning';
 
 import ChartContainer, {
@@ -394,6 +398,7 @@ const Tile = forwardRef(
       filters,
       variables,
       showAlertAnnotations,
+      showReleaseAnnotations,
       isLive,
       readOnly,
 
@@ -424,6 +429,8 @@ const Tile = forwardRef(
       variables?: ChartVariable[];
       // When true, draw alert firing/recovery annotations on this tile's chart.
       showAlertAnnotations?: boolean;
+      // When true, draw release markers on this tile's chart.
+      showReleaseAnnotations?: boolean;
       isLive?: boolean;
       readOnly?: boolean;
 
@@ -677,13 +684,49 @@ const Tile = forwardRef(
       return tooltip;
     }, [alert]);
 
+    // Only DBTimeChart draws annotations (see the render below) — a tile
+    // showing a table, number, pie, ... discards them. Both annotation queries
+    // stay idle for those rather than paying for a result nothing can show.
+    const tileCanDrawAnnotations = isTimeSeriesDisplayType(
+      chart.config.displayType,
+    );
+
     // Firing/recovery markers for this tile's alert, scoped to the *visible*
     // window — the fullscreen range while the fullscreen view is open, else the
     // dashboard range (off unless the dashboard toggle is on).
     const alertAnnotations = useAlertAnnotations(
       alert?.id,
       isFullscreen ? fullscreenDateRange : dateRange,
-      showAlertAnnotations,
+      showAlertAnnotations && tileCanDrawAnnotations,
+    );
+
+    // Release markers, over the same visible window. Scoped to this tile: the
+    // query runs against the tile's own source with the tile's own predicates,
+    // so a chart filtered to one service isn't annotated with another's
+    // releases. Tiles sharing a source and filters share one query.
+    //
+    // A time chart's filter lives in each series' `aggCondition`, not in the
+    // statement-level `where` (the editor clears that one), so `select` has to
+    // come along for the scoping to mean anything — `where` is carried for the
+    // configs that do set it, e.g. an imported dashboard.
+    const builderConfig = isBuilderSavedChartConfig(chart.config)
+      ? chart.config
+      : undefined;
+    const releaseAnnotations = useReleaseAnnotations(
+      isFullscreen ? fullscreenDateRange : dateRange,
+      showReleaseAnnotations && tileCanDrawAnnotations,
+      {
+        source,
+        where: builderConfig?.where,
+        whereLanguage: builderConfig?.whereLanguage,
+        select: builderConfig?.select,
+        filters,
+      },
+    );
+
+    const annotations = useMemo(
+      () => mergeAnnotations(alertAnnotations, releaseAnnotations),
+      [alertAnnotations, releaseAnnotations],
     );
 
     const filterWarning = useMemo(() => {
@@ -1175,7 +1218,7 @@ const Tile = forwardRef(
                     showDisplaySwitcher={!readOnly}
                     enabled={chartEnabled}
                     config={effectiveQueriedConfig}
-                    annotations={alertAnnotations}
+                    annotations={annotations}
                     onTimeRangeSelect={
                       readOnly
                         ? undefined
@@ -1387,7 +1430,7 @@ const Tile = forwardRef(
         isSourceMissing,
         isSourceUnset,
         hasBeenVisible,
-        alertAnnotations,
+        annotations,
         isLive,
         readOnly,
       ],
@@ -1802,6 +1845,11 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
     'alertAnnotations',
     parseAsBoolean.withDefault(false),
   );
+  // Same for release markers, derived from `service.version` changes.
+  const [showReleaseAnnotations, setShowReleaseAnnotations] = useQueryState(
+    'releaseMarkers',
+    parseAsBoolean.withDefault(false),
+  );
 
   // Track if we've initialized query for this dashboard
   const initializedDashboardRef = useRef<string>(undefined);
@@ -2270,6 +2318,7 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
           variables={showFilterVariableOptions ? variables : undefined}
           onTimeRangeSelect={onTimeRangeSelect}
           showAlertAnnotations={showAlertAnnotations}
+          showReleaseAnnotations={showReleaseAnnotations}
           isHighlighted={highlightedTileId === chart.id}
           onUpdateChart={
             isKioskMode
@@ -2367,6 +2416,7 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
       whereLanguage,
       onTimeRangeSelect,
       showAlertAnnotations,
+      showReleaseAnnotations,
       getFilterQueriesForSource,
       showFilterVariableOptions,
       variables,
@@ -2811,15 +2861,26 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
           {(hasTiles || containers.length > 0) && (
             <>
               {hasTiles && (
-                <Menu.Item
-                  leftSection={<IconTimelineEvent size={16} />}
-                  onClick={() => setShowAlertAnnotations(v => !v)}
-                  data-testid="toggle-alert-annotations-menu-item"
-                >
-                  {showAlertAnnotations
-                    ? 'Hide alert annotations'
-                    : 'Show alert annotations'}
-                </Menu.Item>
+                <>
+                  <Menu.Item
+                    leftSection={<IconTimelineEvent size={16} />}
+                    onClick={() => setShowAlertAnnotations(v => !v)}
+                    data-testid="toggle-alert-annotations-menu-item"
+                  >
+                    {showAlertAnnotations
+                      ? 'Hide alert annotations'
+                      : 'Show alert annotations'}
+                  </Menu.Item>
+                  <Menu.Item
+                    leftSection={<IconRocket size={16} />}
+                    onClick={() => setShowReleaseAnnotations(v => !v)}
+                    data-testid="toggle-release-annotations-menu-item"
+                  >
+                    {showReleaseAnnotations
+                      ? 'Hide release markers'
+                      : 'Show release markers'}
+                  </Menu.Item>
+                </>
               )}
               {containers.length > 0 && (
                 <>

packages/app/src/HDXMultiSeriesTimeChart.tsx

@@ -36,6 +36,7 @@ import { COLORS, formatNumber, truncateMiddle } from '@/utils';
 import {
   ChartAnnotation,
   getAnnotationElements,
+  resolveAnnotationSeries,
 } from './components/charts/chartAnnotations';
 import { ChartOverlayControls } from './components/charts/ChartOverlayControls';
 import {
@@ -48,6 +49,7 @@ import {
 import { useChartSyncId } from './chartSync';
 import {
   findNearestSeriesKey,
+  getSeriesColorForGroup,
   LineData,
   MAX_TIME_CHART_SERIES,
   toStartOfInterval,
@@ -796,7 +798,7 @@ export const MemoChart = memo(function MemoChart({
   lineData: LineData[];
   referenceLines?: React.ReactNode;
   /**
-   * Event markers (alerts, deploys, …) drawn as dashed vertical lines with a
+   * Event markers (alerts, releases, …) drawn as dashed vertical lines with a
    * label above. Passed as data rather than pre-rendered elements so the chart
    * can clamp them to its own x-axis domain. Distinct from `referenceLines`
    * (threshold lines).
@@ -1395,7 +1397,9 @@ export const MemoChart = memo(function MemoChart({
     [buildActivePayloadFromState, setIsClickActive],
   );
 
-  const xAxisDomain: AxisDomain = useMemo(() => {
+  // Typed as the tuple it actually is (assignable to AxisDomain) so the
+  // annotation helpers can take it without an unsafe cast.
+  const xAxisDomain: [number, number] = useMemo(() => {
     let startTime = toStartOfInterval(dateRange[0], granularity);
     let endTime = toStartOfInterval(dateRange[1], granularity);
     const endTimeIsBoundaryAligned = isSameSecond(dateRange[1], endTime);
@@ -1420,15 +1424,29 @@ export const MemoChart = memo(function MemoChart({
   // Alert/event markers as dashed lines, clamped to the chart's x-axis domain so
   // an edge marker (e.g. an alert already firing at window open) stays visible
   // instead of being dropped. Labels float in the reserved top headroom.
-  const annotationElements = useMemo(() => {
+  // Tint each marker to match the series it describes and drop the ones that
+  // can't be tied to anything on this chart — see `resolveAnnotationSeries`.
+  const coloredAnnotations = useMemo(() => {
     if (!annotations?.length) {
+      return annotations;
+    }
+    return resolveAnnotationSeries(annotations, group =>
+      getSeriesColorForGroup(lineData, group),
+    );
+  }, [annotations, lineData]);
+
+  const annotationElements = useMemo(() => {
+    if (!coloredAnnotations?.length) {
       return null;
     }
-    // xAxisDomain is a [min, max] tuple at runtime (declared as AxisDomain).
-    return getAnnotationElements(annotations, {
-      domain: xAxisDomain as [number, number],
+    return getAnnotationElements(coloredAnnotations, {
+      domain: xAxisDomain,
+      // Drawable width, so markers too close together share one label. Zero on
+      // the first paint (before ResponsiveContainer measures), which the
+      // renderer treats as "label everything".
+      plotWidth: Math.max(0, containerWidth - Y_AXIS_WIDTH),
     });
-  }, [annotations, xAxisDomain]);
+  }, [coloredAnnotations, xAxisDomain, containerWidth]);
 
   return (
     <div

packages/app/src/__tests__/ChartUtils.test.ts

@@ -5,12 +5,15 @@ import {
 } from '@hyperdx/common-utils/dist/types';
 
 import {
+  ChartKeyJoiner,
   convertToNumberChartConfig,
   convertToTableChartConfig,
   convertToTimeChartConfig,
   findNearestSeriesKey,
   formatResponseForCategoricalChart,
   formatResponseForTimeChart,
+  getSeriesColorForGroup,
+  type LineData,
 } from '@/ChartUtils';
 import {
   MAX_RENDERED_TIME_CHART_SERIES,
@@ -1590,3 +1593,55 @@ describe('ChartUtils', () => {
     });
   });
 });
+
+describe('getSeriesColorForGroup', () => {
+  const line = (
+    currentPeriodKey: string,
+    color: string,
+    isDashed = false,
+  ): LineData => ({
+    dataKey: currentPeriodKey,
+    currentPeriodKey,
+    previousPeriodKey: `${currentPeriodKey} (previous)`,
+    displayName: currentPeriodKey,
+    valueColumnName: 'count()',
+    color,
+    isDashed,
+  });
+
+  // Single value column + group by: the series key is just the group value.
+  it('matches a group value that is the whole series key', () => {
+    const lineData = [line('checkout-service', '#blue'), line('api', '#gold')];
+
+    expect(getSeriesColorForGroup(lineData, 'api')).toBe('#gold');
+  });
+
+  // Multiple value columns: the key is prefixed with the column name, joined
+  // by ChartKeyJoiner, so the group value is only one component of it.
+  it('matches a group value that is one component of a composite key', () => {
+    const lineData = [
+      line(`count()${ChartKeyJoiner}checkout-service`, '#blue'),
+      line(`count()${ChartKeyJoiner}api`, '#gold'),
+    ];
+
+    expect(getSeriesColorForGroup(lineData, 'api')).toBe('#gold');
+  });
+
+  it('returns undefined when no series covers the group', () => {
+    expect(
+      getSeriesColorForGroup([line('checkout-service', '#blue')], 'api'),
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for an empty series list', () => {
+    expect(getSeriesColorForGroup([], 'api')).toBeUndefined();
+  });
+
+  // Previous-period series mirror a current-period series' color, so skipping
+  // them keeps the marker tied to the solid line the user sees.
+  it('skips previous-period series', () => {
+    const lineData = [line('api', '#dashed', true), line('api', '#solid')];
+
+    expect(getSeriesColorForGroup(lineData, 'api')).toBe('#solid');
+  });
+});