From 8afddddb9777791b1a53a7722f3d7989d30d0ae8 Mon Sep 17 00:00:00 2001 From: Pavan Nalam Date: Mon, 16 Nov 2026 10:22:42 -0800 Subject: [PATCH 1/2] fix(api): use log body fallback in MCP and alert queries --- .changeset/log-body-search-fallback.md | 6 + .../bodyExpressionFallback.int.test.ts | 222 ++++++++++++++++++ .../api/src/mcp/tools/query/eventDeltas.ts | 2 + packages/api/src/mcp/tools/query/helpers.ts | 5 + .../src/mcp/tools/query/patternDrilldown.ts | 3 + .../src/mcp/tools/query/runEventPatterns.ts | 7 +- .../bodyExpressionFallback.int.test.ts | 148 ++++++++++++ packages/api/src/tasks/checkAlerts/index.ts | 2 + 8 files changed, 394 insertions(+), 1 deletion(-) create mode 100644 .changeset/log-body-search-fallback.md create mode 100644 packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts create mode 100644 packages/api/src/tasks/checkAlerts/__tests__/bodyExpressionFallback.int.test.ts diff --git a/.changeset/log-body-search-fallback.md b/.changeset/log-body-search-fallback.md new file mode 100644 index 000000000..10397cf1b --- /dev/null +++ b/.changeset/log-body-search-fallback.md @@ -0,0 +1,6 @@ +--- +'@hyperdx/api': patch +--- + +Use the log source body expression for bare-text MCP searches, pattern filters, +event deltas, and alert alias queries when no implicit search column is set. diff --git a/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts b/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts new file mode 100644 index 000000000..954f09fe6 --- /dev/null +++ b/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts @@ -0,0 +1,222 @@ +import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node'; +import { SourceKind } from '@hyperdx/common-utils/dist/types'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; + +import * as config from '@/config'; +import { + bulkInsertLogs, + DEFAULT_DATABASE, + DEFAULT_LOGS_TABLE, + getLoggedInAgent, + getServer, +} from '@/fixtures'; +import Connection from '@/models/connection'; +import { LogSource, Source, SourceDocument } from '@/models/source'; + +import { callTool, createTestClient, getFirstText } from './mcpTestUtils'; + +describe('log body fallback for bare-text MCP filters', () => { + const server = getServer(); + let client: Client; + let source: SourceDocument; + let connectionId: string; + let now: number; + + beforeAll(async () => { + await server.start(); + }); + + beforeEach(async () => { + const { team, user } = await getLoggedInAgent(server); + const connection = await Connection.create({ + team: team._id, + name: 'Body fallback', + host: config.CLICKHOUSE_HOST, + username: config.CLICKHOUSE_USER, + password: config.CLICKHOUSE_PASSWORD, + }); + connectionId = connection.id; + source = await Source.create({ + kind: SourceKind.Log, + team: team._id, + connection: connection._id, + name: 'Logs', + from: { databaseName: DEFAULT_DATABASE, tableName: DEFAULT_LOGS_TABLE }, + timestampValueExpression: 'Timestamp', + bodyExpression: 'Body', + }); + client = await createTestClient({ + teamId: team._id.toString(), + userId: user._id.toString(), + }); + now = Date.now(); + await bulkInsertLogs( + [2, 7].flatMap(minutes => [ + { + Body: 'needle in body', + ServiceName: 'api', + SeverityText: 'error', + LogAttributes: { message: 'other' }, + Timestamp: new Date(now - minutes * 60_000), + }, + { + Body: 'other', + ServiceName: 'needle', + SeverityText: 'info', + LogAttributes: { message: 'needle in map' }, + Timestamp: new Date(now - minutes * 60_000), + }, + ]), + ); + }); + + afterEach(async () => { + await client.close(); + await server.clearDBs(); + }); + + afterAll(async () => { + await server.stop(); + }); + + const currentWindow = () => ({ + startTime: new Date(now - 5 * 60_000).toISOString(), + endTime: new Date(now).toISOString(), + }); + + it.each([ + { implicitColumnExpression: undefined, expectedBody: 'needle in body' }, + { implicitColumnExpression: '', expectedBody: 'needle in body' }, + { implicitColumnExpression: 'ServiceName', expectedBody: 'other' }, + ])( + 'searches the correct field with implicitColumnExpression=$implicitColumnExpression', + async ({ implicitColumnExpression, expectedBody }) => { + await LogSource.updateOne( + { _id: source._id }, + implicitColumnExpression === undefined + ? { $unset: { implicitColumnExpression: '' } } + : { $set: { implicitColumnExpression } }, + ); + const result = await callTool(client, 'clickstack_search', { + sourceId: source._id.toString(), + where: 'needle', + ...currentWindow(), + }); + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.result.data).toEqual([ + expect.objectContaining({ Body: expectedBody }), + ]); + }, + ); + + it('uses a map-valued body expression for bare-text search', async () => { + await LogSource.updateOne( + { _id: source._id }, + { $set: { bodyExpression: "LogAttributes['message']" } }, + ); + const result = await callTool(client, 'clickstack_search', { + sourceId: source._id.toString(), + where: 'needle', + ...currentWindow(), + }); + expect(result.isError).toBeFalsy(); + expect(JSON.parse(getFirstText(result)).result.data).toEqual([ + expect.objectContaining({ Body: 'other' }), + ]); + }); + + it('hydrates a raw SQL tile with its log source body expression', async () => { + const saved = await callTool(client, 'clickstack_save_dashboard', { + name: 'Body fallback', + tiles: [ + { + name: 'Matching logs', + config: { + configType: 'sql', + displayType: 'table', + connectionId, + sourceId: source._id.toString(), + sqlTemplate: + 'SELECT Body FROM $__sourceTable WHERE $__timeFilter(Timestamp) AND $__filters', + }, + }, + ], + }); + expect(saved.isError).toBeFalsy(); + const dashboard = JSON.parse(getFirstText(saved)); + const query = jest.spyOn(ClickhouseClient.prototype, 'queryChartConfig'); + try { + const result = await callTool(client, 'clickstack_query_tile', { + dashboardId: dashboard.id, + tileId: dashboard.tiles[0].id, + ...currentWindow(), + }); + expect(result.isError).toBeFalsy(); + expect(query).toHaveBeenCalledWith( + expect.objectContaining({ + config: expect.objectContaining({ bodyExpression: 'Body' }), + }), + ); + } finally { + query.mockRestore(); + } + }); + + it('uses the fallback for pattern samples, counts and drill-down filters', async () => { + const result = await callTool(client, 'clickstack_event_patterns', { + sourceId: source._id.toString(), + where: 'needle', + ...currentWindow(), + }); + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.summary.totalCount).toBe(1); + expect(output.summary.sampledCount).toBe(1); + expect(output.patterns).toHaveLength(1); + expect(output.patterns[0].whereSnippet).toContain('Body'); + const drilldown = await callTool(client, 'clickstack_search', { + sourceId: source._id.toString(), + where: output.patterns[0].whereSnippet, + whereLanguage: 'sql', + ...currentWindow(), + }); + expect(drilldown.isError).toBeFalsy(); + expect(JSON.parse(getFirstText(drilldown)).result.data).toEqual([ + expect.objectContaining({ Body: 'needle in body' }), + ]); + }); + + it('uses the fallback in both emerging-signals windows', async () => { + const result = await callTool(client, 'clickstack_emerging_signals', { + sourceId: source._id.toString(), + where: 'needle', + currentStartTime: currentWindow().startTime, + currentEndTime: currentWindow().endTime, + baselineStartTime: new Date(now - 10 * 60_000).toISOString(), + baselineEndTime: currentWindow().startTime, + }); + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.summary.currentWindow.total).toBe(1); + expect(output.summary.currentWindow.sampled).toBe(1); + expect(output.summary.baselineWindow.total).toBe(1); + expect(output.summary.baselineWindow.sampled).toBe(1); + }); + + it('uses the fallback in both event-deltas samples', async () => { + const result = await callTool(client, 'clickstack_event_deltas', { + sourceId: source._id.toString(), + target: { ...currentWindow(), where: 'needle' }, + baseline: { + startTime: new Date(now - 10 * 60_000).toISOString(), + endTime: currentWindow().startTime, + where: 'needle', + }, + }); + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.summary.targetSampleCount).toBe(1); + expect(output.summary.baselineSampleCount).toBe(1); + }); +}); diff --git a/packages/api/src/mcp/tools/query/eventDeltas.ts b/packages/api/src/mcp/tools/query/eventDeltas.ts index bed6345f9..603267551 100644 --- a/packages/api/src/mcp/tools/query/eventDeltas.ts +++ b/packages/api/src/mcp/tools/query/eventDeltas.ts @@ -296,6 +296,8 @@ export function registerEventDeltas({ context, registerTool }: ToolRegistrar) { 'implicitColumnExpression' in source ? source.implicitColumnExpression : undefined, + bodyExpression: + source.kind === SourceKind.Log ? source.bodyExpression : undefined, orderBy: stableSampleExpr, limit: { limit: sampleSize }, dateRange: [startDate, endDate], diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 282bf2f05..63f5d9a66 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -678,6 +678,8 @@ export async function runConfigTile( connection: source.connection.toString(), timestampValueExpression: source.timestampValueExpression, implicitColumnExpression: implicitColumn, + bodyExpression: + source.kind === SourceKind.Log ? source.bodyExpression : undefined, useTextIndexForImplicitColumn, dateRange: [startDate, endDate] as [Date, Date], variables: options?.variables, @@ -738,6 +740,7 @@ export async function runConfigTile( let sourceFields: { from?: { databaseName: string; tableName: string }; implicitColumnExpression?: string; + bodyExpression?: string; useTextIndexForImplicitColumn?: UseTextIndex; metricTables?: MetricTable; } = {}; @@ -752,6 +755,8 @@ export async function runConfigTile( 'implicitColumnExpression' in source ? source.implicitColumnExpression : undefined, + bodyExpression: + source.kind === SourceKind.Log ? source.bodyExpression : undefined, useTextIndexForImplicitColumn: 'useTextIndexForImplicitColumn' in source ? source.useTextIndexForImplicitColumn diff --git a/packages/api/src/mcp/tools/query/patternDrilldown.ts b/packages/api/src/mcp/tools/query/patternDrilldown.ts index 5e85cb6c0..b8ee1edd2 100644 --- a/packages/api/src/mcp/tools/query/patternDrilldown.ts +++ b/packages/api/src/mcp/tools/query/patternDrilldown.ts @@ -80,6 +80,7 @@ export async function userWhereAsSql({ tableName, connectionId, implicitColumnExpression, + bodyExpression, useTextIndexForImplicitColumn, }: { where: string; @@ -90,6 +91,7 @@ export async function userWhereAsSql({ tableName: string; connectionId: string; implicitColumnExpression?: string; + bodyExpression?: string; useTextIndexForImplicitColumn?: UseTextIndex; }): Promise { if (!where.trim()) return ''; @@ -103,6 +105,7 @@ export async function userWhereAsSql({ from: { databaseName, tableName }, connectionId, implicitColumnExpression, + bodyExpression, useTextIndexForImplicitColumn, }); } diff --git a/packages/api/src/mcp/tools/query/runEventPatterns.ts b/packages/api/src/mcp/tools/query/runEventPatterns.ts index f92e42395..c20ba29e9 100644 --- a/packages/api/src/mcp/tools/query/runEventPatterns.ts +++ b/packages/api/src/mcp/tools/query/runEventPatterns.ts @@ -11,7 +11,7 @@ import type { ChartConfigWithDateRange, ChartVariable, } from '@hyperdx/common-utils/dist/types'; -import { DisplayType } from '@hyperdx/common-utils/dist/types'; +import { DisplayType, SourceKind } from '@hyperdx/common-utils/dist/types'; import { trace } from '@opentelemetry/api'; import { ClickhouseClient } from '@/clickhouse'; @@ -168,6 +168,8 @@ export async function mineWindowPatterns( 'implicitColumnExpression' in source ? source.implicitColumnExpression : undefined; + const bodyExpression = + source.kind === SourceKind.Log ? source.bodyExpression : undefined; const useTextIndexForImplicitColumn = 'useTextIndexForImplicitColumn' in source ? source.useTextIndexForImplicitColumn @@ -190,6 +192,7 @@ export async function mineWindowPatterns( connection: source.connection.toString(), timestampValueExpression: source.timestampValueExpression, implicitColumnExpression: implicitColumn, + bodyExpression, useTextIndexForImplicitColumn, orderBy: [{ ordering: 'DESC' as const, valueExpression: 'rand()' }], limit: { limit: sampleSize, offset: 0 }, @@ -211,6 +214,7 @@ export async function mineWindowPatterns( connection: source.connection.toString(), timestampValueExpression: source.timestampValueExpression, implicitColumnExpression: implicitColumn, + bodyExpression, useTextIndexForImplicitColumn, limit: { limit: 1, offset: 0 }, dateRange: [startDate, endDate] as [Date, Date], @@ -232,6 +236,7 @@ export async function mineWindowPatterns( tableName: source.from.tableName, connectionId: source.connection.toString(), implicitColumnExpression: implicitColumn, + bodyExpression, useTextIndexForImplicitColumn, }).catch(err => { if (queriesFailed || options.abortSignal?.aborted) return null; diff --git a/packages/api/src/tasks/checkAlerts/__tests__/bodyExpressionFallback.int.test.ts b/packages/api/src/tasks/checkAlerts/__tests__/bodyExpressionFallback.int.test.ts new file mode 100644 index 000000000..b766831a1 --- /dev/null +++ b/packages/api/src/tasks/checkAlerts/__tests__/bodyExpressionFallback.int.test.ts @@ -0,0 +1,148 @@ +import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node'; +import { + getMetadata, + Metadata, +} from '@hyperdx/common-utils/dist/core/metadata'; +import { SourceKind } from '@hyperdx/common-utils/dist/types'; + +import * as config from '@/config'; +import { createTeam } from '@/controllers/team'; +import { bulkInsertLogs, getServer } from '@/fixtures'; +import Connection from '@/models/connection'; +import { ISource, LogSource, Source } from '@/models/source'; +import { computeAliasWithClauses } from '@/tasks/checkAlerts'; +import { fetchSampleLines } from '@/tasks/checkAlerts/template'; + +describe('log body fallback in alert queries', () => { + const server = getServer(); + let source: ISource; + let clickhouseClient: ClickhouseClient; + let metadata: Metadata; + const savedSearch = { + id: 'body-fallback', + select: 'Body AS message', + where: 'needle', + whereLanguage: 'lucene' as const, + }; + let startTime: Date; + let endTime: Date; + + beforeAll(async () => { + await server.start(); + }); + + beforeEach(async () => { + const team = await createTeam({ name: 'Body fallback' }); + const connection = await Connection.create({ + team: team._id, + name: 'Default', + host: config.CLICKHOUSE_HOST, + username: config.CLICKHOUSE_USER, + password: config.CLICKHOUSE_PASSWORD, + }); + source = await LogSource.create({ + team: team._id, + connection: connection._id, + name: 'Logs', + from: { databaseName: 'default', tableName: 'otel_logs' }, + timestampValueExpression: 'Timestamp', + bodyExpression: 'Body', + }); + clickhouseClient = new ClickhouseClient({ + host: connection.host, + username: connection.username, + password: connection.password, + }); + metadata = getMetadata(clickhouseClient); + const now = new Date(); + startTime = new Date(now.getTime() - 60_000); + endTime = new Date(now.getTime() + 60_000); + await bulkInsertLogs([ + { + Body: 'needle in body', + ServiceName: 'api', + SeverityText: 'error', + Timestamp: now, + }, + { + Body: 'other', + ServiceName: 'needle', + SeverityText: 'info', + Timestamp: now, + }, + ]); + }); + + afterEach(async () => { + await clickhouseClient.close(); + await server.clearDBs(); + }); + + afterAll(async () => { + await server.stop(); + }); + + it('renders saved-search aliases with a body-only source', async () => { + const clauses = await computeAliasWithClauses( + savedSearch, + source, + metadata, + ); + expect(clauses).toEqual( + expect.arrayContaining([expect.objectContaining({ name: 'message' })]), + ); + }); + + it('includes only matching body rows in notification samples', async () => { + const sample = await fetchSampleLines({ + clickhouseClient, + metadata, + source, + savedSearch, + startTime, + endTime, + }); + expect(sample).toContain('needle in body'); + expect(sample).not.toContain('other'); + }); + + it('keeps an explicit implicit column ahead of the body for notification samples', async () => { + await LogSource.updateOne( + { _id: source.id }, + { $set: { implicitColumnExpression: 'ServiceName' } }, + ); + const updated = await Source.findById(source.id); + expect(updated).not.toBeNull(); + const sample = await fetchSampleLines({ + clickhouseClient, + metadata, + source: updated!, + savedSearch, + startTime, + endTime, + }); + expect(sample).toContain('other'); + expect(sample).not.toContain('needle in body'); + }); + + it('does not introduce a body fallback for trace sources', async () => { + const traceSource = await Source.create({ + kind: SourceKind.Trace, + team: source.team, + connection: source.connection, + name: 'Traces', + from: { databaseName: 'default', tableName: 'otel_traces' }, + timestampValueExpression: 'Timestamp', + spanNameExpression: 'SpanName', + }); + await expect( + computeAliasWithClauses( + { ...savedSearch, select: 'SpanName AS span' }, + traceSource, + metadata, + ), + ).rejects.toThrow( + 'Can not search bare text without an implicit column set.', + ); + }); +}); diff --git a/packages/api/src/tasks/checkAlerts/index.ts b/packages/api/src/tasks/checkAlerts/index.ts index d34af3dd8..dc9e6292d 100644 --- a/packages/api/src/tasks/checkAlerts/index.ts +++ b/packages/api/src/tasks/checkAlerts/index.ts @@ -187,6 +187,8 @@ export async function computeAliasWithClauses( source.kind === SourceKind.Log || source.kind === SourceKind.Trace ? source.implicitColumnExpression : undefined, + bodyExpression: + source.kind === SourceKind.Log ? source.bodyExpression : undefined, useTextIndexForImplicitColumn: source.kind === SourceKind.Log || source.kind === SourceKind.Trace ? source.useTextIndexForImplicitColumn From 0edeed9b2d4400e0ea22913bc533d5b9cf6244a5 Mon Sep 17 00:00:00 2001 From: Pavan Nalam Date: Mon, 16 Nov 2026 17:12:44 -0800 Subject: [PATCH 2/2] test(api): strengthen log body fallback regression coverage --- .../bodyExpressionFallback.int.test.ts | 64 +++++++++++++++++-- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts b/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts index 954f09fe6..69ae7232b 100644 --- a/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts +++ b/packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts @@ -1,4 +1,5 @@ import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node'; +import { isRawSqlChartConfig } from '@hyperdx/common-utils/dist/guards'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { Client } from '@modelcontextprotocol/sdk/client/index.js'; @@ -126,7 +127,44 @@ describe('log body fallback for bare-text MCP filters', () => { ]); }); - it('hydrates a raw SQL tile with its log source body expression', async () => { + it('rejects bare-text search without an implicit column or body expression', async () => { + await LogSource.updateOne( + { _id: source._id }, + { $unset: { implicitColumnExpression: '', bodyExpression: '' } }, + ); + const result = await callTool(client, 'clickstack_search', { + sourceId: source._id.toString(), + where: 'needle', + ...currentWindow(), + }); + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain( + 'Can not search bare text without an implicit column set.', + ); + }); + + it('does not introduce a body fallback for MCP trace searches', async () => { + const traceSource = await Source.create({ + kind: SourceKind.Trace, + team: source.team, + connection: source.connection, + name: 'Traces', + from: { databaseName: 'default', tableName: 'otel_traces' }, + timestampValueExpression: 'Timestamp', + spanNameExpression: 'SpanName', + }); + const result = await callTool(client, 'clickstack_search', { + sourceId: traceSource._id.toString(), + where: 'needle', + ...currentWindow(), + }); + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain( + 'Can not search bare text without an implicit column set.', + ); + }); + + it('uses raw SQL tile hydration to filter by the log body expression', async () => { const saved = await callTool(client, 'clickstack_save_dashboard', { name: 'Body fallback', tiles: [ @@ -153,11 +191,25 @@ describe('log body fallback for bare-text MCP filters', () => { ...currentWindow(), }); expect(result.isError).toBeFalsy(); - expect(query).toHaveBeenCalledWith( - expect.objectContaining({ - config: expect.objectContaining({ bodyExpression: 'Body' }), - }), - ); + expect(query).toHaveBeenCalledTimes(1); + const [queryOptions] = query.mock.calls[0]; + if (!isRawSqlChartConfig(queryOptions.config)) { + throw new Error('Expected a raw SQL tile query'); + } + const clickhouseClient = new ClickhouseClient({ + host: config.CLICKHOUSE_HOST, + username: config.CLICKHOUSE_USER, + password: config.CLICKHOUSE_PASSWORD, + }); + // query_tile exposes variables but not runtime dashboard filters. + const filtered = await clickhouseClient.queryChartConfig({ + ...queryOptions, + config: { + ...queryOptions.config, + filters: [{ type: 'lucene', condition: 'needle' }], + }, + }); + expect(filtered.data).toEqual([{ Body: 'needle in body' }]); } finally { query.mockRestore(); }