Skip to content

feat(mcp): maxBodyChars mines only the start of each body in event_patterns and emerging_signals - #3742

Open
bcanvural wants to merge 2 commits into
ClickHouse:mainfrom
bcanvural:feat/patterns-max-body-chars
Open

bcanvural wants to merge 2 commits into
ClickHouse:mainfrom
bcanvural:feat/patterns-max-body-chars

Conversation

@bcanvural

Copy link
Copy Markdown
Contributor

Summary

Closes #3650. Adds a maxBodyChars option to clickstack_event_patterns and clickstack_emerging_signals, as agreed in the issue.

Long error logs (multi-KB stack traces, request dumps) are slow to mine: every sampled row's full body is read from ClickHouse, Drain is slow on them, and templates over 4,000 characters get no drill-down whereSnippet. Often the most frequent error pattern is the one that can't be drilled into.

With maxBodyChars: N, the body column becomes leftUTF8(<body>, N):

  • the cut happens in the query, so only the first N characters are read;
  • the same expression is used in the drill-down predicate, so whereSnippet matches events by the prefix the template came from;
  • summary.bodyColumn shows the expression used.

It works on top of bodyExpression (a column, a map reference or JSONExtractString). The value must be an integer from 1 to 1,000,000; mineWindowPatterns checks it again before it goes into SQL. The drilldownUnavailable hint for long templates now points to maxBodyChars.

How to reproduce

Starting point: make dev-int.

On main:

  1. Add the two new tests from this PR (queryTool.int.test.ts, emergingSignalsTool.int.test.ts).
  2. make dev-int FILE="mcp/__tests__/(queryTool|emergingSignalsTool) --testNamePattern=maxBodyChars": both fail, because the option is ignored and the full body is mined.

On this branch:

  1. The same command passes both tests.
  2. make dev-int FILE="mcp/__tests__/(queryTool|emergingSignalsTool)" passes (126 tests).

How to test on Vercel preview

N/A — non-UI change.

References

@bcanvural
bcanvural requested a review from a team as a code owner November 20, 2026 07:22
@changeset-bot

changeset-bot Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 80279b2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@hyperdx/api Patch
@hyperdx/app Patch
@hyperdx/otel-collector Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Nov 20, 2026

Copy link
Copy Markdown

@bcanvural is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

`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.',

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.

🟡 P2 — New drilldownUnavailable hint tells callers to pass maxBodyChars even on paths that cannot accept it

The hint is now added to every long template, but runEventPatterns is also called for EventPatterns dashboard tiles in packages/api/src/mcp/tools/query/helpers.ts:547. That call never forwards maxBodyChars, and the tile tools have no such parameter, so an agent there is told to do something it can't. The same hint also appears when the caller already passed a maxBodyChars above 4000. Fix: only add the sentence when maxBodyChars is accepted on that path, e.g. a canTruncate option set by the eventPatterns tool. When it was already set, say to lower it below MAX_PREDICATE_TEMPLATE_LENGTH instead.

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.

Fixed in 80279b2: I removed the sentence. Dashboard tiles also reach this code and can't pass maxBodyChars, and the descriptions of clickstack_event_patterns and clickstack_emerging_signals already point to it.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 P0/P1 in code this PR adds or changes: fix before asking for review.
  • 🟡 P2 in code this PR changes: your call. Fix if small, otherwise reply.
  • 🔵 P3 is collapsed at the bottom: nobody needs to act on it before merge.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    priority. Reply with one sentence; if it is P0, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

2 finding(s): 🔴 0 P0/P1 · 🟡 0 P2 · 🔵 2 P3

No inline comments. 2 P3 folded at the bottom.

🔵 2 P3 — no action needed before merge
  • 🔵 P3 packages/api/src/mcp/tools/query/eventPatterns.ts:126 — maxBodyChars Zod schema is copied into two tools instead of living with the other shared query schemas → eventPatterns.ts:126 and emergingSignals.ts:78 both define z.number().int().min(1).max(1_000_000).optional(). Their descriptions already differ slightly. The shared MCP query schemas (sourceIdSchema, whereSchema, whereLanguageSchema) live in packages/api/src/mcp/tools/query/schemas.ts. Export one maxBodyCharsSchema from there and use it in both tools; if a tool needs extra wording, add it with .describe() on the shared schema. This follows the REQUIRED DRY rule ('Before you add a type, schema, or helper') and stops the two bounds from drifting apart.
  • 🔵 P3 packages/api/src/mcp/tools/query/runEventPatterns.ts:161 — The second maxBodyChars check in mineWindowPatterns can't fail from any caller, and it accepts a different range than the Zod schema → Only two paths set maxBodyChars, and both pass through a Zod .int().min(1).max(1_000_000) schema first. The dashboard path in helpers.ts:547 never sets it. So the !Number.isSafeInteger || < 1 branch can never fail, and the 2.5 case in the new test only exercises the Zod rejection. The check is also a second source of truth with a different rule, because it has no 1,000,000 upper bound. Either delete it and rely on the schema, or keep it as the single authoritative bound (including the max) and add a unit test that calls mineWindowPatterns directly with an invalid value.

Priority comes from a separate grading pass over the finished review. P3 is folded here instead of posted inline. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a small, well-contained change. maxBodyChars is validated at both MCP tool boundaries (z.number().int().min(1).max(1_000_000)), re-guarded with Number.isSafeInteger before it reaches the leftUTF8(${bodyColumn}, ${maxBodyChars}) interpolation, and bodyColumn is independently sanitized — so the SQL interpolation is not injectable. The leftUTF8 wrap composes correctly with JSONExtractString/map bodyExpression, feeds the sample SELECT, summary.bodyColumn, and the drill-down predicate consistently, and the integration tests assert the exact expression and prefix behavior. No P0/P1/P2 findings.

🔵 P3 nitpicks (2)
  • packages/api/src/mcp/tools/query/runEventPatterns.ts:160 — the runtime guard re-validates maxBodyChars with !Number.isSafeInteger(maxBodyChars) || maxBodyChars < 1 but omits the 1_000_000 upper bound both zod schemas enforce, so the exported helper's contract diverges from its callers' (harmless today — unreachable from both MCP paths and a no-op in leftUTF8).
    • Fix: mirror the 1..1_000_000 range in the runtime guard, ideally via a shared bound constant, so the two validation layers cannot drift.
    • maintainability, api-contract, kieran-typescript
  • packages/api/src/mcp/tools/query/emergingSignals.ts:85 — the maxBodyChars describe() omits the summary.bodyColumn shows the leftUTF8 expression used note that the event_patterns describe includes, even though emerging_signals surfaces the same wrapped expression in summary.bodyColumn.
    • Fix: append the matching summary.bodyColumn clause to the emerging_signals describe string so both tools document the same observable contract.
    • api-contract

Reviewers (9): correctness, security, testing, maintainability, project-standards, performance, api-contract, kieran-typescript, previous-comments.

Testing gaps:

  • No test combines maxBodyChars with a JSONExtractString/map-reference bodyExpression, so the ordering that wraps leftUTF8(JSONExtractString(Body, 'message'), N) and still matches on drill-down is unverified.
  • The defensive maxBodyChars re-check in mineWindowPatterns (runEventPatterns.ts:161) is unreachable from the MCP path — the maxBodyChars: 2.5 case is rejected by zod's .int() at the schema layer, not by this branch — so the branch is untested.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

Dashboard tiles also reach runEventPatterns and cannot pass maxBodyChars;
the tool descriptions already point to it.
@bcanvural

Copy link
Copy Markdown
Contributor Author

@pulpdrew this adds maxBodyChars as you suggested in #3650. The bots have done two rounds: the one P2 is fixed in 80279b2, and only P3s are left. The CI workflows are waiting for a maintainer to approve them before they run on this fork PR.

}
// 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;

@brandon-pereira brandon-pereira Nov 20, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I see

  maxBodyChars: z
    .number()
    .int()
    .min(1)
    .max(1_000_000)
    .optional()

What is the scenario where we need this additional check? is this something we can enforce via typescript and downstream zod schemas as opposed to a runtime check?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bodyExpression: allow truncating the body (substring / left) for pattern mining

2 participants