feat(dashboards): deployment markers on tile charts

.changeset/deployment-markers-on-dashboard-charts.md

@@ -0,0 +1,10 @@
+---
+'@hyperdx/app': minor
+---
+
+Overlay deployment markers on dashboard tile charts, derived from changes in the
+OpenTelemetry `service.version` resource attribute. 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

@@ -191,6 +191,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 (deployment 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

@@ -102,6 +102,7 @@ import {
   IconPlus,
   IconPresentation,
   IconRefresh,
+  IconRocket,
   IconSearch,
   IconSquaresDiagonal,
   IconTags,
@@ -113,6 +114,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';
@@ -149,6 +151,7 @@ import useDashboardContainers, {
   TabDeleteAction,
 } from '@/hooks/useDashboardContainers';
 import { useDashboardKioskMode } from '@/hooks/useDashboardKioskMode';
+import { useDeploymentAnnotations } from '@/hooks/useDeploymentAnnotations';
 import { calculateNextTilePosition, makeId } from '@/utils/tilePositioning';
 
 import ChartContainer, {
@@ -385,6 +388,7 @@ const Tile = forwardRef(
       onTimeRangeSelect,
       filters,
       showAlertAnnotations,
+      showDeployAnnotations,
       isLive,
       readOnly,
 
@@ -414,6 +418,8 @@ const Tile = forwardRef(
       filters?: Filter[];
       // When true, draw alert firing/recovery annotations on this tile's chart.
       showAlertAnnotations?: boolean;
+      // When true, draw release markers on this tile's chart.
+      showDeployAnnotations?: boolean;
       isLive?: boolean;
       readOnly?: boolean;
 
@@ -655,6 +661,30 @@ const Tile = forwardRef(
       showAlertAnnotations,
     );
 
+    // 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.
+    const deployAnnotations = useDeploymentAnnotations(
+      isFullscreen ? fullscreenDateRange : dateRange,
+      showDeployAnnotations,
+      {
+        source,
+        where: isBuilderSavedChartConfig(chart.config)
+          ? chart.config.where
+          : undefined,
+        whereLanguage: isBuilderSavedChartConfig(chart.config)
+          ? chart.config.whereLanguage
+          : undefined,
+        filters,
+      },
+    );
+
+    const annotations = useMemo(
+      () => mergeAnnotations(alertAnnotations, deployAnnotations),
+      [alertAnnotations, deployAnnotations],
+    );
+
     const filterWarning = useMemo(() => {
       const doFiltersExist = !!filters?.filter(
         f => (f.type === 'lucene' || f.type === 'sql') && f.condition.trim(),
@@ -1103,7 +1133,7 @@ const Tile = forwardRef(
                     showDisplaySwitcher={!readOnly}
                     enabled={chartEnabled}
                     config={effectiveQueriedConfig}
-                    annotations={alertAnnotations}
+                    annotations={annotations}
                     onTimeRangeSelect={
                       readOnly
                         ? undefined
@@ -1315,7 +1345,7 @@ const Tile = forwardRef(
         isSourceMissing,
         isSourceUnset,
         hasBeenVisible,
-        alertAnnotations,
+        annotations,
         isLive,
         readOnly,
       ],
@@ -1728,6 +1758,11 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
     'alertAnnotations',
     parseAsBoolean.withDefault(false),
   );
+  // Same for release markers, derived from `service.version` changes.
+  const [showDeployAnnotations, setShowDeployAnnotations] = useQueryState(
+    'deployMarkers',
+    parseAsBoolean.withDefault(false),
+  );
 
   // Track if we've initialized query for this dashboard
   const initializedDashboard = useRef<string>(undefined);
@@ -2189,6 +2224,7 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
           ]}
           onTimeRangeSelect={onTimeRangeSelect}
           showAlertAnnotations={showAlertAnnotations}
+          showDeployAnnotations={showDeployAnnotations}
           isHighlighted={highlightedTileId === chart.id}
           onUpdateChart={
             isKioskMode
@@ -2286,6 +2322,7 @@ function DBDashboardPage({ presetConfig }: { presetConfig?: Dashboard }) {
       whereLanguage,
       onTimeRangeSelect,
       showAlertAnnotations,
+      showDeployAnnotations,
       getFilterQueriesForSource,
       moveTargetContainers,
       handleMoveTileToGroup,
@@ -2712,15 +2749,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={() => setShowDeployAnnotations(v => !v)}
+                    data-testid="toggle-deploy-annotations-menu-item"
+                  >
+                    {showDeployAnnotations
+                      ? 'Hide deployment markers'
+                      : 'Show deployment markers'}
+                  </Menu.Item>
+                </>
               )}
               {containers.length > 0 && (
                 <>

packages/app/src/HDXMultiSeriesTimeChart.tsx

@@ -37,6 +37,7 @@ import { COLORS, formatNumber, truncateMiddle } from '@/utils';
 import {
   ChartAnnotation,
   getAnnotationElements,
+  resolveAnnotationSeries,
 } from './components/charts/chartAnnotations';
 import {
   ChartTooltipContainer,
@@ -48,6 +49,7 @@ import {
 import { useChartSyncId } from './chartSync';
 import {
   findNearestSeriesKey,
+  getSeriesColorForGroup,
   LineData,
   MAX_TIME_CHART_SERIES,
   toStartOfInterval,
@@ -1024,15 +1026,30 @@ 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, {
+    return getAnnotationElements(coloredAnnotations, {
       domain: xAxisDomain as [number, number],
+      // 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 { COLORS } from '@/utils';
 
@@ -1172,3 +1175,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');
+  });
+});