From 9f8c3b24e361ccedcc603abf32363029ef549f26 Mon Sep 17 00:00:00 2001 From: Baris Can Vural Date: Wed, 18 Nov 2026 11:58:01 +0300 Subject: [PATCH 1/3] feat(mcp): maxBodyChars mines only the start of each body in event_patterns and emerging_signals Refs #3650 --- .changeset/patterns-max-body-chars.md | 7 +++++ .../__tests__/emergingSignalsTool.int.test.ts | 18 +++++++++++ .../src/mcp/__tests__/queryTool.int.test.ts | 30 +++++++++++++++++++ .../src/mcp/tools/query/emergingSignals.ts | 12 ++++++++ .../api/src/mcp/tools/query/eventPatterns.ts | 16 +++++++++- .../src/mcp/tools/query/runEventPatterns.ts | 18 ++++++++++- 6 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 .changeset/patterns-max-body-chars.md diff --git a/.changeset/patterns-max-body-chars.md b/.changeset/patterns-max-body-chars.md new file mode 100644 index 0000000000..38cf774c56 --- /dev/null +++ b/.changeset/patterns-max-body-chars.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/api': patch +--- + +feat(mcp): `maxBodyChars` on `clickstack_event_patterns` and +`clickstack_emerging_signals` mines only the start of each body, so long stack +traces and dumps are cut in the query and their patterns can be drilled into diff --git a/packages/api/src/mcp/__tests__/emergingSignalsTool.int.test.ts b/packages/api/src/mcp/__tests__/emergingSignalsTool.int.test.ts index 59ccb7301f..fb72744460 100644 --- a/packages/api/src/mcp/__tests__/emergingSignalsTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/emergingSignalsTool.int.test.ts @@ -218,6 +218,24 @@ describe('MCP Emerging Signals Tool', () => { expect(checkoutEmerging).toBeUndefined(); }); + it('mines only the first maxBodyChars characters of each body', async () => { + const result = await callTool(client, 'clickstack_emerging_signals', { + sourceId: logSource._id.toString(), + currentStartTime: new Date(now - 5 * 60_000).toISOString(), + currentEndTime: new Date(now).toISOString(), + baselineStartTime: new Date(now - 10 * 60_000).toISOString(), + baselineEndTime: new Date(now - 5 * 60_000).toISOString(), + sampleSize: 2000, + maxBodyChars: 12, + }); + + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.summary.bodyColumn).toBe('leftUTF8(Body, 12)'); + const emerging: EmergingPattern[] = output.emerging; + expect(emerging.map(p => p.sample)).toEqual(['shadow-eval ']); + }); + it('reports nothing novel when both windows share the same patterns', async () => { // Two non-overlapping halves of the baseline-only region (now-10min .. // now-5min). Both contain only the steady-state checkout template and diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 0e613fd5b0..0169fe6c1e 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -1301,6 +1301,36 @@ describe('MCP Query Tools', () => { expect(p.drilldownUnavailable).toContain('longer than 4000'); }); + it('mines the start of long bodies with maxBodyChars and drills by that prefix', async () => { + await bulkInsertLogs( + [101, 202, 303].map(id => ({ + Body: `Error: job ${id} failed ${'at frame '.repeat(1000)}${id}`, + ServiceName: 'trace', + SeverityText: 'ERROR', + Timestamp: base, + })), + ); + const output = await mine({ + where: 'ServiceName:trace', + maxBodyChars: 27, + }); + expect(output.summary.bodyColumn).toBe('leftUTF8(Body, 27)'); + expect(output.patterns).toHaveLength(1); + const [p] = output.patterns; + expect(p.pattern).toBe('Error: job <*> failed at fr'); + for (const sample of p.samples) expect(sample).toHaveLength(27); + const rows = await drill(output, p); + expect(rows).toHaveLength(3); + for (const r of rows) expect(r.Body.length).toBeGreaterThan(9000); + + const result = await callTool(client, 'clickstack_event_patterns', { + sourceId: logSource._id.toString(), + ...window, + maxBodyChars: 2.5, + }); + expect(result.isError).toBe(true); + }); + it('separates sampled counts from estimates', async () => { const output = await mine({ where: 'ServiceName:svc-a', diff --git a/packages/api/src/mcp/tools/query/emergingSignals.ts b/packages/api/src/mcp/tools/query/emergingSignals.ts index be00d96371..f0687028f4 100644 --- a/packages/api/src/mcp/tools/query/emergingSignals.ts +++ b/packages/api/src/mcp/tools/query/emergingSignals.ts @@ -75,6 +75,17 @@ const emergingSignalsSchema = z.object({ 'if omitted (Body for logs, SpanName for traces). ' + 'Example: "Body", "SpanName", "SpanAttributes[\'http.url\']".', ), + maxBodyChars: z + .number() + .int() + .min(1) + .max(1_000_000) + .optional() + .describe( + 'Mine only the first maxBodyChars characters of each value, e.g. 1000 for long ' + + 'stack traces or request dumps. Long values are cut in the query, so less data ' + + 'is read, and each sample is the cut value.', + ), currentStartTime: z .string() .describe( @@ -204,6 +215,7 @@ export function registerEmergingSignals({ where: input.where, whereLanguage: input.whereLanguage, bodyExpression: input.bodyExpression, + maxBodyChars: input.maxBodyChars, sampleSize: input.sampleSize, trendBuckets: 0, }; diff --git a/packages/api/src/mcp/tools/query/eventPatterns.ts b/packages/api/src/mcp/tools/query/eventPatterns.ts index 6e09c127c5..eb3bba768d 100644 --- a/packages/api/src/mcp/tools/query/eventPatterns.ts +++ b/packages/api/src/mcp/tools/query/eventPatterns.ts @@ -43,7 +43,20 @@ const eventPatternsSchema = z.object({ 'Examples: "Body", "SpanName", "LogAttributes[\'exception.type\']", ' + "\"JSONExtractString(Body, 'error', 'message')\". Other function calls are rejected. " + "Rows where the value is '' (missing key, invalid JSON) are mined as an empty " + - 'pattern; add where " != \'\'" (whereLanguage:"sql") to exclude them.', + 'pattern; add where " != \'\'" (whereLanguage:"sql") to exclude them. ' + + 'To mine the start of long values, use maxBodyChars.', + ), + maxBodyChars: z + .number() + .int() + .min(1) + .max(1_000_000) + .optional() + .describe( + 'Mine only the first maxBodyChars characters of each value, e.g. 1000 for long ' + + 'stack traces or request dumps. Long values are cut in the query, so less data ' + + 'is read; samples are the cut values, and whereSnippet matches events by that ' + + 'prefix (summary.bodyColumn shows the leftUTF8 expression used).', ), topN: z .number() @@ -124,6 +137,7 @@ export function registerEventPatterns({ where: input.where, whereLanguage: input.whereLanguage, bodyExpression: input.bodyExpression, + maxBodyChars: input.maxBodyChars, sampleSize: input.sampleSize, topN: input.topN, trendBuckets: input.trendBuckets, diff --git a/packages/api/src/mcp/tools/query/runEventPatterns.ts b/packages/api/src/mcp/tools/query/runEventPatterns.ts index a6d6fbb507..982ed6e9d3 100644 --- a/packages/api/src/mcp/tools/query/runEventPatterns.ts +++ b/packages/api/src/mcp/tools/query/runEventPatterns.ts @@ -69,6 +69,8 @@ export async function mineWindowPatterns( where?: string; whereLanguage?: 'lucene' | 'sql'; bodyExpression?: string; + /** Mine only the first maxBodyChars characters of each body. */ + maxBodyChars?: number; sampleSize?: number; trendBuckets?: number; abortSignal?: AbortSignal; @@ -152,6 +154,17 @@ export async function mineWindowPatterns( ), }; } + // Truncate in the query, so long bodies are not transferred, and in the + // drill-down predicate, so it matches the prefix the template came from. + const maxBodyChars = options?.maxBodyChars; + if (maxBodyChars != null) { + if (!Number.isSafeInteger(maxBodyChars) || maxBodyChars < 1) { + return { + error: mcpUserError('maxBodyChars must be a positive integer.'), + }; + } + bodyColumn = `leftUTF8(${bodyColumn}, ${maxBodyChars})`; + } const filters = getSourceTableFilters(source); const tableFilterSql = andSql( @@ -392,6 +405,7 @@ export async function runEventPatterns( where?: string; whereLanguage?: 'lucene' | 'sql'; bodyExpression?: string; + maxBodyChars?: number; sampleSize?: number; topN?: number; trendBuckets?: number; @@ -416,6 +430,7 @@ export async function runEventPatterns( where: options?.where, whereLanguage: options?.whereLanguage, bodyExpression: options?.bodyExpression, + maxBodyChars: options?.maxBodyChars, sampleSize: options?.sampleSize, trendBuckets, abortSignal: options?.abortSignal, @@ -500,7 +515,8 @@ export async function runEventPatterns( ? { drilldownUnavailable: `Template is longer than ${MAX_PREDICATE_TEMPLATE_LENGTH} characters, so ` + - 'whereSnippet is empty. Do not search with it; it would match every row.', + 'whereSnippet is empty. Do not search with it; it would match every row. ' + + 'Pass maxBodyChars to mine a shorter prefix of each body.', } : {}), ...(formattedTrend ? { trend: formattedTrend } : {}), From 80279b22849aa18290839c664e19e81c93c8ebf6 Mon Sep 17 00:00:00 2001 From: Baris Can Vural Date: Fri, 20 Nov 2026 14:51:39 +0300 Subject: [PATCH 2/3] fix(mcp): drop the maxBodyChars hint from drilldownUnavailable Dashboard tiles also reach runEventPatterns and cannot pass maxBodyChars; the tool descriptions already point to it. --- packages/api/src/mcp/tools/query/runEventPatterns.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/api/src/mcp/tools/query/runEventPatterns.ts b/packages/api/src/mcp/tools/query/runEventPatterns.ts index 982ed6e9d3..cb9f9ddfbe 100644 --- a/packages/api/src/mcp/tools/query/runEventPatterns.ts +++ b/packages/api/src/mcp/tools/query/runEventPatterns.ts @@ -515,8 +515,7 @@ export async function runEventPatterns( ? { drilldownUnavailable: `Template is longer than ${MAX_PREDICATE_TEMPLATE_LENGTH} characters, so ` + - 'whereSnippet is empty. Do not search with it; it would match every row. ' + - 'Pass maxBodyChars to mine a shorter prefix of each body.', + 'whereSnippet is empty. Do not search with it; it would match every row.', } : {}), ...(formattedTrend ? { trend: formattedTrend } : {}), From 40238f59d053d0a1c2e06ba1669e4993f6b31bd6 Mon Sep 17 00:00:00 2001 From: Baris Can Vural Date: Sat, 21 Nov 2026 09:27:51 +0300 Subject: [PATCH 3/3] refactor(mcp): rely on the tool schemas to bound maxBodyChars Both callers that set it validate it with zod first; dashboard tiles never set it. --- packages/api/src/mcp/tools/query/runEventPatterns.ts | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/packages/api/src/mcp/tools/query/runEventPatterns.ts b/packages/api/src/mcp/tools/query/runEventPatterns.ts index cb9f9ddfbe..ba8edb76bb 100644 --- a/packages/api/src/mcp/tools/query/runEventPatterns.ts +++ b/packages/api/src/mcp/tools/query/runEventPatterns.ts @@ -156,14 +156,9 @@ export async function mineWindowPatterns( } // Truncate in the query, so long bodies are not transferred, and in the // drill-down predicate, so it matches the prefix the template came from. - const maxBodyChars = options?.maxBodyChars; - if (maxBodyChars != null) { - if (!Number.isSafeInteger(maxBodyChars) || maxBodyChars < 1) { - return { - error: mcpUserError('maxBodyChars must be a positive integer.'), - }; - } - bodyColumn = `leftUTF8(${bodyColumn}, ${maxBodyChars})`; + // The tool schemas bound maxBodyChars to an integer from 1 to 1,000,000. + if (options?.maxBodyChars != null) { + bodyColumn = `leftUTF8(${bodyColumn}, ${options.maxBodyChars})`; } const filters = getSourceTableFilters(source);