1+ import { ClickHouseError } from '@clickhouse/client-common' ;
12import { SourceKind } from '@hyperdx/common-utils/dist/types' ;
23import { 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' ;
1416import { McpContext } from '@/mcp/tools/types' ;
1517import Connection from '@/models/connection' ;
1618import { 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. */
2334async 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} ) ;
0 commit comments