feat(dashboards): Add groupBy handling to TimeSeries (#95116)

More work to align `TimeSeries` with the response format of
`/events-timeseries` endpoint. This time, `groupBy`! The endpoint
returns "group by" information as an array of key-value objects. This PR
adds that to the `TimeSeries` type, and updates
`TimeSeriesWidgetVisualization` to take `groupBy` into account when
creating the legends.

Right now, nothing in our code _sets_ `groupBy`, instead it does
shenanigans like setting `yAxis` to `"prod"` or `"prod,v1.2"` to get the
correct labels. This PR doesn't update any of that usage yet, so the
current UI is unaffected. I'll either update that usage in the near
future, or we'll get the correct behaviour for free once we switch to
using `/events-timeseries`.

**e.g.,**

In this screenshot, both the `TimeSeries` have a `yAxis` of
`"p50(span.duration)"` but different group by, which you can see in the
legend.
<img width="445" alt="Screenshot 2025-07-09 at 10 23 03 AM"
src="https://github.com/user-attachments/assets/3dd224e0-d944-48a9-b3de-47fc6a0a4f02"
/>

---------

Co-authored-by: Dominik Buszowiecki <44422760+DominikB2014@users.noreply.github.com>

Author: gggritso

static/app/views/dashboards/widgets/common/types.tsx

@@ -46,12 +46,18 @@ export type TimeSeriesItem = {
   incomplete?: boolean;
 };
 
+type TimeSeriesGroupBy = {
+  key: string;
+  value: string;
+};
+
 export type TimeSeries = {
   meta: TimeSeriesMeta;
   values: TimeSeriesItem[];
   yAxis: string;
   confidence?: Confidence;
   dataScanned?: 'full' | 'partial';
+  groupBy?: TimeSeriesGroupBy[];
   sampleCount?: AccuracyStats<number>;
   samplingRate?: AccuracyStats<number | null>;
 };

static/app/views/dashboards/widgets/timeSeriesWidget/formatters/formatTimeSeriesName.spec.tsx

@@ -82,4 +82,35 @@ describe('formatSeriesName', () => {
       expect(formatTimeSeriesName(timeSeries)).toEqual(result);
     });
   });
+
+  describe('groupBy', () => {
+    it.each([
+      [
+        'equation|p75(measurements.cls);76123',
+        [{key: 'release', value: 'v0.0.2'}],
+        'v0.0.2',
+      ],
+      ['p95(span.duration)', [{key: 'release', value: 'v0.0.2'}], 'v0.0.2'],
+      [
+        'p95(span.duration)',
+        [
+          {key: 'release', value: 'v0.0.2'},
+          {key: 'env', value: 'prod'},
+        ],
+        'v0.0.2,prod',
+      ],
+      [
+        'p95(span.duration)',
+        [{key: 'release', value: 'frontend@31804d9a5f0b5e4f53055467cd258e1c'}],
+        '31804d9a5f0b',
+      ],
+    ])('Formats %s with groupBy %s as %s', (name, groupBy, result) => {
+      const timeSeries = TimeSeriesFixture({
+        yAxis: name,
+        groupBy,
+      });
+
+      expect(formatTimeSeriesName(timeSeries)).toEqual(result);
+    });
+  });
 });

static/app/views/dashboards/widgets/timeSeriesWidget/formatters/formatTimeSeriesName.tsx

@@ -9,11 +9,37 @@ import WidgetLegendNameEncoderDecoder from 'sentry/views/dashboards/widgetLegend
 import type {TimeSeries} from 'sentry/views/dashboards/widgets/common/types';
 
 export function formatTimeSeriesName(timeSeries: TimeSeries): string {
+  // If the timeSeries has `groupBy` information, the label is made by
+  // concatenating the values of the groupBy, since there's no point repeating
+  // the name of the Y axis multiple times in the legend.
+  if (timeSeries.groupBy?.length && timeSeries.groupBy.length > 0) {
+    return `${timeSeries.groupBy
+      ?.map(groupBy => {
+        if (groupBy.key === 'release') {
+          return formatVersion(groupBy.value);
+        }
+
+        return groupBy.value;
+      })
+      .join(',')}`;
+  }
+
   let {yAxis: seriesName} = timeSeries;
+
   // Decode from series name disambiguation
   seriesName = WidgetLegendNameEncoderDecoder.decodeSeriesNameForLegend(seriesName)!;
 
-  // Check if it's a release version
+  // Attempt to parse the `seriesName` as a version. A correct `TimeSeries`
+  // would have a `yAxis` like `p50(span.duration)` with a `groupBy` like
+  // `[{key: "release", value: "proj@1.2.3"}]`. `groupBy` was only introduced
+  // recently though, so many `TimeSeries` instead mash the group by information
+  // into the `yAxis` property, e.g., the `yAxis` might have been set to
+  // `"proj@1.2.3"` just to get the correct rendering in the chart legend. We
+  // cover these cases by parsing the `yAxis` as a series name. This works badly
+  // because sometimes it'll interpet email addresses as versions, which causes
+  // bugs. We should update all usages of `TimeSeriesWidgetVisualization` to
+  // correctly specify `yAxis` and `groupBy`, and/or to use the time
+  // `/events-timeseries` endpoint which does this automatically.
   seriesName = formatVersion(seriesName);
 
   // Check for special-case measurement formatting

static/app/views/dashboards/widgets/timeSeriesWidget/plottables/continuousTimeSeries.tsx

@@ -58,8 +58,21 @@ export abstract class ContinuousTimeSeries<
     this.config = config;
   }
 
+  /**
+   * Continuous time series names need to be unique to disambiguate them from other series. We use both the `yAxis` and the `groupBy` to create the name. This makes it possible to pass in two different time series with the same `yAxis` as long as they have different `groupBy` information.
+   */
   get name(): string {
-    return this.timeSeries.yAxis;
+    let name = `${this.timeSeries.yAxis}`;
+
+    if (this.timeSeries.groupBy?.length) {
+      name += ` : ${this.timeSeries.groupBy
+        ?.map(groupBy => {
+          return `${groupBy.key}:${groupBy.value}`;
+        })
+        .join(',')}`;
+    }
+
+    return name;
   }
 
   get label(): string {

static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.stories.tsx

@@ -923,6 +923,15 @@ export default Storybook.story('TimeSeriesWidgetVisualization', (story, APIRefer
           default. The legend will always include an entry for every plottable, even if
           some plottables have the same alias, as you can see in the second example.
         </p>
+        <p>
+          By default, <Storybook.JSXNode name="TimeSeriesWidgetVisualization" /> creates
+          legend labels using all information from the <code>TimeSeries</code> object,
+          including the <code>yAxis</code> and the <code>groupBy</code>. In the first two
+          examples, the label uses the <code>yAxis</code> property. In the third example,
+          each <code>TimeSeries</code> has a <code>groupBy</code> property, so the{' '}
+          <code>yAxis</code> property is not shown in the label. The best way to override
+          this is by using the <code>alias</code> of a plottable.
+        </p>
 
         <code>{JSON.stringify(legendSelection)}</code>
 
@@ -945,6 +954,40 @@ export default Storybook.story('TimeSeriesWidgetVisualization', (story, APIRefer
               ]}
             />
           </MediumWidget>
+          <MediumWidget>
+            <TimeSeriesWidgetVisualization
+              plottables={[
+                new Line({
+                  ...sampleDurationTimeSeries,
+                  yAxis: 'span.duration()',
+                  groupBy: [
+                    {
+                      key: 'release',
+                      value: 'proj@v0.6.2',
+                    },
+                    {
+                      key: 'env',
+                      value: 'production',
+                    },
+                  ],
+                }),
+                new Line({
+                  ...sampleDurationTimeSeriesP50,
+                  yAxis: 'span.duration()',
+                  groupBy: [
+                    {
+                      key: 'release',
+                      value: 'proj@v0.6.1',
+                    },
+                    {
+                      key: 'env',
+                      value: 'production',
+                    },
+                  ],
+                }),
+              ]}
+            />
+          </MediumWidget>
         </Storybook.SideBySide>
       </Fragment>
     );