Skip to content

Commit 210a3fb

Browse files
authored
fix(app): warn distinctly when a release-marker query fails (#3007)
## Summary Release markers silently rendered nothing when the underlying ClickHouse query failed — for example when a source's configured version expression references a column the table doesn't have, such as a missing `ResourceAttributes`. That failure looked identical to the already-handled "no releases in this time range" case, so a genuinely broken configuration gave no signal to the user. The query already surfaces the failure through React Query's normal error state, but `useReleaseAnnotations` only ever read `data`/`isFetching` and discarded it. It now shows a distinct notification on query failure, with an actionable hint pointing at the source's Service Version Expression setting when the failure looks like a missing-column error. ### How to test on Vercel preview **Preview routes:** N/A **Steps:** N/A — the changed behavior only surfaces on a ClickHouse query error (e.g. a source misconfigured to reference a nonexistent column), which the pre-seeded demo dataset doesn't naturally produce. Verified with new unit tests exercising the error and missing-column branches directly (`useReleaseAnnotations.test.tsx`). ### References - Linear Issue: HDX-5176
1 parent 2ba1b25 commit 210a3fb

3 files changed

Lines changed: 430 additions & 11 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@hyperdx/app': patch
3+
---
4+
5+
Release markers now show a distinct "couldn't load release markers" notification when the underlying query fails (e.g. a source's version expression references a column, such as `ResourceAttributes`, that the table doesn't have), instead of silently rendering no markers indistinguishable from "no releases found in this time range."

‎packages/app/src/hooks/__tests__/useReleaseAnnotations.test.tsx‎

Lines changed: 298 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { isValidElement } from 'react';
12
import {
23
BuilderChartConfigWithDateRange,
34
DerivedColumn,
@@ -27,6 +28,15 @@ jest.mock('@/hooks/useChartConfig', () => ({
2728
jest.mock('@mantine/notifications', () => ({
2829
notifications: { show: jest.fn() },
2930
}));
31+
// A getter (rather than a plain value) so individual tests can flip
32+
// `mockIsLocalMode` without re-mocking the module.
33+
let mockIsLocalMode = false;
34+
jest.mock('@/config', () => ({
35+
__esModule: true,
36+
get IS_LOCAL_MODE() {
37+
return mockIsLocalMode;
38+
},
39+
}));
3040

3141
// Untyped handle on the mocked hook. Going through the module object keeps the
3242
// mock's argument and return types loose, so the fixtures below don't need
@@ -35,6 +45,58 @@ const chartConfigModule: { useQueriedChartConfig: jest.Mock } =
3545
jest.requireMock('@/hooks/useChartConfig');
3646
const mockedUseQueriedChartConfig = chartConfigModule.useQueriedChartConfig;
3747

48+
const notificationsModule: { notifications: { show: jest.Mock } } =
49+
jest.requireMock('@mantine/notifications');
50+
const mockedNotificationsShow = notificationsModule.notifications.show;
51+
52+
/**
53+
* The error notification's `message` is JSX (to carry a truncated raw error
54+
* and, for missing-column errors, a settings link), not a plain string.
55+
* Walks it to recover the rendered text and any `href`s for assertions.
56+
* Takes `unknown` (rather than `ReactNode`) so narrowing an element's untyped
57+
* `props` needs only `in` checks, not a type assertion.
58+
*/
59+
function readNotificationMessage(node: unknown): {
60+
text: string;
61+
hrefs: string[];
62+
} {
63+
if (node == null || typeof node === 'boolean') {
64+
return { text: '', hrefs: [] };
65+
}
66+
if (typeof node === 'string' || typeof node === 'number') {
67+
return { text: String(node), hrefs: [] };
68+
}
69+
if (Array.isArray(node)) {
70+
return node.reduce<{ text: string; hrefs: string[] }>(
71+
(acc, child) => {
72+
const next = readNotificationMessage(child);
73+
return {
74+
text: acc.text + next.text,
75+
hrefs: [...acc.hrefs, ...next.hrefs],
76+
};
77+
},
78+
{ text: '', hrefs: [] },
79+
);
80+
}
81+
if (isValidElement(node)) {
82+
const props: unknown = node.props;
83+
if (props == null || typeof props !== 'object') {
84+
return { text: '', hrefs: [] };
85+
}
86+
const children = 'children' in props ? props.children : undefined;
87+
const href =
88+
'href' in props && typeof props.href === 'string'
89+
? props.href
90+
: undefined;
91+
const inner = readNotificationMessage(children);
92+
return {
93+
text: inner.text,
94+
hrefs: href ? [...inner.hrefs, href] : inner.hrefs,
95+
};
96+
}
97+
return { text: '', hrefs: [] };
98+
}
99+
38100
// Fully-formed sources, typed as their concrete kind rather than asserted, so
39101
// a schema change surfaces here instead of being silently cast away.
40102
const logSource: TLogSource = {
@@ -522,6 +584,16 @@ describe('useReleaseAnnotations', () => {
522584
mockedUseQueriedChartConfig.mockReturnValue({
523585
data: rows ? { data: rows } : undefined,
524586
isFetching,
587+
isError: false,
588+
error: null,
589+
});
590+
591+
const mockQueryError = (error: Error) =>
592+
mockedUseQueriedChartConfig.mockReturnValue({
593+
data: undefined,
594+
isFetching: false,
595+
isError: true,
596+
error,
525597
});
526598

527599
/** The config and options the hook last handed to `useQueriedChartConfig`. */
@@ -534,7 +606,10 @@ describe('useReleaseAnnotations', () => {
534606
];
535607

536608
beforeEach(() => mockQuery([]));
537-
afterEach(() => jest.clearAllMocks());
609+
afterEach(() => {
610+
jest.clearAllMocks();
611+
mockIsLocalMode = false;
612+
});
538613

539614
it('returns undefined and keeps the query idle when disabled', () => {
540615
mockQuery([{ firstSeen: '2026-07-01T00:30:00.000Z', version: '1.0.0' }]);
@@ -588,6 +663,228 @@ describe('useReleaseAnnotations', () => {
588663
expect(result.current).toBeUndefined();
589664
});
590665

666+
// Regression: the `isError` branch was added ahead of this one; guard
667+
// against a future reorder silently swallowing the empty-result case.
668+
it('warns "no releases found" for a genuinely empty result', () => {
669+
mockQuery([{ firstSeen: '2026-06-30T20:00:00.000Z', version: '1.43.0' }]);
670+
671+
renderHook(() => useReleaseAnnotations(range, true, { source: logSource }));
672+
673+
expect(mockedNotificationsShow).toHaveBeenCalledWith(
674+
expect.objectContaining({ id: 'release-markers-empty' }),
675+
);
676+
expect(mockedNotificationsShow).not.toHaveBeenCalledWith(
677+
expect.objectContaining({ id: 'release-markers-error' }),
678+
);
679+
});
680+
681+
// Regression: unlike a structural error, "no releases found" is inherently
682+
// per-window -- a different range can genuinely have different releases --
683+
// so an unchanged scope must not suppress a second window's empty warning.
684+
it('warns again for a new window even if a previous window already warned empty', () => {
685+
// A timestamp before any window in this test, so every window maps to
686+
// the same "genuinely empty" result regardless of its bounds.
687+
mockQuery([{ firstSeen: '2000-01-01T00:00:00.000Z', version: '1.0.0' }]);
688+
689+
const { rerender } = renderHook(
690+
({ range }: { range: [Date, Date] }) =>
691+
useReleaseAnnotations(range, true, { source: logSource }),
692+
{ initialProps: { range } },
693+
);
694+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
695+
expect(mockedNotificationsShow).toHaveBeenLastCalledWith(
696+
expect.objectContaining({ id: 'release-markers-empty' }),
697+
);
698+
699+
rerender({
700+
range: [
701+
new Date(range[0].getTime() + 24 * 60 * 60_000),
702+
new Date(range[1].getTime() + 24 * 60 * 60_000),
703+
],
704+
});
705+
706+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(2);
707+
expect(mockedNotificationsShow).toHaveBeenLastCalledWith(
708+
expect.objectContaining({ id: 'release-markers-empty' }),
709+
);
710+
});
711+
712+
describe('query errors', () => {
713+
// A query failure and a truly-empty result both leave `data` unset;
714+
// without distinguishing `isError` the two look identical to the user.
715+
it('warns distinctly on a query error rather than reporting "no releases found"', () => {
716+
mockQueryError(new Error('Timeout exceeded'));
717+
718+
const { result } = renderHook(() =>
719+
useReleaseAnnotations(range, true, { source: logSource }),
720+
);
721+
722+
expect(result.current).toBeUndefined();
723+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
724+
const call = mockedNotificationsShow.mock.calls[0][0];
725+
expect(call).toMatchObject({ id: 'release-markers-error', color: 'red' });
726+
expect(readNotificationMessage(call.message).text).toContain(
727+
'Timeout exceeded',
728+
);
729+
});
730+
731+
// The scenario in question: a source configured for release markers
732+
// whose table has no matching column (e.g. no `ResourceAttributes`).
733+
it('gives an actionable hint for a missing-column error, linking to the source settings', () => {
734+
mockQueryError(new Error("Missing columns: 'ResourceAttributes'"));
735+
736+
renderHook(() =>
737+
useReleaseAnnotations(range, true, { source: logSource }),
738+
);
739+
740+
const call = mockedNotificationsShow.mock.calls[0][0];
741+
expect(call.id).toBe('release-markers-error');
742+
const { text, hrefs } = readNotificationMessage(call.message);
743+
expect(text).toContain('Service Version Expression');
744+
expect(text).toContain("Missing columns: 'ResourceAttributes'");
745+
expect(hrefs).toContain(`/team#source-${logSource.id}`);
746+
});
747+
748+
// Regression: `/team` isn't reachable in local mode (e.g. the Vercel
749+
// preview), so linking there would be a dead link.
750+
it('omits the Team Settings link in local mode', () => {
751+
mockIsLocalMode = true;
752+
mockQueryError(new Error("Missing columns: 'ResourceAttributes'"));
753+
754+
renderHook(() =>
755+
useReleaseAnnotations(range, true, { source: logSource }),
756+
);
757+
758+
const call = mockedNotificationsShow.mock.calls[0][0];
759+
const { text, hrefs } = readNotificationMessage(call.message);
760+
expect(text).toContain("doesn't match a column on this source");
761+
expect(hrefs).toEqual([]);
762+
});
763+
764+
// Real ClickHouse errors often echo the full rendered SQL, which is
765+
// unreadable dumped whole into a toast.
766+
it('truncates a long raw error message', () => {
767+
mockQueryError(new Error('x'.repeat(500)));
768+
769+
renderHook(() =>
770+
useReleaseAnnotations(range, true, { source: logSource }),
771+
);
772+
773+
const call = mockedNotificationsShow.mock.calls[0][0];
774+
const { text } = readNotificationMessage(call.message);
775+
expect(text.length).toBeLessThan(500);
776+
expect(text).toContain('…');
777+
});
778+
779+
it('warns only once while the error persists', () => {
780+
mockQueryError(new Error('Timeout exceeded'));
781+
782+
const { rerender } = renderHook(() =>
783+
useReleaseAnnotations(range, true, { source: logSource }),
784+
);
785+
rerender();
786+
787+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
788+
});
789+
790+
// Regression: the warned-once latch used to reset only when markers were
791+
// toggled off, so a later, differently-scoped query's own error (or empty
792+
// result) silently went unreported because the earlier query had already
793+
// tripped the latch.
794+
it('warns again for a new query even if a previous query already warned', () => {
795+
mockQueryError(new Error('Timeout exceeded'));
796+
797+
const { rerender } = renderHook(
798+
({ where }: { where: string }) =>
799+
useReleaseAnnotations(range, true, { source: logSource, where }),
800+
{ initialProps: { where: 'ServiceName:"checkout"' } },
801+
);
802+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
803+
804+
mockQueryError(new Error('Connection reset'));
805+
rerender({ where: 'ServiceName:"cart"' });
806+
807+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(2);
808+
const lastCallArg =
809+
mockedNotificationsShow.mock.calls[
810+
mockedNotificationsShow.mock.calls.length - 1
811+
][0];
812+
expect(lastCallArg.id).toBe('release-markers-error');
813+
expect(readNotificationMessage(lastCallArg.message).text).toContain(
814+
'Connection reset',
815+
);
816+
});
817+
818+
// A reviewer's point: panning/zooming the time range doesn't fix a
819+
// structural error (e.g. a missing column), so re-showing the same
820+
// warning on every range change -- which happens every `BUCKET_MS` on a
821+
// live-tailing dashboard -- would just be noise.
822+
it('does not warn again for a pure time-range change on the same scope', () => {
823+
mockQueryError(new Error('Timeout exceeded'));
824+
825+
const { rerender } = renderHook(
826+
({ range }: { range: [Date, Date] }) =>
827+
useReleaseAnnotations(range, true, { source: logSource }),
828+
{ initialProps: { range } },
829+
);
830+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
831+
832+
rerender({
833+
range: [
834+
new Date(range[0].getTime() + 5 * 60_000),
835+
new Date(range[1].getTime() + 5 * 60_000),
836+
],
837+
});
838+
839+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
840+
});
841+
842+
// Regression: a single boolean latch stayed tripped across a kind
843+
// change on the *same* query (e.g. a background refetch that flips an
844+
// empty result to an error), silently swallowing the second warning.
845+
it('warns again when the result kind changes without a config change', () => {
846+
mockQueryError(new Error('Timeout exceeded'));
847+
848+
const { rerender } = renderHook(() =>
849+
useReleaseAnnotations(range, true, { source: logSource }),
850+
);
851+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
852+
853+
mockQuery([{ firstSeen: '2026-06-30T20:00:00.000Z', version: '1.43.0' }]);
854+
rerender();
855+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(2);
856+
expect(mockedNotificationsShow).toHaveBeenLastCalledWith(
857+
expect.objectContaining({ id: 'release-markers-empty' }),
858+
);
859+
860+
mockQueryError(new Error('Timeout exceeded'));
861+
rerender();
862+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(3);
863+
expect(mockedNotificationsShow).toHaveBeenLastCalledWith(
864+
expect.objectContaining({ id: 'release-markers-error' }),
865+
);
866+
});
867+
868+
// A real (non-empty) result between two failures clears the latch, same
869+
// as a distinct kind would -- a later failure is never "the same" one.
870+
it('warns again after recovering and failing once more on the same config', () => {
871+
mockQueryError(new Error('Timeout exceeded'));
872+
873+
const { rerender } = renderHook(() =>
874+
useReleaseAnnotations(range, true, { source: logSource }),
875+
);
876+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
877+
878+
mockQuery([{ firstSeen: '2026-07-01T00:30:00.000Z', version: '1.43.1' }]);
879+
rerender();
880+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(1);
881+
882+
mockQueryError(new Error('Timeout exceeded'));
883+
rerender();
884+
expect(mockedNotificationsShow).toHaveBeenCalledTimes(2);
885+
});
886+
});
887+
591888
it("uses the source's configured version expression", () => {
592889
renderHook(() =>
593890
useReleaseAnnotations(range, true, {

0 commit comments

Comments
 (0)