Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions static/app/components/charts/annotations/severity.spec.tsx
Original file line number Diff line number Diff line change
@@ -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>): 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);
});
});
11 changes: 11 additions & 0 deletions static/app/components/charts/annotations/severity.tsx
Original file line number Diff line number Diff line change
@@ -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;
}
}
Original file line number Diff line number Diff line change
@@ -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<string, unknown> | null;
}
4 changes: 4 additions & 0 deletions static/app/components/charts/annotations/types.tsx
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import type {TimeseriesAnnotation} from './timeseriesAnnotation';

export type AnnotationKind = 'release' | 'flag' | 'timeseriesAnnotation';

/**
Expand All @@ -9,4 +11,6 @@ export interface AnnotationItem {
kind: AnnotationKind;
start: number;
title: string;
environment?: TimeseriesAnnotation['environment'];
severity?: TimeseriesAnnotation['severity'];
}
2 changes: 1 addition & 1 deletion static/app/components/charts/bands/bandShapes.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export const BAND_Y_AXIS = {
type BandGroup = Extract<NonNullable<CustomSeriesRenderItemReturn>, {type: 'group'}>;
export type BandElement = BandGroup['children'][number];

type CartesianCoordSys = CustomSeriesRenderItemParams['coordSys'] & {
export type CartesianCoordSys = CustomSeriesRenderItemParams['coordSys'] & {
height: number;
width: number;
x: number;
Expand Down
Original file line number Diff line number Diff line change
@@ -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}}],
});
});
});
103 changes: 103 additions & 0 deletions static/app/components/charts/markers/useAnnotationMarkers.tsx
Original file line number Diff line number Diff line change
@@ -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';

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]);
}
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -1271,6 +1285,26 @@ export default Storybook.story('TimeSeriesWidgetVisualization', story => {
</Fragment>
);
});

story('Annotation Markers', () => {
return (
<Fragment>
<p>
Severe <code>annotations</code> 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.
</p>

<MediumWidget>
<TimeSeriesWidgetVisualization
plottables={[new Bars(sampleThroughputTimeSeries)]}
annotations={[...releaseAnnotations, ...changeAnnotations]}
/>
</MediumWidget>
</Fragment>
);
});
story('Deep-Linking', () => (
<div>
<p>
Expand Down
Loading
Loading