Skip to content

Commit d5aa218

Browse files
authored
Merge branch 'main' into fix/implicit-search-fixedstring-hastoken
2 parents 8d2b55c + c372a71 commit d5aa218

14 files changed

Lines changed: 650 additions & 232 deletions

File tree

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
'@hyperdx/app': patch
3+
---
4+
5+
fix: pulse the list-bar and histogram charts while they refresh
6+
7+
The Services dashboard's list-bar and latency histogram charts kept their
8+
previous data during a refresh but gave no sign that new data was loading,
9+
and the histogram could briefly swap its chart for "Loading Chart Data...".
10+
Both now keep their previous data on screen and pulse while the refetch runs,
11+
like the other charts.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@hyperdx/api': patch
3+
---
4+
5+
fix(mcp): time-limit the `clickstack_trace_top_time_consuming_operations` tool.
6+
Its queries now use the MCP request timeout and `max_execution_time` ceiling,
7+
which a source's `querySettings` can no longer override. A timeout returns
8+
guidance to shorten the window or narrow `parentFilter` instead of an "invalid
9+
SQL" hint, and the client-side `Timeout error.` now gets the timeout hint in
10+
every MCP tool. Sources with a multi-column `timestampValueExpression`
11+
(including a leading Date column such as `EventDate, EventTime`) now return
12+
correct breakdowns.

‎.github/VOUCHED.td‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
# copilot is listed because vouch only auto-exempts logins ending in "[bot]".
2626
# GitHub's Copilot coding agent has the login "Copilot", so without an entry
2727
# its PRs would be closed.
28+
28hus
2829
adityapimpalkar
2930
alex-fedotyev
3031
alok87

‎packages/api/src/mcp/__tests__/query.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,17 @@ describe('errorHint', () => {
309309
expect(hint).toContain('Narrow the time range');
310310
});
311311

312+
it('should match the client-side request timeout', () => {
313+
const error = new Error('Timeout error.');
314+
expect(errorHint(error.message, error)).toContain('execution-time limit');
315+
});
316+
317+
it('should not give query-tuning advice for a socket timeout', () => {
318+
const error: NodeJS.ErrnoException = new Error('connect ETIMEDOUT');
319+
error.code = 'ETIMEDOUT';
320+
expect(errorHint(error.message, error)).toBeNull();
321+
});
322+
312323
it('should match SETTING_CONSTRAINT_VIOLATION errors', () => {
313324
const hint = errorHint(
314325
"Setting max_result_rows shouldn't be greater than 1000. (SETTING_CONSTRAINT_VIOLATION)",

‎packages/api/src/mcp/__tests__/trace.int.test.ts‎

Lines changed: 140 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { ClickHouseError } from '@clickhouse/client-common';
12
import { SourceKind } from '@hyperdx/common-utils/dist/types';
23
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
34

@@ -11,6 +12,7 @@ import {
1112
getLoggedInAgent,
1213
getServer,
1314
} from '@/fixtures';
15+
import { MCP_REQUEST_TIMEOUT } from '@/mcp/tools/query/helpers';
1416
import { McpContext } from '@/mcp/tools/types';
1517
import Connection from '@/models/connection';
1618
import { Source, type SourceDocument } from '@/models/source';
@@ -19,6 +21,15 @@ import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
1921

2022
// ─── Helpers ──────────────────────────────────────────────────────────────────
2123

24+
type BreakdownOperation = {
25+
service: string;
26+
operation: string;
27+
totalTimeMs: number;
28+
calls: number;
29+
inParents: number;
30+
shareOfTotalTime: number;
31+
};
32+
2233
/** Insert trace spans into the default otel_traces table. */
2334
async function bulkInsertTraces(
2435
spans: {
@@ -1212,10 +1223,10 @@ describe('MCP Trace Tools', () => {
12121223

12131224
// DB operations should be ranked first (higher total time)
12141225
const dbOp = output.operations.find(
1215-
(op: any) => op.operation === CHILD_DB_OP,
1226+
(op: BreakdownOperation) => op.operation === CHILD_DB_OP,
12161227
);
12171228
const cacheOp = output.operations.find(
1218-
(op: any) => op.operation === CHILD_CACHE_OP,
1229+
(op: BreakdownOperation) => op.operation === CHILD_CACHE_OP,
12191230
);
12201231
expect(dbOp).toBeDefined();
12211232
expect(cacheOp).toBeDefined();
@@ -1250,7 +1261,7 @@ describe('MCP Trace Tools', () => {
12501261

12511262
// Only trace 2's children should be included (1 call each)
12521263
const dbOp = output.operations.find(
1253-
(op: any) => op.operation === CHILD_DB_OP,
1264+
(op: BreakdownOperation) => op.operation === CHILD_DB_OP,
12541265
);
12551266
expect(dbOp).toBeDefined();
12561267
expect(dbOp.inParents).toBe(1);
@@ -1301,6 +1312,31 @@ describe('MCP Trace Tools', () => {
13011312
expect(output.summary.grandTotalTimeMs).toBeGreaterThan(0);
13021313
});
13031314

1315+
it('handles a multi-column timestampValueExpression with a leading Date column', async () => {
1316+
await Source.updateOne(
1317+
{ _id: traceSource._id },
1318+
{ timestampValueExpression: 'toDate(Timestamp), Timestamp' },
1319+
);
1320+
1321+
const result = await callTool(
1322+
client,
1323+
'clickstack_trace_top_time_consuming_operations',
1324+
{
1325+
sourceId: traceSource._id.toString(),
1326+
parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`,
1327+
startTime: new Date(now.getTime() - 10 * 60 * 1000).toISOString(),
1328+
endTime: new Date(now.getTime() + 60 * 1000).toISOString(),
1329+
},
1330+
);
1331+
1332+
expect(result.isError).toBeFalsy();
1333+
const output = JSON.parse(getFirstText(result));
1334+
const dbOp = output.operations.find(
1335+
(op: BreakdownOperation) => op.operation === CHILD_DB_OP,
1336+
);
1337+
expect(dbOp?.inParents).toBe(2);
1338+
});
1339+
13041340
it('should return error for invalid parentFilter SQL', async () => {
13051341
const result = await callTool(
13061342
client,
@@ -1314,8 +1350,108 @@ describe('MCP Trace Tools', () => {
13141350
);
13151351

13161352
expect(result.isError).toBe(true);
1317-
expect(getFirstText(result)).toContain('Failed to compute breakdown');
1353+
const text = getFirstText(result);
1354+
expect(text).toContain('Failed to compute breakdown');
1355+
expect(text).toContain('must be valid ClickHouse SQL');
1356+
expect(text).not.toContain('shorter startTime/endTime window');
13181357
});
1358+
1359+
it('applies the MCP time limits even when the source sets max_execution_time', async () => {
1360+
await Source.updateOne(
1361+
{ _id: traceSource._id },
1362+
{
1363+
querySettings: [
1364+
{ setting: 'max_execution_time', value: '3600' },
1365+
{ setting: 'max_threads', value: '2' },
1366+
],
1367+
},
1368+
);
1369+
const querySpy = jest.spyOn(ClickhouseClient.prototype, 'query');
1370+
try {
1371+
const result = await callTool(
1372+
client,
1373+
'clickstack_trace_top_time_consuming_operations',
1374+
{
1375+
sourceId: traceSource._id.toString(),
1376+
parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`,
1377+
startTime: new Date(now.getTime() - 10 * 60 * 1000).toISOString(),
1378+
endTime: new Date(now.getTime() + 60 * 1000).toISOString(),
1379+
},
1380+
);
1381+
1382+
expect(result.isError).toBeFalsy();
1383+
const call = querySpy.mock.calls.find(([args]) =>
1384+
args.query.includes('parent_traces'),
1385+
);
1386+
expect(call?.[0].clickhouse_settings).toMatchObject({
1387+
max_execution_time: 30,
1388+
readonly: '2',
1389+
max_threads: '2',
1390+
});
1391+
const ctx: ClickhouseClient =
1392+
querySpy.mock.contexts[querySpy.mock.calls.indexOf(call!)];
1393+
expect(ctx.requestTimeoutMs).toBe(MCP_REQUEST_TIMEOUT);
1394+
} finally {
1395+
querySpy.mockRestore();
1396+
}
1397+
});
1398+
1399+
it.each([
1400+
['client request timeout', new Error('Timeout error.')],
1401+
[
1402+
'ClickHouse TIMEOUT_EXCEEDED',
1403+
new ClickHouseError({
1404+
code: '159',
1405+
type: 'TIMEOUT_EXCEEDED',
1406+
message: 'Timeout exceeded: elapsed 30.001 seconds, maximum: 30',
1407+
}),
1408+
],
1409+
])('returns actionable guidance on a %s', async (_label, error) => {
1410+
const text = await callBreakdownWithFailingQuery(error);
1411+
expect(text).toContain('Failed to compute breakdown');
1412+
expect(text).toContain('execution-time limit');
1413+
expect(text).toContain('shorter startTime/endTime window');
1414+
expect(text).toContain('minParentDurationMs');
1415+
expect(text).not.toContain('must be valid ClickHouse SQL');
1416+
});
1417+
1418+
it('gives no query-tuning or invalid-SQL advice on a socket timeout', async () => {
1419+
const error: NodeJS.ErrnoException = new Error('connect ETIMEDOUT');
1420+
error.code = 'ETIMEDOUT';
1421+
const text = await callBreakdownWithFailingQuery(error);
1422+
expect(text).toContain('Failed to compute breakdown');
1423+
expect(text).not.toContain('execution-time limit');
1424+
expect(text).not.toContain('shorter startTime/endTime window');
1425+
expect(text).not.toContain('must be valid ClickHouse SQL');
1426+
});
1427+
1428+
async function callBreakdownWithFailingQuery(error: Error) {
1429+
const original = ClickhouseClient.prototype.query;
1430+
const querySpy = jest
1431+
.spyOn(ClickhouseClient.prototype, 'query')
1432+
.mockImplementation(function (this: ClickhouseClient, args) {
1433+
if (args.query.includes('parent_traces')) {
1434+
return Promise.reject(error);
1435+
}
1436+
return original.call(this, args);
1437+
});
1438+
try {
1439+
const result = await callTool(
1440+
client,
1441+
'clickstack_trace_top_time_consuming_operations',
1442+
{
1443+
sourceId: traceSource._id.toString(),
1444+
parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`,
1445+
startTime: new Date(now.getTime() - 10 * 60 * 1000).toISOString(),
1446+
endTime: new Date(now.getTime() + 60 * 1000).toISOString(),
1447+
},
1448+
);
1449+
expect(result.isError).toBe(true);
1450+
return getFirstText(result);
1451+
} finally {
1452+
querySpy.mockRestore();
1453+
}
1454+
}
13191455
});
13201456
});
13211457
});

‎packages/api/src/mcp/tools/query/helpers.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
convertToInternalTileConfig,
3333
isConfigTile,
3434
} from '@/routers/external-api/v2/utils/dashboards';
35+
import { isQueryTimeoutError } from '@/tasks/checkAlerts/errors';
3536
import { trimToolResponse } from '@/utils/trimToolResponse';
3637
import type { ExternalDashboardTileWithId } from '@/utils/zod';
3738
import { externalDashboardTileSchemaWithId } from '@/utils/zod';
@@ -869,6 +870,20 @@ function findCause<T>(
869870
return undefined;
870871
}
871872

873+
const SOCKET_TIMEOUT_CODES: ReadonlySet<string> = new Set(['ETIMEDOUT']);
874+
875+
/**
876+
* True when a query ran out of time: ClickHouse's max_execution_time or the
877+
* client request timeout. A socket ETIMEDOUT is excluded because ClickHouse
878+
* was unreachable, so narrowing the query won't help.
879+
*/
880+
export function isQueryOutOfTime(e: unknown): boolean {
881+
const socketTimeout = findCause(e, (c): c is Error =>
882+
hasNodeErrorCode(c, SOCKET_TIMEOUT_CODES),
883+
);
884+
return !socketTimeout && isQueryTimeoutError(e);
885+
}
886+
872887
/** @internal Exported for testing only. */
873888
export function errorHint(msg: string, error?: unknown): string | null {
874889
const unknownVariableError = findCause(
@@ -911,7 +926,10 @@ export function errorHint(msg: string, error?: unknown): string | null {
911926
// Match only real timeouts. A bare `max_execution_time` substring would also
912927
// hijack SETTING_CONSTRAINT_VIOLATION / readonly errors ("Setting
913928
// max_execution_time shouldn't be greater than…"), which need a different fix.
914-
if (/TIMEOUT_EXCEEDED|Timeout exceeded/i.test(msg)) {
929+
if (
930+
/TIMEOUT_EXCEEDED|Timeout exceeded/i.test(msg) ||
931+
isQueryOutOfTime(error)
932+
) {
915933
return (
916934
'The query exceeded its execution-time limit. Narrow the time range so ' +
917935
'ClickHouse can prune partitions, add filters to reduce the rows scanned, ' +

0 commit comments

Comments
 (0)