Skip to content
Merged
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
6 changes: 6 additions & 0 deletions .changeset/log-body-search-fallback.md
Original file line number Diff line number Diff line change
@@ -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.
274 changes: 274 additions & 0 deletions packages/api/src/mcp/__tests__/bodyExpressionFallback.int.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,274 @@
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';

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('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: [
{
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).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();
}
});

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);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Raw SQL tile test checks that a spy was called, not that the query was correct

The test only asserts that queryChartConfig received bodyExpression: 'Body'. It never checks that $__filters with a bare-text filter matches only the body row, so a macro-expansion regression that ignores bodyExpression would still pass. Fix: give the tile a Lucene filter (e.g. via the tile's filters or dashboard variables) and assert the returned rows contain only needle in body.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a real ClickHouse assertion: the MCP-hydrated raw-SQL config is executed with a bare-text filter and must return only the body-matching row. Since query_tile has no runtime-filter input, the test applies it at the query-client boundary.

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);
});
});
2 changes: 2 additions & 0 deletions packages/api/src/mcp/tools/query/eventDeltas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The rule for which source fields drive bare-text search is now copied by hand at six call sites

source.kind === SourceKind.Log ? source.bodyExpression : undefined now appears in eventDeltas.ts, helpers.ts (twice), runEventPatterns.ts and checkAlerts/index.ts. Each copy sits next to its own copy of the implicitColumnExpression and useTextIndexForImplicitColumn picks. buildSearchChartConfig (packages/common-utils/src/core/searchChartConfig.ts:150-165) already encodes the same rule: Log and Trace get the implicit column, only Log gets the body. Pull it into one helper, e.g. pickTextSearchProps(source) next to pickSampleWeightExpressionProps in packages/common-utils/src/types.ts, and use it here, in buildSearchChartConfig, and in the denoise.ts and inline-alert call sites listed as follow-ups. Then the next consumer can't leave the body out again, which is the bug this PR fixes.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

limit: { limit: sampleSize },
dateRange: [startDate, endDate],
Expand Down
5 changes: 5 additions & 0 deletions packages/api/src/mcp/tools/query/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -678,6 +678,8 @@ export async function runConfigTile(
connection: source.connection.toString(),
timestampValueExpression: source.timestampValueExpression,
implicitColumnExpression: implicitColumn,
bodyExpression:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The body-fallback projection is now copied by hand into five MCP builders, and other builders still miss it

The diff pastes source.kind === SourceKind.Log ? source.bodyExpression : undefined next to the existing implicitColumnExpression and useTextIndexForImplicitColumn ternaries in three files: helpers.ts:681 and :758, runEventPatterns.ts:171 and eventDeltas.ts:299. That same hand-copying is why denoise.ts:115/135 and the inline-alert builder at checkAlerts/index.ts:768-789 still lack the fallback, and why eventDeltas.ts:285 has never passed useTextIndexForImplicitColumn. Pull the three-field projection out of buildSearchChartConfig (common-utils/src/core/searchChartConfig.ts:150-165) into an exported helper, for example pickImplicitSearchProps(source), and spread it at every call site.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

source.kind === SourceKind.Log ? source.bodyExpression : undefined,
useTextIndexForImplicitColumn,
dateRange: [startDate, endDate] as [Date, Date],
variables: options?.variables,
Expand Down Expand Up @@ -738,6 +740,7 @@ export async function runConfigTile(
let sourceFields: {
from?: { databaseName: string; tableName: string };
implicitColumnExpression?: string;
bodyExpression?: string;
useTextIndexForImplicitColumn?: UseTextIndex;
metricTables?: MetricTable;
} = {};
Expand All @@ -752,6 +755,8 @@ export async function runConfigTile(
'implicitColumnExpression' in source
? source.implicitColumnExpression
: undefined,
bodyExpression:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Raw SQL bodyExpression hydration in runConfigTile is never used, and the test that covers it injects the filters by hand

bodyExpression is only read by renderFiltersToSql (packages/common-utils/src/core/renderChartConfig.ts:2602), and that function returns early when chartConfig.filters is empty. On this path the config is {...savedConfig, ...sourceFields, dateRange, variables}. Saved raw SQL configs have no filters field (RawSqlBaseChartConfigSchema / SharedChartSettingsSchema in types.ts), and runConfigTile has no filters option, so the new field cannot change any MCP result. The test admits this ("query_tile exposes variables but not runtime dashboard filters") and adds filters to the captured config before re-running it. That checks the common-utils renderer, not MCP behaviour. Either drop this hunk and the test until query_tile accepts filters, or add the filters input in the same PR and test it end to end through clickstack_query_tile.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

source.kind === SourceKind.Log ? source.bodyExpression : undefined,
useTextIndexForImplicitColumn:
'useTextIndexForImplicitColumn' in source
? source.useTextIndexForImplicitColumn
Expand Down
3 changes: 3 additions & 0 deletions packages/api/src/mcp/tools/query/patternDrilldown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ export async function userWhereAsSql({
tableName,
connectionId,
implicitColumnExpression,
bodyExpression,
useTextIndexForImplicitColumn,
}: {
where: string;
Expand All @@ -90,6 +91,7 @@ export async function userWhereAsSql({
tableName: string;
connectionId: string;
implicitColumnExpression?: string;
bodyExpression?: string;
useTextIndexForImplicitColumn?: UseTextIndex;
}): Promise<string> {
if (!where.trim()) return '';
Expand All @@ -103,6 +105,7 @@ export async function userWhereAsSql({
from: { databaseName, tableName },
connectionId,
implicitColumnExpression,
bodyExpression,
useTextIndexForImplicitColumn,
});
}
7 changes: 6 additions & 1 deletion packages/api/src/mcp/tools/query/runEventPatterns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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
Expand All @@ -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 },
Expand All @@ -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],
Expand All @@ -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;
Expand Down
Loading
Loading