From acf4f91e32335adacad8b4fe7feee329d724f916 Mon Sep 17 00:00:00 2001 From: Adrian Bonilla Date: Wed, 18 Nov 2026 19:00:29 -0700 Subject: [PATCH 1/3] feat(charts): Add severity to annotation items --- .../charts/annotations/severity.spec.tsx | 30 ++++++++++++++ .../charts/annotations/severity.tsx | 11 ++++++ .../annotations/timeseriesAnnotation.tsx | 39 +++++++++++++++++++ .../components/charts/annotations/types.tsx | 4 ++ 4 files changed, 84 insertions(+) create mode 100644 static/app/components/charts/annotations/severity.spec.tsx create mode 100644 static/app/components/charts/annotations/severity.tsx create mode 100644 static/app/components/charts/annotations/timeseriesAnnotation.tsx diff --git a/static/app/components/charts/annotations/severity.spec.tsx b/static/app/components/charts/annotations/severity.spec.tsx new file mode 100644 index 000000000000..2126364580fc --- /dev/null +++ b/static/app/components/charts/annotations/severity.spec.tsx @@ -0,0 +1,30 @@ +import {isSevere} from './severity'; +import type {AnnotationItem} from './types'; + +const START = new Date('2026-11-03T12:00:00Z').getTime(); + +function item(overrides: Partial): AnnotationItem { + return { + id: '1', + kind: 'timeseriesAnnotation', + start: START, + title: 'Outage', + ...overrides, + }; +} + +describe('isSevere', () => { + it('is true for high severity timeseries annotations', () => { + expect(isSevere(item({severity: 'high'}))).toBe(true); + }); + + it('is false for lower severity timeseries annotations', () => { + expect(isSevere(item({severity: 'medium'}))).toBe(false); + expect(isSevere(item({severity: 'low'}))).toBe(false); + }); + + it('is false for releases and flag changes', () => { + expect(isSevere(item({kind: 'release', severity: 'high'}))).toBe(false); + expect(isSevere(item({kind: 'flag', severity: 'high'}))).toBe(false); + }); +}); diff --git a/static/app/components/charts/annotations/severity.tsx b/static/app/components/charts/annotations/severity.tsx new file mode 100644 index 000000000000..a868431487ba --- /dev/null +++ b/static/app/components/charts/annotations/severity.tsx @@ -0,0 +1,11 @@ +import type {AnnotationItem} from './types'; + +export function isSevere(item: AnnotationItem): boolean { + switch (item.kind) { + case 'timeseriesAnnotation': + return item.severity === 'high'; + case 'release': + case 'flag': + return false; + } +} diff --git a/static/app/components/charts/annotations/timeseriesAnnotation.tsx b/static/app/components/charts/annotations/timeseriesAnnotation.tsx new file mode 100644 index 000000000000..ea2ae0ba67f0 --- /dev/null +++ b/static/app/components/charts/annotations/timeseriesAnnotation.tsx @@ -0,0 +1,39 @@ +type TimeseriesAnnotationType = + | 'inbound_filter_change' + | 'infrastructure_change' + | 'sdk_update' + | 'sentry_outage' + | 'custom'; + +type TimeseriesAnnotationScope = + | 'global' + | 'spans' + | 'logs' + | 'tracemetrics' + | 'errors' + | 'occurrences'; + +type TimeseriesAnnotationSeverity = 'low' | 'medium' | 'high'; + +/** + * An external event that could explain a change in telemetry data, as + * returned by `/organizations/{org}/annotations/`. + */ +export interface TimeseriesAnnotation { + annotationType: TimeseriesAnnotationType; + createdBy: {id: string; type: 'user' | 'service_account'} | null; + createdByLabel: string | null; + dateAdded: string; + dateUpdated: string; + description: string; + endTimestamp: string | null; + environment: string | null; + id: string; + intervalType: 'point' | 'range'; + organizationId: string; + projectId: string | null; + scope: TimeseriesAnnotationScope; + severity: TimeseriesAnnotationSeverity; + startTimestamp: string; + tags: Record | null; +} diff --git a/static/app/components/charts/annotations/types.tsx b/static/app/components/charts/annotations/types.tsx index ddcbb11c3052..209f9750b38e 100644 --- a/static/app/components/charts/annotations/types.tsx +++ b/static/app/components/charts/annotations/types.tsx @@ -1,3 +1,5 @@ +import type {TimeseriesAnnotation} from './timeseriesAnnotation'; + export type AnnotationKind = 'release' | 'flag' | 'timeseriesAnnotation'; /** @@ -9,4 +11,6 @@ export interface AnnotationItem { kind: AnnotationKind; start: number; title: string; + environment?: TimeseriesAnnotation['environment']; + severity?: TimeseriesAnnotation['severity']; } From 292f852b821469a7301fbecc4cdeffb6d4e14a96 Mon Sep 17 00:00:00 2001 From: Adrian Bonilla Date: Wed, 18 Nov 2026 19:12:11 -0700 Subject: [PATCH 2/3] feat(charts): Draw a marker on the plot for severe annotations --- .../components/charts/bands/bandShapes.tsx | 2 +- .../markers/useAnnotationMarkers.spec.tsx | 86 +++++++++++++++ .../charts/markers/useAnnotationMarkers.tsx | 103 ++++++++++++++++++ .../timeSeriesWidgetVisualization.stories.tsx | 34 ++++++ .../timeSeriesWidgetVisualization.tsx | 22 +++- 5 files changed, 243 insertions(+), 4 deletions(-) create mode 100644 static/app/components/charts/markers/useAnnotationMarkers.spec.tsx create mode 100644 static/app/components/charts/markers/useAnnotationMarkers.tsx diff --git a/static/app/components/charts/bands/bandShapes.tsx b/static/app/components/charts/bands/bandShapes.tsx index 43cf07ba68a9..690f313a4ecb 100644 --- a/static/app/components/charts/bands/bandShapes.tsx +++ b/static/app/components/charts/bands/bandShapes.tsx @@ -40,7 +40,7 @@ export const BAND_Y_AXIS = { type BandGroup = Extract, {type: 'group'}>; export type BandElement = BandGroup['children'][number]; -type CartesianCoordSys = CustomSeriesRenderItemParams['coordSys'] & { +export type CartesianCoordSys = CustomSeriesRenderItemParams['coordSys'] & { height: number; width: number; x: number; diff --git a/static/app/components/charts/markers/useAnnotationMarkers.spec.tsx b/static/app/components/charts/markers/useAnnotationMarkers.spec.tsx new file mode 100644 index 000000000000..ef3174c367fc --- /dev/null +++ b/static/app/components/charts/markers/useAnnotationMarkers.spec.tsx @@ -0,0 +1,86 @@ +import type { + CustomSeriesRenderItem, + CustomSeriesRenderItemAPI, + CustomSeriesRenderItemParams, +} from 'echarts'; + +import {renderHookWithProviders} from 'sentry-test/reactTestingLibrary'; + +import type {AnnotationItem} from 'sentry/components/charts/annotations/types'; + +import {useAnnotationMarkers} from './useAnnotationMarkers'; + +const MINUTE = 60_000; + +const buckets = Array.from({length: 10}, (_, index) => ({ + start: index * MINUTE, + end: (index + 1) * MINUTE, +})); + +function change( + id: string, + time: number, + severity: AnnotationItem['severity'] +): AnnotationItem { + return {id, kind: 'timeseriesAnnotation', start: time, title: id, severity}; +} + +const api = { + coord: ([time]: number[]) => [(time ?? 0) / 1000, 100], +} as unknown as CustomSeriesRenderItemAPI; + +const params = { + coordSys: {type: 'cartesian2d', x: 0, y: 10, width: 600, height: 200}, +} as unknown as CustomSeriesRenderItemParams; + +describe('useAnnotationMarkers', () => { + it('returns no markers without severe annotations', () => { + const {result} = renderHookWithProviders(() => + useAnnotationMarkers({ + buckets, + items: [ + {id: '1.0.0', kind: 'release', start: MINUTE, title: '1.0.0'}, + change('medium', 2 * MINUTE, 'medium'), + change('low', 3 * MINUTE, 'low'), + ], + }) + ); + + expect(result.current).toBeNull(); + }); + + it('draws one marker per bucket with severe annotations, at the bucket center', () => { + const {result} = renderHookWithProviders(() => + useAnnotationMarkers({ + buckets, + items: [ + change('first', 2 * MINUTE + 10_000, 'high'), + change('second', 2 * MINUTE + 20_000, 'high'), + change('third', 5 * MINUTE, 'high'), + change('not-severe', 7 * MINUTE, 'low'), + ], + }) + ); + const series = result.current; + if (!series || typeof series.renderItem !== 'function') { + throw new Error('Expected the marker series to render items'); + } + const renderItem = series.renderItem as CustomSeriesRenderItem; + + expect(series.data).toHaveLength(2); + + const [merged, single] = [0, 1].map(dataIndex => + renderItem({...params, dataIndex, dataIndexInside: dataIndex}, api) + ); + + expect(merged).toMatchObject({ + children: [ + {type: 'line', shape: {x1: 120, y1: 10, x2: 120, y2: 210}}, + {type: 'circle', shape: {cx: 120, cy: 10}}, + ], + }); + expect(single).toMatchObject({ + children: [{shape: {x1: 300}}, {shape: {cx: 300}}], + }); + }); +}); diff --git a/static/app/components/charts/markers/useAnnotationMarkers.tsx b/static/app/components/charts/markers/useAnnotationMarkers.tsx new file mode 100644 index 000000000000..5528e18aa415 --- /dev/null +++ b/static/app/components/charts/markers/useAnnotationMarkers.tsx @@ -0,0 +1,103 @@ +import {useMemo} from 'react'; +import {useTheme, type Theme} from '@emotion/react'; +import type {CustomSeriesOption, CustomSeriesRenderItem} from 'echarts'; + +import {isSevere} from 'sentry/components/charts/annotations/severity'; +import type {AnnotationItem} from 'sentry/components/charts/annotations/types'; +import { + BAND_Z, + type BandBucket, + type CartesianCoordSys, +} from 'sentry/components/charts/bands/bandShapes'; +import { + bucketAnnotations, + type AnnotationBucket, +} from 'sentry/components/charts/bands/bucketAnnotations'; +import {defined} from 'sentry/utils/defined'; + +export const ANNOTATION_MARKERS_SERIES_ID = '__annotation_markers__'; + +const CIRCLE_RADIUS = 3; +const LINE_DASH = [2, 2]; + +interface AnnotationMarkerItem extends AnnotationBucket { + value: [start: number, y: number]; +} + +function annotationMarkerRenderItem( + data: AnnotationMarkerItem[], + theme: Theme +): CustomSeriesRenderItem { + return function renderAnnotationMarker(params, api) { + const bucket = data[params.dataIndex]; + if (!bucket) { + return null; + } + + const [x] = api.coord([bucket.start, 0]); + const plot = params.coordSys as CartesianCoordSys; + if (!defined(x) || x < plot.x || x > plot.x + plot.width) { + return null; + } + + const color = theme.tokens.dataviz.semantic.bad; + return { + type: 'group', + children: [ + { + type: 'line', + shape: {x1: x, y1: plot.y, x2: x, y2: plot.y + plot.height}, + style: {stroke: color, lineWidth: 1, lineDash: LINE_DASH}, + }, + { + type: 'circle', + shape: {cx: x, cy: plot.y, r: CIRCLE_RADIUS}, + style: {fill: color}, + }, + ], + }; + }; +} + +interface UseAnnotationMarkersParams { + buckets: BandBucket[]; + items?: readonly AnnotationItem[]; +} + +/** + * A dotted vertical line with a circle on top, drawn over the plot at the + * center of every chart bucket that has a severe annotation. + */ +export function useAnnotationMarkers({ + buckets, + items, +}: UseAnnotationMarkersParams): CustomSeriesOption | null { + const theme = useTheme(); + + return useMemo(() => { + const data: AnnotationMarkerItem[] = bucketAnnotations( + items?.filter(isSevere) ?? [], + buckets + ) + .filter(bucket => bucket.items.length > 0) + .map(bucket => ({...bucket, value: [bucket.start, 0]})); + if (data.length === 0) { + return null; + } + + return { + id: ANNOTATION_MARKERS_SERIES_ID, + type: 'custom', + renderItem: annotationMarkerRenderItem(data, theme), + name: ANNOTATION_MARKERS_SERIES_ID, + data, + color: theme.tokens.dataviz.semantic.bad, + z: BAND_Z - 1, + clip: false, + silent: true, + tooltip: {show: false}, + animation: false, + legendHoverLink: false, + }; + }, [buckets, items, theme]); +} diff --git a/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.stories.tsx b/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.stories.tsx index 70638d2bb53b..d8ef0cd9037c 100644 --- a/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.stories.tsx +++ b/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.stories.tsx @@ -86,6 +86,20 @@ const releaseAnnotations: AnnotationItem[] = releases.map(({timestamp, version}) title: version, })); +const changeAnnotations: AnnotationItem[] = ( + [ + [8, 'high', 'Sentry outage'], + [14, 'low', 'SDK update'], + [30, 'high', 'Infrastructure change'], + ] as const +).map(([index, severity, title]) => ({ + id: `change:${index}`, + kind: 'timeseriesAnnotation', + start: sampleThroughputTimeSeries.values.at(index)!.timestamp, + title, + severity, +})); + export default Storybook.story('TimeSeriesWidgetVisualization', story => { story('Getting Started', () => { return ( @@ -1271,6 +1285,26 @@ export default Storybook.story('TimeSeriesWidgetVisualization', story => { ); }); + + story('Annotation Markers', () => { + return ( + +

+ Severe annotations also get a marker on the plot: a dotted vertical + line with a circle on top, at the center of their time bucket. Severe + annotations in the same bucket share one marker. Every annotation, severe or + not, still counts toward the band under the plot. +

+ + + + +
+ ); + }); story('Deep-Linking', () => (

diff --git a/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.tsx b/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.tsx index 861d8178ee1e..2f896a3ac3bb 100644 --- a/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.tsx +++ b/static/app/views/dashboards/widgets/timeSeriesWidget/timeSeriesWidgetVisualization.tsx @@ -13,7 +13,7 @@ import unescape from 'lodash/unescape'; import {Container, Flex, Stack} from '@sentry/scraps/layout'; import type {AnnotationItem} from 'sentry/components/charts/annotations/types'; -import type {BandBucket} from 'sentry/components/charts/bands/bandShapes'; +import {BAND_Y_AXIS, type BandBucket} from 'sentry/components/charts/bands/bandShapes'; import {useBandTooltips} from 'sentry/components/charts/bands/bandTooltip'; import {mergeChartBands} from 'sentry/components/charts/bands/mergeChartBands'; import {useAnnotationBand} from 'sentry/components/charts/bands/useAnnotationBand'; @@ -21,6 +21,7 @@ import {BaseChart} from 'sentry/components/charts/baseChart'; import type {LegendItem} from 'sentry/components/charts/chartLegend'; import {ChartLegend} from 'sentry/components/charts/chartLegend'; import {getFormatter} from 'sentry/components/charts/components/tooltip'; +import {useAnnotationMarkers} from 'sentry/components/charts/markers/useAnnotationMarkers'; import { useChartXRangeSelection, type ChartXRangeSelectionProps, @@ -86,7 +87,8 @@ export interface TimeSeriesWidgetVisualizationProps extends Partial Date: Wed, 18 Nov 2026 19:19:50 -0700 Subject: [PATCH 3/3] ref(charts): Stop exporting the annotation markers series id --- static/app/components/charts/markers/useAnnotationMarkers.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/app/components/charts/markers/useAnnotationMarkers.tsx b/static/app/components/charts/markers/useAnnotationMarkers.tsx index 5528e18aa415..3e6e7b202fc1 100644 --- a/static/app/components/charts/markers/useAnnotationMarkers.tsx +++ b/static/app/components/charts/markers/useAnnotationMarkers.tsx @@ -15,7 +15,7 @@ import { } from 'sentry/components/charts/bands/bucketAnnotations'; import {defined} from 'sentry/utils/defined'; -export const ANNOTATION_MARKERS_SERIES_ID = '__annotation_markers__'; +const ANNOTATION_MARKERS_SERIES_ID = '__annotation_markers__'; const CIRCLE_RADIUS = 3; const LINE_DASH = [2, 2];