Repository navigation
fix(mcp): return partial describe_source results on timeout - #3259
Conversation
Raise the clickstack_describe_source deadline from 10s to 30s to match the other MCP query tools. At the deadline, abort the signal and return whatever discovery has gathered (columns at minimum, with skippedStages) instead of discarding it. A 2s backstop answers from the latest snapshot if a ClickHouse call ignores the signal. The timeout error is only returned when the column schema never loaded. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: f3e4451 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
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 |
🔵 Tier 2 — Low RiskSmall, isolated change with no API route or data model modifications. Why this tier:
Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns. Stats
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
PR Review
3 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 3 minor 2 posted as inline comment(s) on the changed lines. 1 listed below. Findings outside the changed lines1 minor
Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
|
Deep Review✅ No critical issues found. This is a focused, well-tested change to the 🟡 P2 — recommended
🔵 P3 nitpicks (1)
Reviewers (2): orchestrator deep-analysis (correctness, reliability, maintainability, and testing lenses applied directly to the diff), previous-comments. Testing gaps:
Residual risk (advisory, intentional): raising the deadline 10s→30s holds ClickHouse discovery queries up to ~3x longer per call, which can increase concurrent query pressure under load — a deliberate trade-off to match the other MCP query tools' budget. 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 |
E2E Test Results✅ All tests passed • 393 passed • 1 skipped • 1179s
Tests ran across 4 shards in parallel. |
| function getHandler() { | ||
| let handler: ((args: { sourceId: string }) => Promise<ToolResult>) | null = | ||
| null; | ||
| registerDescribeSource({ |
There was a problem hiding this comment.
🔵 minor — New metric-source behaviour and the outcome span attribute have no tests
Every test uses a Trace source, so nothing checks that metric sources now list metricNames in skippedStages, either in the abort-before-stage-5 path or in the backstop snapshot (via optionalStages). That was one of the behaviours this PR changed on purpose. Nothing checks mcp.describe_source.outcome either. Fix: add a SourceKind.Metric fixture whose metricTables are populated, abort during map keys, and assert skippedStages contains metricNames. Also add a test that mocks trace.getActiveSpan and asserts the outcome attribute.
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
| const DESCRIBE_TIMEOUT_MS = 10_000; | ||
| // When discovery's signal is aborted; it then returns what it has so far. | ||
| // Matches the 30s budget of the other MCP query tools. | ||
| export const DESCRIBE_TIMEOUT_MS = 30_000; |
There was a problem hiding this comment.
🔵 minor — The 30s/32s budget is copied by hand from query/helpers.ts
DESCRIBE_TIMEOUT_MS = 30_000 and DESCRIBE_BACKSTOP_MS = 2_000 repeat max_execution_time: 30 and MCP_REQUEST_TIMEOUT = 32_000 from packages/api/src/mcp/tools/query/helpers.ts:75,84. They stay in sync only because a comment says so. Fix: export MCP_REQUEST_TIMEOUT (and the 30s limit) from helpers.ts and derive both constants from them.
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
Report mapAttributeKeys / metricNames as skipped when the deadline hits after only some Map columns or metric kinds finished, keep finished results in the backstop snapshot, leave stages with nothing to sample out of it, and derive the outcome span attribute from the returned result. Add metric-source and partial-stage tests.
|
|
||
| expect(source.partial).toBe(true); | ||
| expect(source.skippedStages).toEqual(['metricNames']); | ||
| }); |
There was a problem hiding this comment.
🔵 minor — Tests mock abort as a rejection, but the real helpers resolve empty on abort
rejectOnAbort makes getAllKeyValues and sampleMetricNamesWithLookback reject when aborted. The real Metadata.getAllKeyValues (common-utils/src/core/metadata.ts:2748-2761) swallows the abort and resolves [], and so does the lookback helper. So the skip-detection paths are tested against behaviour production never shows, which is why the metricNames bug above passes. Mock these to resolve [] on abort, matching the real helpers, and assert skippedStages.
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
…mpty (deep-review P2)
| 'Schema discovery timed out. The ClickHouse server may be under load. ' + | ||
| 'Try again, or use clickstack_list_sources for basic source info without schema details.', | ||
| ); | ||
| if (controller.signal.aborted) { |
There was a problem hiding this comment.
🔵 minor — Any error thrown after the 30s abort is reported as a timeout, hiding the real cause
The catch block returns timedOutResult() whenever controller.signal.aborted is true. It doesn't check whether the error was actually an abort. getColumns, getSource and getConnectionById take no signal. If one of them throws a real error between 30s and 32s (for example a missing table or a Mongo failure), the agent gets 'Schema discovery timed out before the column schema loaded' and is told to retry, and the real error is never logged. Only use the timeout result for abort errors (check e.name === 'AbortError', or check that the error came from a signalled call). Otherwise log and rethrow as the pre-deadline path does.
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
…w major) getAllKeyValues drops aborted chunks instead of throwing, so a stage that returns some values after the abort is still incomplete. Also report mapAttributeValues as skipped when map keys were cut short, matching the backstop snapshot.
| clearTimeout(abortTimer); | ||
| clearTimeout(backstopTimer); | ||
| } | ||
| }, |
There was a problem hiding this comment.
🔵 minor — After the abort, any error is reported as a timeout and never logged
In the catch block, controller.signal.aborted sends every rejection to timedOutResult() before the logger.warn. So a real failure that lands after 30s is returned as "timed out before the column schema loaded" with outcome timeout, and the cause is dropped. Examples: getColumns hitting UNKNOWN_TABLE (it takes no signal), or a Mongo error from getConnectionById. Log e before returning, and only use the timeout path when the error is actually an abort (e.g. e.name === 'AbortError'). Rethrow anything else.
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
|
|
||
| expect(result.isError).toBeFalsy(); | ||
| const { source, usage } = parse(result); | ||
| expect(source.columns).toHaveLength(COLUMNS.length); |
There was a problem hiding this comment.
🔵 minor — The new outcome span attribute has no test
The PR adds mcp.describe_source.outcome (complete/partial/timeout) as the way to measure the fix, but no test mocks @opentelemetry/api's trace.getActiveSpan. A wrong or missing outcome would still pass. Mock getActiveSpan the way src/mcp/__tests__/tracing.test.ts does, and assert the attribute value in the complete, abort-partial, backstop-partial and schema-timeout cases.
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
Why
clickstack_describe_sourcetimes out often in production, and successful calls run close to the 10s cap. Our server instructions tell agents to run describe_source before querying, so when it fails they fall back toclickstack_sql.Two problems:
max_execution_time30, request timeout 32s viaMCP_REQUEST_TIMEOUT).Promise.racerejected and threw away everything gathered so far, including the column schema. The existingskippedStagespartial-result logic never ran.What changed
DESCRIBE_TIMEOUT_MS10s → 30s.partial: trueandskippedStages.metricNamesinskippedStageswhen the abort lands before that stage (it was silently omitted).mcp.describe_source.outcome(complete/partial/timeout) so we can track the effect.Testing
describeSourceTimeout.test.ts(fake timers): complete path, abort mid-map-keys, abort mid-value-sampling, backstop when a call ignores the signal, and the column-schema-never-loads error.yarn ci:unitinpackages/api: 1080 passed.make dev-int FILE=src/mcp/__tests__/sources.int.test.ts: 55 passed.🤖 Generated with Claude Code