From 899c5d6cf95f1a4766f769fe18dd0d5af172b7e7 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 12:35:37 -0600 Subject: [PATCH 1/9] perf(mcp): speed up list_metrics and give metric discovery tools a 30s budget list_metrics timed out on 19% of production calls at its 10s cap. The per-kind query aggregated MetricUnit/MetricDescription across every point in the window, and kinds ran one after another. - Scan names only (MetricName + TimeUnix), then fetch unit/description for the returned page with LIMIT 1 BY + LIMIT so ClickHouse stops early. - Scan kinds in parallel; resolve once the page is decided and abort the rest. Kinds still running at the deadline are reported in partialFailure and finished kinds are returned. - Emit a cursor when a kind exactly fills the page and later kinds have names (previously the remaining kinds were dropped). - Raise list_metrics and describe_metric wall clocks to 30s to match the other MCP query tools, scaling per-query caps (break mode) to fit. Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/api/src/fixtures.ts | 2 + .../src/mcp/__tests__/listMetricsPage.test.ts | 146 ++++++++ .../api/src/mcp/__tests__/sources.int.test.ts | 59 ++++ .../src/mcp/tools/sources/describeMetric.ts | 8 +- .../api/src/mcp/tools/sources/listMetrics.ts | 316 +++++++++--------- .../src/mcp/tools/sources/listMetricsPage.ts | 292 ++++++++++++++++ 6 files changed, 655 insertions(+), 168 deletions(-) create mode 100644 packages/api/src/mcp/__tests__/listMetricsPage.test.ts create mode 100644 packages/api/src/mcp/tools/sources/listMetricsPage.ts diff --git a/packages/api/src/fixtures.ts b/packages/api/src/fixtures.ts index 414ac9eebf..4868ec8bbe 100644 --- a/packages/api/src/fixtures.ts +++ b/packages/api/src/fixtures.ts @@ -452,6 +452,8 @@ export const bulkInsertLogs = async ( export const bulkInsertMetricsGauge = async ( metrics: { MetricName: string; + MetricUnit?: string; + MetricDescription?: string; ResourceAttributes: Record; ScopeAttributes?: Record; Attributes?: Record; diff --git a/packages/api/src/mcp/__tests__/listMetricsPage.test.ts b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts new file mode 100644 index 0000000000..0b9a4e85eb --- /dev/null +++ b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts @@ -0,0 +1,146 @@ +import { + assembleMetricsPage, + KIND_TIMED_OUT_ERROR, + type KindScan, + scanKindsForPage, +} from '@/mcp/tools/sources/listMetricsPage'; +import type { DiscoverableMetricKind } from '@/mcp/tools/sources/metricKinds'; + +const ok = (...names: string[]): KindScan => ({ status: 'ok', names }); + +describe('assembleMetricsPage', () => { + const kinds: DiscoverableMetricKind[] = ['gauge', 'sum', 'histogram']; + + it('concatenates kinds in order when everything fits', () => { + const page = assembleMetricsPage( + kinds, + [ok('a'), ok('b', 'c'), ok()], + 10, + false, + ); + expect(page).toEqual({ + entries: [ + { name: 'a', kind: 'gauge' }, + { name: 'b', kind: 'sum' }, + { name: 'c', kind: 'sum' }, + ], + partialFailure: [], + }); + }); + + it('truncates the overflowing kind and points the cursor at its last kept name', () => { + const page = assembleMetricsPage( + kinds, + [ok('a'), ok('b', 'c', 'd'), { status: 'pending' }], + 2, + false, + ); + expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.next).toEqual({ kind: 'sum', lastName: 'b' }); + }); + + it('emits a cursor when an earlier kind exactly fills the page and a later kind has names', () => { + const page = assembleMetricsPage( + kinds, + [ok('a', 'b'), ok('c'), ok()], + 2, + false, + ); + expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.next).toEqual({ kind: 'gauge', lastName: 'b' }); + }); + + it('waits while a pending kind can still change the page', () => { + expect( + assembleMetricsPage( + kinds, + [ok('a'), { status: 'pending' }, ok('b')], + 10, + false, + ), + ).toBeNull(); + }); + + it('reports pending kinds as timed out when finalizing and keeps finished kinds', () => { + const page = assembleMetricsPage( + kinds, + [ok('a'), { status: 'pending' }, ok('b')], + 10, + true, + ); + expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.partialFailure).toEqual([ + { kind: 'sum', error: KIND_TIMED_OUT_ERROR }, + ]); + }); + + it('skips failed kinds and records them', () => { + const page = assembleMetricsPage( + kinds, + [{ status: 'error', error: 'boom' }, ok('a'), ok()], + 10, + false, + ); + expect(page?.entries).toEqual([{ name: 'a', kind: 'sum' }]); + expect(page?.partialFailure).toEqual([{ kind: 'gauge', error: 'boom' }]); + }); +}); + +describe('scanKindsForPage', () => { + const never = (_kind: DiscoverableMetricKind, signal: AbortSignal) => + new Promise((_, reject) => { + signal.addEventListener('abort', () => reject(new Error('aborted'))); + }); + + it('runs kinds in parallel', async () => { + const started: DiscoverableMetricKind[] = []; + const resolvers: Array<() => void> = []; + const pageP = scanKindsForPage({ + kinds: ['gauge', 'sum'], + limit: 10, + deadlineAt: Date.now() + 5_000, + signal: new AbortController().signal, + fetchNames: kind => { + started.push(kind); + return new Promise(resolve => resolvers.push(() => resolve([kind]))); + }, + }); + expect(started).toEqual(['gauge', 'sum']); + resolvers.forEach(r => r()); + expect((await pageP).entries.map(e => e.name)).toEqual(['gauge', 'sum']); + }); + + it('resolves and aborts later kinds once an earlier kind fills the page', async () => { + let sumSignal: AbortSignal | undefined; + const page = await scanKindsForPage({ + kinds: ['gauge', 'sum'], + limit: 1, + deadlineAt: Date.now() + 5_000, + signal: new AbortController().signal, + fetchNames: (kind, signal) => { + if (kind === 'gauge') return Promise.resolve(['a', 'b']); + sumSignal = signal; + return never(kind, signal); + }, + }); + expect(page.entries).toEqual([{ name: 'a', kind: 'gauge' }]); + expect(page.next).toEqual({ kind: 'gauge', lastName: 'a' }); + expect(page.partialFailure).toEqual([]); + expect(sumSignal?.aborted).toBe(true); + }); + + it('returns finished kinds and marks the rest timed out at the deadline', async () => { + const page = await scanKindsForPage({ + kinds: ['gauge', 'sum', 'histogram'], + limit: 10, + deadlineAt: Date.now() + 50, + signal: new AbortController().signal, + fetchNames: (kind, signal) => + kind === 'sum' ? never(kind, signal) : Promise.resolve([kind]), + }); + expect(page.entries.map(e => e.name)).toEqual(['gauge', 'histogram']); + expect(page.partialFailure).toEqual([ + { kind: 'sum', error: KIND_TIMED_OUT_ERROR }, + ]); + }); +}); diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts index cfe23e7f2f..c61a6615c7 100644 --- a/packages/api/src/mcp/__tests__/sources.int.test.ts +++ b/packages/api/src/mcp/__tests__/sources.int.test.ts @@ -895,6 +895,65 @@ describe('MCP Source Tools', () => { } }); + it('walks every kind across pages without repeating or dropping names', async () => { + const metricSource = await createMetricSource(); + await seedMetricNames(); + + const seen: string[] = []; + let cursor: string | undefined; + for (let page = 0; page < 10; page++) { + const result = await callTool(client, 'clickstack_list_metrics', { + sourceId: metricSource._id.toString(), + limit: 1, + ...(cursor && { cursor }), + }); + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + seen.push( + ...(output.metrics as { kind: string; name: string }[]).map( + m => `${m.kind}:${m.name}`, + ), + ); + cursor = output.nextCursor; + if (!cursor) break; + } + expect(seen).toEqual([ + 'gauge:system.cpu.utilization', + 'gauge:system.memory.usage', + 'sum:http.server.request.count', + 'histogram:http.server.request.duration', + ]); + }); + + it('returns unit and description for each listed metric', async () => { + const metricSource = await createMetricSource(); + await bulkInsertMetricsGauge([ + { + MetricName: 'system.cpu.utilization', + MetricUnit: '1', + MetricDescription: 'CPU utilization', + ResourceAttributes: { 'service.name': 'svc-a' }, + ServiceName: 'svc-a', + TimeUnix: new Date(), + Value: 0.42, + }, + ]); + + const result = await callTool(client, 'clickstack_list_metrics', { + sourceId: metricSource._id.toString(), + kind: 'gauge', + }); + const output = JSON.parse(getFirstText(result)); + expect(output.metrics).toEqual([ + { + name: 'system.cpu.utilization', + kind: 'gauge', + unit: '1', + description: 'CPU utilization', + }, + ]); + }); + it('rejects a malformed cursor with an actionable error', async () => { const metricSource = await createMetricSource(); const result = await callTool(client, 'clickstack_list_metrics', { diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index d42bc23f68..061f628069 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -25,7 +25,8 @@ import { } from './metricKinds'; const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; -const DESCRIBE_TIMEOUT_MS = 10_000; +// Matches the 30s cap the MCP query tools use. +const DESCRIBE_TIMEOUT_MS = 30_000; // Server-side safety nets for the attribute-keys discovery query. // Sample at most N rows that match (MetricName, time range), then @@ -34,7 +35,10 @@ const DESCRIBE_TIMEOUT_MS = 10_000; // wall-clock budget. 100k rows is plenty to surface every unique map // key on a healthy OTel metric. const METRIC_ATTR_KEYS_SAMPLE_SIZE = 100_000; -const METRIC_ATTR_KEYS_MAX_EXEC_SECONDS = 8; +// Attribute keys and value sampling run back to back, so each gets under half +// the wall-clock budget; with timeout_overflow_mode: 'break' both return +// partial results before DESCRIBE_TIMEOUT_MS fires. +const METRIC_ATTR_KEYS_MAX_EXEC_SECONDS = 14; // Max sampled values per attribute key (when sampleValues is true). const MAX_ATTR_VALUES = 10; diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 5ad4f60dea..d2764eab2a 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -1,10 +1,6 @@ -import { - chSql, - concatChSql, - tableExpr, -} from '@hyperdx/common-utils/dist/clickhouse'; import { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; +import { trace } from '@opentelemetry/api'; import { z } from 'zod'; import { ClickhouseClient } from '@/clickhouse'; @@ -18,6 +14,13 @@ import { encodeCursor as encodeCursorPayload, } from '@/utils/pagination'; +import { + fetchMetricNames, + fetchMetricUnitsAndDescriptions, + KIND_TIMED_OUT_ERROR, + type MetricEntry, + scanKindsForPage, +} from './listMetricsPage'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, @@ -27,12 +30,19 @@ const DEFAULT_LIMIT = 50; const MAX_LIMIT = 500; const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; -// Hard timeout for the entire list operation (ms). -const LIST_TIMEOUT_MS = 10_000; +// Wall-clock budget for the whole call, matching the 30s cap the MCP query +// tools use. +const LIST_TIMEOUT_MS = 30_000; + +// Time held back from the name scan for the unit/description lookup and +// response assembly. Kinds still scanning when it starts are reported as +// timed out and the kinds that finished are returned. +const ENRICH_RESERVE_MS = 4_000; -// Server-side ClickHouse execution cap per query. Matches the bounds -// used by describeMetric's fetchAttributeKeys / sampleAttributeValues. -const MAX_EXEC_SECONDS = 8; +// Per-query ClickHouse caps. Both use timeout_overflow_mode: 'break', so +// ClickHouse returns what it has read before the wall clock fires. +const NAMES_MAX_EXEC_SECONDS = 24; +const ENRICH_MAX_EXEC_SECONDS = 3; // ─── Cursor ────────────────────────────────────────────────────────────────── @@ -109,13 +119,6 @@ const listMetricsSchema = z.object({ // ─── Helpers ───────────────────────────────────────────────────────────────── -type MetricEntry = { - name: string; - kind: DiscoverableMetricKind; - unit?: string; - description?: string; -}; - function parseTimeRange( startTime?: string, endTime?: string, @@ -135,102 +138,6 @@ function parseTimeRange( return { startDate, endDate }; } -async function fetchMetricsForKind({ - clickhouseClient, - metadata, - kind, - databaseName, - tableName, - connectionId, - startDate, - endDate, - namePattern, - afterName, - limit, - signal, -}: { - clickhouseClient: ClickhouseClient; - metadata: ReturnType; - kind: DiscoverableMetricKind; - databaseName: string; - tableName: string; - connectionId: string; - startDate: Date; - endDate: Date; - namePattern: string | undefined; - afterName: string | undefined; - limit: number; - signal: AbortSignal; -}): Promise { - // Defensive column-presence check so we don't reference MetricUnit / - // MetricDescription on non-OTel-default schemas. - const columns = await metadata.getColumns({ - databaseName, - tableName, - connectionId, - }); - const columnNames = new Set(columns.map(c => c.name)); - const hasUnit = columnNames.has('MetricUnit'); - const hasDescription = columnNames.has('MetricDescription'); - - const projections = [ - chSql`MetricName`, - ...(hasUnit - ? [chSql`anyLast(${{ Identifier: 'MetricUnit' }}) AS MetricUnit`] - : []), - ...(hasDescription - ? [ - chSql`anyLast(${{ Identifier: 'MetricDescription' }}) AS MetricDescription`, - ] - : []), - ]; - - const whereParts = [ - chSql`TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }})`, - chSql`TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }})`, - ...(afterName !== undefined - ? [chSql`MetricName > ${{ String: afterName }}`] - : []), - ...(namePattern - ? [chSql`MetricName ILIKE ${{ String: namePattern }}`] - : []), - ]; - - const sql = chSql` - SELECT ${concatChSql(', ', projections)} - FROM ${tableExpr({ database: databaseName, table: tableName })} - WHERE ${concatChSql(' AND ', whereParts)} - GROUP BY MetricName - ORDER BY MetricName ASC - LIMIT ${{ Int32: limit }} - `; - - type Row = { - MetricName: string; - MetricUnit?: string; - MetricDescription?: string; - }; - - const response = await clickhouseClient.query<'JSON'>({ - query: sql.sql, - query_params: sql.params, - format: 'JSON', - connectionId, - clickhouse_settings: { - max_execution_time: MAX_EXEC_SECONDS, - timeout_overflow_mode: 'break', - }, - abort_signal: signal, - }); - const result = (await response.json()) as { data: Row[] }; - return result.data.map(row => { - const entry: MetricEntry = { name: row.MetricName, kind }; - if (row.MetricUnit) entry.unit = row.MetricUnit; - if (row.MetricDescription) entry.description = row.MetricDescription; - return entry; - }); -} - // ─── Tool registration ─────────────────────────────────────────────────────── export function registerListMetrics({ @@ -266,6 +173,7 @@ export function registerListMetrics({ const input: z.infer = listMetricsSchema.parse(rawInput); + const deadlineAt = Date.now() + LIST_TIMEOUT_MS; const controller = new AbortController(); let timeoutId: ReturnType | undefined; const timeoutPromise = new Promise((_, reject) => { @@ -277,7 +185,12 @@ export function registerListMetrics({ try { return await Promise.race([ - listMetricsImpl(teamId.toString(), input, controller.signal), + listMetricsImpl( + teamId.toString(), + input, + deadlineAt, + controller.signal, + ), timeoutPromise, ]); } catch (e) { @@ -299,9 +212,76 @@ export function registerListMetrics({ ); } +/** + * Attach unit and description to each entry. Best effort: on failure or + * timeout the names are still returned. + */ +async function enrichEntries({ + entries, + clickhouseClient, + metadata, + databaseName, + metricTables, + connectionId, + startDate, + endDate, + signal, +}: { + entries: MetricEntry[]; + clickhouseClient: ClickhouseClient; + metadata: ReturnType; + databaseName: string; + metricTables: Partial>; + connectionId: string; + startDate: Date; + endDate: Date; + signal: AbortSignal; +}): Promise { + const kinds = [...new Set(entries.map(e => e.kind))]; + const byKind = await Promise.all( + kinds.map(async kind => { + const tableName = metricTables[kind]!; + try { + // Skip MetricUnit / MetricDescription on non-OTel-default schemas. + const columns = await metadata.getColumns({ + databaseName, + tableName, + connectionId, + }); + const columnNames = new Set(columns.map(c => c.name)); + return await fetchMetricUnitsAndDescriptions({ + clickhouseClient, + databaseName, + tableName, + connectionId, + names: entries.filter(e => e.kind === kind).map(e => e.name), + startDate, + endDate, + hasUnit: columnNames.has('MetricUnit'), + hasDescription: columnNames.has('MetricDescription'), + maxExecutionSeconds: ENRICH_MAX_EXEC_SECONDS, + signal, + }); + } catch (e) { + logger.warn( + { kind, tableName, error: e instanceof Error ? e.message : e }, + 'Failed to fetch metric unit/description', + ); + return new Map(); + } + }), + ); + const enrichments = new Map(kinds.map((kind, i) => [kind, byKind[i]])); + return entries.map(entry => ({ + ...entry, + ...enrichments.get(entry.kind)?.get(entry.name), + })); +} + async function listMetricsImpl( teamId: string, input: z.infer, + deadlineAt: number, signal: AbortSignal, ) { const source = await getSource(teamId, input.sourceId); @@ -365,65 +345,69 @@ async function listMetricsImpl( const limit = input.limit ?? DEFAULT_LIMIT; const databaseName = source.from.databaseName; - const metrics: MetricEntry[] = []; - // Per-kind fetch failures, surfaced on the response so the agent - // can distinguish "kind genuinely has no metrics" from "the fetch - // for that kind failed" — the two need different recovery steps. - const partialFailure: { kind: string; error: string }[] = []; - let nextCursor: string | undefined; - for (let i = startKindIdx; i < requestedKinds.length; i++) { - const kind = requestedKinds[i]; - const tableName = source.metricTables[kind]; - if (!tableName) continue; - const afterName = - cursor && cursor.kind === kind && i === startKindIdx - ? cursor.lastName - : undefined; - const remaining = limit - metrics.length; - if (remaining <= 0) break; - // Fetch one extra row so we can detect more-data-available. - let kindMetrics: MetricEntry[]; - try { - kindMetrics = await fetchMetricsForKind({ + const connectionId = source.connection.toString(); + + // Kinds before the cursor's kind were already returned on earlier pages. + const scanKinds = requestedKinds + .slice(startKindIdx) + .filter(kind => Boolean(source.metricTables[kind])); + const page = await scanKindsForPage({ + kinds: scanKinds, + limit, + deadlineAt: deadlineAt - ENRICH_RESERVE_MS, + signal, + fetchNames: (kind, kindSignal) => + fetchMetricNames({ clickhouseClient, - metadata, - kind, databaseName, - tableName, - connectionId: source.connection.toString(), + tableName: source.metricTables[kind]!, + connectionId, startDate, endDate, namePattern: input.namePattern, - afterName, - limit: remaining + 1, - signal, - }); - } catch (e) { - const message = e instanceof Error ? e.message : String(e); - logger.warn( - { sourceId: input.sourceId, kind, error: message }, - 'Failed to list metrics for kind', - ); - partialFailure.push({ - kind, - error: message.replace(/\s+/g, ' ').trim().slice(0, 200), - }); - continue; - } - if (kindMetrics.length > remaining) { - // We hit the cap for this kind; emit cursor pointing at the - // last returned name and stop iterating further kinds. - const truncated = kindMetrics.slice(0, remaining); - metrics.push(...truncated); - nextCursor = encodeCursor({ - kind, - lastName: truncated[truncated.length - 1].name, - }); - break; - } - metrics.push(...kindMetrics); + afterName: kind === cursor?.kind ? cursor.lastName : undefined, + // One extra row detects that more names remain for this kind. + limit: limit + 1, + maxExecutionSeconds: NAMES_MAX_EXEC_SECONDS, + signal: kindSignal, + }), + }); + for (const failure of page.partialFailure) { + logger.warn( + { sourceId: input.sourceId, kind: failure.kind, error: failure.error }, + 'Failed to list metrics for kind', + ); } + const enrichSignal = AbortSignal.any([ + signal, + AbortSignal.timeout(Math.max(0, deadlineAt - Date.now() - 500)), + ]); + const metrics = await enrichEntries({ + entries: page.entries, + clickhouseClient, + metadata, + databaseName, + metricTables: source.metricTables, + connectionId, + startDate, + endDate, + signal: enrichSignal, + }); + + const nextCursor = page.next && encodeCursor(page.next); + // Per-kind failures are surfaced so the agent can tell "kind has no + // metrics" apart from "the fetch for that kind failed or timed out". + const partialFailure = page.partialFailure; + trace.getActiveSpan()?.setAttributes({ + 'mcp.list_metrics.kinds_scanned': scanKinds.length, + 'mcp.list_metrics.kinds_failed': partialFailure.length, + 'mcp.list_metrics.kinds_timed_out': partialFailure.filter( + f => f.error === KIND_TIMED_OUT_ERROR, + ).length, + 'mcp.list_metrics.result_count': metrics.length, + }); + const responseObj: Record = { metrics, ...(nextCursor && { nextCursor }), diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts new file mode 100644 index 0000000000..d3a381306a --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -0,0 +1,292 @@ +import { + chSql, + concatChSql, + tableExpr, +} from '@hyperdx/common-utils/dist/clickhouse'; + +import type { ClickhouseClient } from '@/clickhouse'; + +import type { DiscoverableMetricKind } from './metricKinds'; + +export type MetricEntry = { + name: string; + kind: DiscoverableMetricKind; + unit?: string; + description?: string; +}; + +export type KindScan = + | { status: 'pending' } + | { status: 'ok'; names: string[] } + | { status: 'error'; error: string }; + +export type MetricsPage = { + entries: MetricEntry[]; + /** Kind + last name of a truncated kind; absent when the scan is exhausted. */ + next?: { kind: DiscoverableMetricKind; lastName: string }; + partialFailure: { kind: DiscoverableMetricKind; error: string }[]; +}; + +export const KIND_TIMED_OUT_ERROR = + 'Timed out before this kind finished listing.'; + +/** + * Build a page from per-kind scan results, filling `limit` entries in kind + * order. Each scan holds up to `limit + 1` names so an overflow can be + * detected. Returns null when a pending kind still decides the page's + * contents, unless `finalize` is set, in which case pending kinds are + * reported as timed out. + * + * @internal Exported for testing. + */ +export function assembleMetricsPage( + kinds: DiscoverableMetricKind[], + scans: KindScan[], + limit: number, + finalize: boolean, +): MetricsPage | null { + const entries: MetricEntry[] = []; + const partialFailure: MetricsPage['partialFailure'] = []; + for (let i = 0; i < kinds.length; i++) { + const kind = kinds[i]; + const scan = scans[i]; + if (scan.status === 'pending') { + if (!finalize) return null; + partialFailure.push({ kind, error: KIND_TIMED_OUT_ERROR }); + continue; + } + if (scan.status === 'error') { + partialFailure.push({ kind, error: scan.error }); + continue; + } + const remaining = limit - entries.length; + if (scan.names.length > remaining) { + entries.push( + ...scan.names.slice(0, remaining).map(name => ({ name, kind })), + ); + // When an earlier kind exactly filled the page, the cursor points at + // that kind's last name so the next call moves on to this kind. + const last = entries[entries.length - 1]; + return { + entries, + next: { kind: last.kind, lastName: last.name }, + partialFailure, + }; + } + entries.push(...scan.names.map(name => ({ name, kind }))); + } + return { entries, partialFailure }; +} + +/** + * Scan every kind in parallel and resolve as soon as the page is decided: + * once the kinds in front of an overflowing kind have all settled, later + * kinds cannot contribute and their queries are aborted. Kinds still running + * at `deadlineAt` are reported as timed out so the kinds that finished are + * returned instead of failing the whole call. + */ +export function scanKindsForPage({ + kinds, + limit, + deadlineAt, + signal, + fetchNames, +}: { + kinds: DiscoverableMetricKind[]; + limit: number; + deadlineAt: number; + signal: AbortSignal; + fetchNames: ( + kind: DiscoverableMetricKind, + signal: AbortSignal, + ) => Promise; +}): Promise { + const scans: KindScan[] = kinds.map(() => ({ status: 'pending' })); + const controller = new AbortController(); + const abort = () => controller.abort(); + signal.addEventListener('abort', abort, { once: true }); + + return new Promise(resolve => { + let done = false; + const tryFinish = (finalize: boolean) => { + if (done) return; + const page = assembleMetricsPage(kinds, scans, limit, finalize); + if (!page) return; + done = true; + clearTimeout(timer); + signal.removeEventListener('abort', abort); + controller.abort(); + resolve(page); + }; + const timer = setTimeout( + () => tryFinish(true), + Math.max(0, deadlineAt - Date.now()), + ); + kinds.forEach((kind, i) => { + fetchNames(kind, controller.signal) + .then( + names => { + scans[i] = { status: 'ok', names }; + }, + (e: unknown) => { + if (done) return; + const message = e instanceof Error ? e.message : String(e); + scans[i] = { + status: 'error', + error: message.replace(/\s+/g, ' ').trim().slice(0, 200), + }; + }, + ) + .finally(() => tryFinish(false)); + }); + }); +} + +/** + * Distinct metric names for one kind. Reads only MetricName and TimeUnix; + * unit and description are fetched separately for the returned page, since + * aggregating those String columns across the whole window was the bulk of + * the bytes read. + */ +export async function fetchMetricNames({ + clickhouseClient, + databaseName, + tableName, + connectionId, + startDate, + endDate, + namePattern, + afterName, + limit, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: ClickhouseClient; + databaseName: string; + tableName: string; + connectionId: string; + startDate: Date; + endDate: Date; + namePattern: string | undefined; + afterName: string | undefined; + limit: number; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise { + const whereParts = [ + chSql`TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }})`, + chSql`TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }})`, + ...(afterName !== undefined + ? [chSql`MetricName > ${{ String: afterName }}`] + : []), + ...(namePattern + ? [chSql`MetricName ILIKE ${{ String: namePattern }}`] + : []), + ]; + + const sql = chSql` + SELECT MetricName + FROM ${tableExpr({ database: databaseName, table: tableName })} + WHERE ${concatChSql(' AND ', whereParts)} + GROUP BY MetricName + ORDER BY MetricName ASC + LIMIT ${{ Int32: limit }} + `; + + const response = await clickhouseClient.query<'JSON'>({ + query: sql.sql, + query_params: sql.params, + format: 'JSON', + connectionId, + clickhouse_settings: { + max_execution_time: maxExecutionSeconds, + timeout_overflow_mode: 'break', + }, + abort_signal: signal, + }); + const result = (await response.json()) as { data: { MetricName: string }[] }; + return result.data.map(row => row.MetricName); +} + +/** + * Unit and description for a page of metric names. `LIMIT 1 BY` plus the + * outer LIMIT lets ClickHouse stop reading once every name has a row, instead + * of aggregating every point in the window. The row picked is arbitrary, which + * matches the `anyLast` this replaced; unit and description are effectively + * constant per metric. + */ +export async function fetchMetricUnitsAndDescriptions({ + clickhouseClient, + databaseName, + tableName, + connectionId, + names, + startDate, + endDate, + hasUnit, + hasDescription, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: ClickhouseClient; + databaseName: string; + tableName: string; + connectionId: string; + names: string[]; + startDate: Date; + endDate: Date; + hasUnit: boolean; + hasDescription: boolean; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise> { + const enrichments = new Map< + string, + { unit?: string; description?: string } + >(); + if (names.length === 0 || (!hasUnit && !hasDescription)) return enrichments; + + const projections = [ + chSql`MetricName`, + ...(hasUnit ? [chSql`${{ Identifier: 'MetricUnit' }}`] : []), + ...(hasDescription ? [chSql`${{ Identifier: 'MetricDescription' }}`] : []), + ]; + const sql = chSql` + SELECT ${concatChSql(', ', projections)} + FROM ${tableExpr({ database: databaseName, table: tableName })} + WHERE MetricName IN (${concatChSql( + ',', + names.map(name => chSql`${{ String: name }}`), + )}) + AND TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }}) + AND TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }}) + LIMIT 1 BY MetricName + LIMIT ${{ Int32: names.length }} + `; + + const response = await clickhouseClient.query<'JSON'>({ + query: sql.sql, + query_params: sql.params, + format: 'JSON', + connectionId, + clickhouse_settings: { + max_execution_time: maxExecutionSeconds, + timeout_overflow_mode: 'break', + }, + abort_signal: signal, + }); + const result = (await response.json()) as { + data: { + MetricName: string; + MetricUnit?: string; + MetricDescription?: string; + }[]; + }; + for (const row of result.data) { + enrichments.set(row.MetricName, { + ...(row.MetricUnit ? { unit: row.MetricUnit } : {}), + ...(row.MetricDescription ? { description: row.MetricDescription } : {}), + }); + } + return enrichments; +} From c6bbf106109eeb2ee08393713d5a9a36136be329 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 13:52:27 -0600 Subject: [PATCH 2/9] fix(mcp): keep list_metrics cursors complete around timeouts and full pages - End the page at a timed-out kind and resume the cursor there (greptile P1) - Return a full page immediately with a cursor to the next non-empty kind (greptile P1) - Race unit/description enrichment, including getColumns, against the deadline (greptile P1) - Inline page names as escaped literals instead of one bind param each (greptile P2) - Resolve immediately when there are no kinds to scan (deep-review P0) - Bring api lint warnings back under the ceiling; add changeset --- .changeset/mcp-list-metrics-speedup.md | 15 +++ .../mcp/__tests__/listMetricsCursor.test.ts | 6 +- .../src/mcp/__tests__/listMetricsPage.test.ts | 94 ++++++++++------ .../api/src/mcp/__tests__/sources.int.test.ts | 11 +- .../api/src/mcp/tools/sources/listMetrics.ts | 48 +++++--- .../src/mcp/tools/sources/listMetricsPage.ts | 105 +++++++++++------- 6 files changed, 181 insertions(+), 98 deletions(-) create mode 100644 .changeset/mcp-list-metrics-speedup.md diff --git a/.changeset/mcp-list-metrics-speedup.md b/.changeset/mcp-list-metrics-speedup.md new file mode 100644 index 0000000000..9305698e18 --- /dev/null +++ b/.changeset/mcp-list-metrics-speedup.md @@ -0,0 +1,15 @@ +--- +'@hyperdx/api': patch +--- + +perf(mcp): speed up `clickstack_list_metrics` and give the metric discovery +tools a 30s budget + +`clickstack_list_metrics` now scans metric names only (about 9x fewer bytes read +per kind), fetches unit and description just for the returned page, and scans +kinds in parallel. When the time budget runs out it returns the kinds that +finished, reports the rest in `partialFailure`, and returns a `nextCursor` that +resumes at the timed-out kind instead of failing the whole call. It also no +longer drops later kinds when one kind exactly fills a page. +`clickstack_list_metrics` and `clickstack_describe_metric` now allow 30s instead +of 10s, matching the other MCP query tools. diff --git a/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts b/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts index 6cb4fbe105..8c1f182eb5 100644 --- a/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts +++ b/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts @@ -77,11 +77,11 @@ describe('listMetrics cursor', () => { expect(decodeCursor(malformed)).toBeNull(); }); - it('returns null when lastName is missing', () => { - const malformed = Buffer.from(JSON.stringify({ kind: 'gauge' })).toString( + it('accepts a cursor without lastName as the start of that kind', () => { + const raw = Buffer.from(JSON.stringify({ kind: 'gauge' })).toString( 'base64', ); - expect(decodeCursor(malformed)).toBeNull(); + expect(decodeCursor(raw)).toEqual({ kind: 'gauge' }); }); it('returns null when kind is not a discoverable metric kind', () => { diff --git a/packages/api/src/mcp/__tests__/listMetricsPage.test.ts b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts index 0b9a4e85eb..c974d486ae 100644 --- a/packages/api/src/mcp/__tests__/listMetricsPage.test.ts +++ b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts @@ -2,19 +2,23 @@ import { assembleMetricsPage, KIND_TIMED_OUT_ERROR, type KindScan, + type KindSlot, scanKindsForPage, } from '@/mcp/tools/sources/listMetricsPage'; import type { DiscoverableMetricKind } from '@/mcp/tools/sources/metricKinds'; const ok = (...names: string[]): KindScan => ({ status: 'ok', names }); +const pending: KindScan = { status: 'pending' }; -describe('assembleMetricsPage', () => { +const slots = (...scans: KindScan[]): KindSlot[] => { const kinds: DiscoverableMetricKind[] = ['gauge', 'sum', 'histogram']; + return scans.map((scan, i) => ({ kind: kinds.at(i)!, scan })); +}; +describe('assembleMetricsPage', () => { it('concatenates kinds in order when everything fits', () => { const page = assembleMetricsPage( - kinds, - [ok('a'), ok('b', 'c'), ok()], + slots(ok('a'), ok('b', 'c'), ok()), 10, false, ); @@ -30,8 +34,7 @@ describe('assembleMetricsPage', () => { it('truncates the overflowing kind and points the cursor at its last kept name', () => { const page = assembleMetricsPage( - kinds, - [ok('a'), ok('b', 'c', 'd'), { status: 'pending' }], + slots(ok('a'), ok('b', 'c', 'd'), pending), 2, false, ); @@ -39,45 +42,60 @@ describe('assembleMetricsPage', () => { expect(page?.next).toEqual({ kind: 'sum', lastName: 'b' }); }); - it('emits a cursor when an earlier kind exactly fills the page and a later kind has names', () => { + it('points the cursor at the next kind with names when an earlier kind exactly fills the page', () => { const page = assembleMetricsPage( - kinds, - [ok('a', 'b'), ok('c'), ok()], + slots(ok('a', 'b'), ok(), ok('c')), 2, false, ); expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); - expect(page?.next).toEqual({ kind: 'gauge', lastName: 'b' }); + expect(page?.next).toEqual({ kind: 'histogram' }); + }); + + it('returns a full page without waiting for later kinds', () => { + const page = assembleMetricsPage(slots(ok('a', 'b'), pending), 2, false); + expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.next).toEqual({ kind: 'sum' }); + expect(page?.partialFailure).toEqual([]); + }); + + it('emits no cursor when the page is full and later kinds are empty', () => { + const page = assembleMetricsPage(slots(ok('a', 'b'), ok(), ok()), 2, false); + expect(page?.next).toBeUndefined(); }); it('waits while a pending kind can still change the page', () => { expect( - assembleMetricsPage( - kinds, - [ok('a'), { status: 'pending' }, ok('b')], - 10, - false, - ), + assembleMetricsPage(slots(ok('a'), pending, ok('b')), 10, false), ).toBeNull(); }); - it('reports pending kinds as timed out when finalizing and keeps finished kinds', () => { + it('ends the page at a timed-out kind and resumes the cursor there', () => { const page = assembleMetricsPage( - kinds, - [ok('a'), { status: 'pending' }, ok('b')], + slots(ok('a'), pending, ok('b')), 10, true, ); - expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.entries.map(e => e.name)).toEqual(['a']); + expect(page?.next).toEqual({ kind: 'sum' }); expect(page?.partialFailure).toEqual([ { kind: 'sum', error: KIND_TIMED_OUT_ERROR }, ]); }); + it("resumes a timed-out cursor kind from the cursor's position", () => { + const page = assembleMetricsPage( + [{ kind: 'sum', afterName: 'm', scan: pending }], + 10, + true, + ); + expect(page?.entries).toEqual([]); + expect(page?.next).toEqual({ kind: 'sum', lastName: 'm' }); + }); + it('skips failed kinds and records them', () => { const page = assembleMetricsPage( - kinds, - [{ status: 'error', error: 'boom' }, ok('a'), ok()], + slots({ status: 'error', error: 'boom' }, ok('a'), ok()), 10, false, ); @@ -87,7 +105,7 @@ describe('assembleMetricsPage', () => { }); describe('scanKindsForPage', () => { - const never = (_kind: DiscoverableMetricKind, signal: AbortSignal) => + const never = (signal: AbortSignal) => new Promise((_, reject) => { signal.addEventListener('abort', () => reject(new Error('aborted'))); }); @@ -96,11 +114,11 @@ describe('scanKindsForPage', () => { const started: DiscoverableMetricKind[] = []; const resolvers: Array<() => void> = []; const pageP = scanKindsForPage({ - kinds: ['gauge', 'sum'], + kinds: [{ kind: 'gauge' }, { kind: 'sum' }], limit: 10, deadlineAt: Date.now() + 5_000, signal: new AbortController().signal, - fetchNames: kind => { + fetchNames: ({ kind }) => { started.push(kind); return new Promise(resolve => resolvers.push(() => resolve([kind]))); }, @@ -113,14 +131,14 @@ describe('scanKindsForPage', () => { it('resolves and aborts later kinds once an earlier kind fills the page', async () => { let sumSignal: AbortSignal | undefined; const page = await scanKindsForPage({ - kinds: ['gauge', 'sum'], + kinds: [{ kind: 'gauge' }, { kind: 'sum' }], limit: 1, deadlineAt: Date.now() + 5_000, signal: new AbortController().signal, - fetchNames: (kind, signal) => { + fetchNames: ({ kind }, signal) => { if (kind === 'gauge') return Promise.resolve(['a', 'b']); sumSignal = signal; - return never(kind, signal); + return never(signal); }, }); expect(page.entries).toEqual([{ name: 'a', kind: 'gauge' }]); @@ -129,16 +147,28 @@ describe('scanKindsForPage', () => { expect(sumSignal?.aborted).toBe(true); }); - it('returns finished kinds and marks the rest timed out at the deadline', async () => { + it('resolves immediately when there are no kinds to scan', async () => { + const page = await scanKindsForPage({ + kinds: [], + limit: 10, + deadlineAt: Date.now() + 60_000, + signal: new AbortController().signal, + fetchNames: () => Promise.resolve([]), + }); + expect(page).toEqual({ entries: [], partialFailure: [] }); + }); + + it('returns kinds before a timed-out kind and resumes at it', async () => { const page = await scanKindsForPage({ - kinds: ['gauge', 'sum', 'histogram'], + kinds: [{ kind: 'gauge' }, { kind: 'sum' }, { kind: 'histogram' }], limit: 10, deadlineAt: Date.now() + 50, signal: new AbortController().signal, - fetchNames: (kind, signal) => - kind === 'sum' ? never(kind, signal) : Promise.resolve([kind]), + fetchNames: ({ kind }, signal) => + kind === 'sum' ? never(signal) : Promise.resolve([kind]), }); - expect(page.entries.map(e => e.name)).toEqual(['gauge', 'histogram']); + expect(page.entries.map(e => e.name)).toEqual(['gauge']); + expect(page.next).toEqual({ kind: 'sum' }); expect(page.partialFailure).toEqual([ { kind: 'sum', error: KIND_TIMED_OUT_ERROR }, ]); diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts index c61a6615c7..7e86e7c3a5 100644 --- a/packages/api/src/mcp/__tests__/sources.int.test.ts +++ b/packages/api/src/mcp/__tests__/sources.int.test.ts @@ -908,12 +908,11 @@ describe('MCP Source Tools', () => { ...(cursor && { cursor }), }); expect(result.isError).toBeFalsy(); - const output = JSON.parse(getFirstText(result)); - seen.push( - ...(output.metrics as { kind: string; name: string }[]).map( - m => `${m.kind}:${m.name}`, - ), - ); + const output: { + metrics: { kind: string; name: string }[]; + nextCursor?: string; + } = JSON.parse(getFirstText(result)); + seen.push(...output.metrics.map(m => `${m.kind}:${m.name}`)); cursor = output.nextCursor; if (!cursor) break; } diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index d2764eab2a..6916a154ec 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -48,7 +48,8 @@ const ENRICH_MAX_EXEC_SECONDS = 3; const cursorPayloadSchema = z.object({ kind: z.enum(DISCOVERABLE_METRIC_KINDS), - lastName: z.string(), + // Absent when the next page starts at the beginning of `kind`. + lastName: z.string().optional(), }); export type ListMetricsCursorPayload = z.infer; @@ -212,6 +213,8 @@ export function registerListMetrics({ ); } +type Enrichments = Awaited>; + /** * Attach unit and description to each entry. Best effort: on failure or * timeout the names are still returned. @@ -238,8 +241,15 @@ async function enrichEntries({ signal: AbortSignal; }): Promise { const kinds = [...new Set(entries.map(e => e.kind))]; - const byKind = await Promise.all( - kinds.map(async kind => { + // metadata.getColumns takes no abort signal, so race the whole lookup + // against it; otherwise a slow schema lookup could outlast the call's + // wall clock and discard the names already collected. + const aborted = new Promise(resolve => { + if (signal.aborted) resolve(undefined); + signal.addEventListener('abort', () => resolve(undefined), { once: true }); + }); + const lookups = Promise.all( + kinds.map(async (kind): Promise<[DiscoverableMetricKind, Enrichments]> => { const tableName = metricTables[kind]!; try { // Skip MetricUnit / MetricDescription on non-OTel-default schemas. @@ -249,7 +259,7 @@ async function enrichEntries({ connectionId, }); const columnNames = new Set(columns.map(c => c.name)); - return await fetchMetricUnitsAndDescriptions({ + const enrichments = await fetchMetricUnitsAndDescriptions({ clickhouseClient, databaseName, tableName, @@ -262,16 +272,25 @@ async function enrichEntries({ maxExecutionSeconds: ENRICH_MAX_EXEC_SECONDS, signal, }); + return [kind, enrichments]; } catch (e) { logger.warn( { kind, tableName, error: e instanceof Error ? e.message : e }, 'Failed to fetch metric unit/description', ); - return new Map(); + return [kind, new Map()]; } }), ); - const enrichments = new Map(kinds.map((kind, i) => [kind, byKind[i]])); + const byKind = await Promise.race([lookups, aborted]); + if (!byKind) { + logger.warn( + { kinds }, + 'Timed out fetching metric unit/description; returning names only', + ); + return entries; + } + const enrichments = new Map(byKind); return entries.map(entry => ({ ...entry, ...enrichments.get(entry.kind)?.get(entry.name), @@ -314,9 +333,9 @@ async function listMetricsImpl( // Resolve which kinds to scan, in order. When a cursor is set, // skip kinds before the cursor's kind (already returned) and start // the cursor's kind at the lastName-exclusive position. - const requestedKinds: DiscoverableMetricKind[] = input.kind - ? [input.kind] - : DISCOVERABLE_METRIC_KINDS.filter(k => Boolean(source.metricTables[k])); + const requestedKinds: DiscoverableMetricKind[] = ( + input.kind ? [input.kind] : DISCOVERABLE_METRIC_KINDS + ).filter(k => Boolean(source.metricTables[k])); const startKindIdx = cursor ? requestedKinds.indexOf(cursor.kind) : 0; if (startKindIdx < 0) { // Cursor points at a kind that's not in scope for this call — @@ -348,15 +367,16 @@ async function listMetricsImpl( const connectionId = source.connection.toString(); // Kinds before the cursor's kind were already returned on earlier pages. - const scanKinds = requestedKinds - .slice(startKindIdx) - .filter(kind => Boolean(source.metricTables[kind])); + const scanKinds = requestedKinds.slice(startKindIdx).map((kind, i) => ({ + kind, + afterName: i === 0 ? cursor?.lastName : undefined, + })); const page = await scanKindsForPage({ kinds: scanKinds, limit, deadlineAt: deadlineAt - ENRICH_RESERVE_MS, signal, - fetchNames: (kind, kindSignal) => + fetchNames: ({ kind, afterName }, kindSignal) => fetchMetricNames({ clickhouseClient, databaseName, @@ -365,7 +385,7 @@ async function listMetricsImpl( startDate, endDate, namePattern: input.namePattern, - afterName: kind === cursor?.kind ? cursor.lastName : undefined, + afterName, // One extra row detects that more names remain for this kind. limit: limit + 1, maxExecutionSeconds: NAMES_MAX_EXEC_SECONDS, diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts index d3a381306a..c53f60642d 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsPage.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -3,6 +3,7 @@ import { concatChSql, tableExpr, } from '@hyperdx/common-utils/dist/clickhouse'; +import SqlString from 'sqlstring'; import type { ClickhouseClient } from '@/clickhouse'; @@ -20,10 +21,21 @@ export type KindScan = | { status: 'ok'; names: string[] } | { status: 'error'; error: string }; +export type KindToScan = { + kind: DiscoverableMetricKind; + /** Exclusive start within this kind; set only for the cursor's kind. */ + afterName?: string; +}; + +export type KindSlot = KindToScan & { scan: KindScan }; + export type MetricsPage = { entries: MetricEntry[]; - /** Kind + last name of a truncated kind; absent when the scan is exhausted. */ - next?: { kind: DiscoverableMetricKind; lastName: string }; + /** + * Where the next page starts. `lastName` is absent when the next page + * starts at the beginning of `kind`. Absent when the scan is exhausted. + */ + next?: { kind: DiscoverableMetricKind; lastName?: string }; partialFailure: { kind: DiscoverableMetricKind; error: string }[]; }; @@ -34,56 +46,59 @@ export const KIND_TIMED_OUT_ERROR = * Build a page from per-kind scan results, filling `limit` entries in kind * order. Each scan holds up to `limit + 1` names so an overflow can be * detected. Returns null when a pending kind still decides the page's - * contents, unless `finalize` is set, in which case pending kinds are - * reported as timed out. + * contents, unless `finalize` is set, in which case the first pending kind + * is reported as timed out and the page ends there. * * @internal Exported for testing. */ export function assembleMetricsPage( - kinds: DiscoverableMetricKind[], - scans: KindScan[], + slots: KindSlot[], limit: number, finalize: boolean, ): MetricsPage | null { const entries: MetricEntry[] = []; const partialFailure: MetricsPage['partialFailure'] = []; - for (let i = 0; i < kinds.length; i++) { - const kind = kinds[i]; - const scan = scans[i]; + const resumeAt = (slot: KindToScan): MetricsPage => ({ + entries, + next: { kind: slot.kind, lastName: slot.afterName }, + partialFailure, + }); + for (const [i, slot] of slots.entries()) { + const { kind, scan } = slot; if (scan.status === 'pending') { if (!finalize) return null; + // End the page at the timed-out kind so the cursor resumes there. + // Moving on to later kinds would leave its names unreachable. partialFailure.push({ kind, error: KIND_TIMED_OUT_ERROR }); - continue; + return resumeAt(slot); } if (scan.status === 'error') { partialFailure.push({ kind, error: scan.error }); continue; } const remaining = limit - entries.length; + const kept = scan.names.slice(0, remaining); + entries.push(...kept.map(name => ({ name, kind }))); if (scan.names.length > remaining) { - entries.push( - ...scan.names.slice(0, remaining).map(name => ({ name, kind })), - ); - // When an earlier kind exactly filled the page, the cursor points at - // that kind's last name so the next call moves on to this kind. - const last = entries[entries.length - 1]; - return { - entries, - next: { kind: last.kind, lastName: last.name }, - partialFailure, - }; + return { entries, next: { kind, lastName: kept.at(-1) }, partialFailure }; + } + if (entries.length === limit) { + // The page is full. Point the cursor at the next kind that may still + // have names instead of waiting for it to finish. + const nextSlot = slots + .slice(i + 1) + .find(s => s.scan.status !== 'ok' || s.scan.names.length > 0); + return nextSlot ? resumeAt(nextSlot) : { entries, partialFailure }; } - entries.push(...scan.names.map(name => ({ name, kind }))); } return { entries, partialFailure }; } /** - * Scan every kind in parallel and resolve as soon as the page is decided: - * once the kinds in front of an overflowing kind have all settled, later - * kinds cannot contribute and their queries are aborted. Kinds still running - * at `deadlineAt` are reported as timed out so the kinds that finished are - * returned instead of failing the whole call. + * Scan every kind in parallel and resolve as soon as the page is decided. + * Queries for kinds that can no longer contribute are aborted. Kinds still + * running at `deadlineAt` are reported as timed out so the kinds that + * finished are returned instead of failing the whole call. */ export function scanKindsForPage({ kinds, @@ -92,16 +107,16 @@ export function scanKindsForPage({ signal, fetchNames, }: { - kinds: DiscoverableMetricKind[]; + kinds: KindToScan[]; limit: number; deadlineAt: number; signal: AbortSignal; - fetchNames: ( - kind: DiscoverableMetricKind, - signal: AbortSignal, - ) => Promise; + fetchNames: (kind: KindToScan, signal: AbortSignal) => Promise; }): Promise { - const scans: KindScan[] = kinds.map(() => ({ status: 'pending' })); + const slots: KindSlot[] = kinds.map(k => ({ + ...k, + scan: { status: 'pending' }, + })); const controller = new AbortController(); const abort = () => controller.abort(); signal.addEventListener('abort', abort, { once: true }); @@ -110,7 +125,7 @@ export function scanKindsForPage({ let done = false; const tryFinish = (finalize: boolean) => { if (done) return; - const page = assembleMetricsPage(kinds, scans, limit, finalize); + const page = assembleMetricsPage(slots, limit, finalize); if (!page) return; done = true; clearTimeout(timer); @@ -122,23 +137,25 @@ export function scanKindsForPage({ () => tryFinish(true), Math.max(0, deadlineAt - Date.now()), ); - kinds.forEach((kind, i) => { - fetchNames(kind, controller.signal) + for (const slot of slots) { + fetchNames(slot, controller.signal) .then( names => { - scans[i] = { status: 'ok', names }; + slot.scan = { status: 'ok', names }; }, (e: unknown) => { if (done) return; const message = e instanceof Error ? e.message : String(e); - scans[i] = { + slot.scan = { status: 'error', error: message.replace(/\s+/g, ' ').trim().slice(0, 200), }; }, ) .finally(() => tryFinish(false)); - }); + } + // Resolves right away when there are no kinds to scan. + tryFinish(false); }); } @@ -254,10 +271,12 @@ export async function fetchMetricUnitsAndDescriptions({ const sql = chSql` SELECT ${concatChSql(', ', projections)} FROM ${tableExpr({ database: databaseName, table: tableName })} - WHERE MetricName IN (${concatChSql( - ',', - names.map(name => chSql`${{ String: name }}`), - )}) + WHERE MetricName IN (${{ + // Inline names as escaped literals: one bind param per name (up to + // 500) pushes the client into a multipart request that query proxies + // can reject. + UNSAFE_RAW_SQL: names.map(name => SqlString.escape(name)).join(','), + }}) AND TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }}) AND TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }}) LIMIT 1 BY MetricName From 2a4b13a2986b191ffb77afe61c9c70fdb625fe0f Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 16:01:10 -0600 Subject: [PATCH 3/9] refactor(mcp): split list_metrics query helpers out of listMetricsPage Keeps listMetricsPage.ts under the 300-line limit (greptile P2) and shares one ClickHouse query helper between the name scan and enrichment queries, removing the duplicated block jscpd flagged. --- .../api/src/mcp/tools/sources/listMetrics.ts | 6 +- .../src/mcp/tools/sources/listMetricsPage.ts | 160 ---------------- .../mcp/tools/sources/listMetricsQueries.ts | 172 ++++++++++++++++++ 3 files changed, 176 insertions(+), 162 deletions(-) create mode 100644 packages/api/src/mcp/tools/sources/listMetricsQueries.ts diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 6916a154ec..53d091e10f 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -15,12 +15,14 @@ import { } from '@/utils/pagination'; import { - fetchMetricNames, - fetchMetricUnitsAndDescriptions, KIND_TIMED_OUT_ERROR, type MetricEntry, scanKindsForPage, } from './listMetricsPage'; +import { + fetchMetricNames, + fetchMetricUnitsAndDescriptions, +} from './listMetricsQueries'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts index c53f60642d..603d2fc20d 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsPage.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -1,12 +1,3 @@ -import { - chSql, - concatChSql, - tableExpr, -} from '@hyperdx/common-utils/dist/clickhouse'; -import SqlString from 'sqlstring'; - -import type { ClickhouseClient } from '@/clickhouse'; - import type { DiscoverableMetricKind } from './metricKinds'; export type MetricEntry = { @@ -158,154 +149,3 @@ export function scanKindsForPage({ tryFinish(false); }); } - -/** - * Distinct metric names for one kind. Reads only MetricName and TimeUnix; - * unit and description are fetched separately for the returned page, since - * aggregating those String columns across the whole window was the bulk of - * the bytes read. - */ -export async function fetchMetricNames({ - clickhouseClient, - databaseName, - tableName, - connectionId, - startDate, - endDate, - namePattern, - afterName, - limit, - maxExecutionSeconds, - signal, -}: { - clickhouseClient: ClickhouseClient; - databaseName: string; - tableName: string; - connectionId: string; - startDate: Date; - endDate: Date; - namePattern: string | undefined; - afterName: string | undefined; - limit: number; - maxExecutionSeconds: number; - signal: AbortSignal; -}): Promise { - const whereParts = [ - chSql`TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }})`, - chSql`TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }})`, - ...(afterName !== undefined - ? [chSql`MetricName > ${{ String: afterName }}`] - : []), - ...(namePattern - ? [chSql`MetricName ILIKE ${{ String: namePattern }}`] - : []), - ]; - - const sql = chSql` - SELECT MetricName - FROM ${tableExpr({ database: databaseName, table: tableName })} - WHERE ${concatChSql(' AND ', whereParts)} - GROUP BY MetricName - ORDER BY MetricName ASC - LIMIT ${{ Int32: limit }} - `; - - const response = await clickhouseClient.query<'JSON'>({ - query: sql.sql, - query_params: sql.params, - format: 'JSON', - connectionId, - clickhouse_settings: { - max_execution_time: maxExecutionSeconds, - timeout_overflow_mode: 'break', - }, - abort_signal: signal, - }); - const result = (await response.json()) as { data: { MetricName: string }[] }; - return result.data.map(row => row.MetricName); -} - -/** - * Unit and description for a page of metric names. `LIMIT 1 BY` plus the - * outer LIMIT lets ClickHouse stop reading once every name has a row, instead - * of aggregating every point in the window. The row picked is arbitrary, which - * matches the `anyLast` this replaced; unit and description are effectively - * constant per metric. - */ -export async function fetchMetricUnitsAndDescriptions({ - clickhouseClient, - databaseName, - tableName, - connectionId, - names, - startDate, - endDate, - hasUnit, - hasDescription, - maxExecutionSeconds, - signal, -}: { - clickhouseClient: ClickhouseClient; - databaseName: string; - tableName: string; - connectionId: string; - names: string[]; - startDate: Date; - endDate: Date; - hasUnit: boolean; - hasDescription: boolean; - maxExecutionSeconds: number; - signal: AbortSignal; -}): Promise> { - const enrichments = new Map< - string, - { unit?: string; description?: string } - >(); - if (names.length === 0 || (!hasUnit && !hasDescription)) return enrichments; - - const projections = [ - chSql`MetricName`, - ...(hasUnit ? [chSql`${{ Identifier: 'MetricUnit' }}`] : []), - ...(hasDescription ? [chSql`${{ Identifier: 'MetricDescription' }}`] : []), - ]; - const sql = chSql` - SELECT ${concatChSql(', ', projections)} - FROM ${tableExpr({ database: databaseName, table: tableName })} - WHERE MetricName IN (${{ - // Inline names as escaped literals: one bind param per name (up to - // 500) pushes the client into a multipart request that query proxies - // can reject. - UNSAFE_RAW_SQL: names.map(name => SqlString.escape(name)).join(','), - }}) - AND TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }}) - AND TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }}) - LIMIT 1 BY MetricName - LIMIT ${{ Int32: names.length }} - `; - - const response = await clickhouseClient.query<'JSON'>({ - query: sql.sql, - query_params: sql.params, - format: 'JSON', - connectionId, - clickhouse_settings: { - max_execution_time: maxExecutionSeconds, - timeout_overflow_mode: 'break', - }, - abort_signal: signal, - }); - const result = (await response.json()) as { - data: { - MetricName: string; - MetricUnit?: string; - MetricDescription?: string; - }[]; - }; - for (const row of result.data) { - enrichments.set(row.MetricName, { - ...(row.MetricUnit ? { unit: row.MetricUnit } : {}), - ...(row.MetricDescription ? { description: row.MetricDescription } : {}), - }); - } - return enrichments; -} diff --git a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts new file mode 100644 index 0000000000..85e261213c --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts @@ -0,0 +1,172 @@ +import { + type ChSql, + chSql, + concatChSql, + tableExpr, +} from '@hyperdx/common-utils/dist/clickhouse'; +import SqlString from 'sqlstring'; + +import type { ClickhouseClient } from '@/clickhouse'; + +// Both queries use timeout_overflow_mode: 'break' so ClickHouse returns what +// it has read when the cap is hit instead of failing. +async function queryRows({ + clickhouseClient, + sql, + connectionId, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: ClickhouseClient; + sql: ChSql; + connectionId: string; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise { + const response = await clickhouseClient.query<'JSON'>({ + query: sql.sql, + query_params: sql.params, + format: 'JSON', + connectionId, + clickhouse_settings: { + max_execution_time: maxExecutionSeconds, + timeout_overflow_mode: 'break', + }, + abort_signal: signal, + }); + const result = (await response.json()) as { data: T[] }; + return result.data; +} + +/** + * Distinct metric names for one kind. Reads only MetricName and TimeUnix; + * unit and description are fetched separately for the returned page, since + * aggregating those String columns across the whole window was the bulk of + * the bytes read. + */ +export async function fetchMetricNames({ + clickhouseClient, + databaseName, + tableName, + connectionId, + startDate, + endDate, + namePattern, + afterName, + limit, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: ClickhouseClient; + databaseName: string; + tableName: string; + connectionId: string; + startDate: Date; + endDate: Date; + namePattern: string | undefined; + afterName: string | undefined; + limit: number; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise { + const whereParts = [ + chSql`TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }})`, + chSql`TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }})`, + ...(afterName !== undefined + ? [chSql`MetricName > ${{ String: afterName }}`] + : []), + ...(namePattern + ? [chSql`MetricName ILIKE ${{ String: namePattern }}`] + : []), + ]; + + const sql = chSql` + SELECT MetricName + FROM ${tableExpr({ database: databaseName, table: tableName })} + WHERE ${concatChSql(' AND ', whereParts)} + GROUP BY MetricName + ORDER BY MetricName ASC + LIMIT ${{ Int32: limit }} + `; + + const rows = await queryRows<{ MetricName: string }>({ + clickhouseClient, + sql, + connectionId, + maxExecutionSeconds, + signal, + }); + return rows.map(row => row.MetricName); +} + +/** + * Unit and description for a page of metric names. `LIMIT 1 BY` plus the + * outer LIMIT lets ClickHouse stop reading once every name has a row, instead + * of aggregating every point in the window. The row picked is arbitrary, which + * matches the `anyLast` this replaced; unit and description are effectively + * constant per metric. + */ +export async function fetchMetricUnitsAndDescriptions({ + clickhouseClient, + databaseName, + tableName, + connectionId, + names, + startDate, + endDate, + hasUnit, + hasDescription, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: ClickhouseClient; + databaseName: string; + tableName: string; + connectionId: string; + names: string[]; + startDate: Date; + endDate: Date; + hasUnit: boolean; + hasDescription: boolean; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise> { + const enrichments = new Map< + string, + { unit?: string; description?: string } + >(); + if (names.length === 0 || (!hasUnit && !hasDescription)) return enrichments; + + const projections = [ + chSql`MetricName`, + ...(hasUnit ? [chSql`${{ Identifier: 'MetricUnit' }}`] : []), + ...(hasDescription ? [chSql`${{ Identifier: 'MetricDescription' }}`] : []), + ]; + const sql = chSql` + SELECT ${concatChSql(', ', projections)} + FROM ${tableExpr({ database: databaseName, table: tableName })} + WHERE MetricName IN (${{ + // Inline names as escaped literals: one bind param per name (up to + // 500) pushes the client into a multipart request that query proxies + // can reject. + UNSAFE_RAW_SQL: names.map(name => SqlString.escape(name)).join(','), + }}) + AND TimeUnix >= fromUnixTimestamp64Milli(${{ Int64: startDate.getTime() }}) + AND TimeUnix <= fromUnixTimestamp64Milli(${{ Int64: endDate.getTime() }}) + LIMIT 1 BY MetricName + LIMIT ${{ Int32: names.length }} + `; + + const rows = await queryRows<{ + MetricName: string; + MetricUnit?: string; + MetricDescription?: string; + }>({ clickhouseClient, sql, connectionId, maxExecutionSeconds, signal }); + for (const row of rows) { + enrichments.set(row.MetricName, { + ...(row.MetricUnit ? { unit: row.MetricUnit } : {}), + ...(row.MetricDescription ? { description: row.MetricDescription } : {}), + }); + } + return enrichments; +} From 7be4071acc535d8e7b038df9b16f3623154fd0a9 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 16:37:49 -0600 Subject: [PATCH 4/9] refactor(mcp): reuse sanitizeFetchError in list_metrics kind scans --- packages/api/src/mcp/tools/sources/describeMetric.ts | 2 +- packages/api/src/mcp/tools/sources/listMetricsPage.ts | 7 ++----- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index 061f628069..cf7690e2fb 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -140,7 +140,7 @@ type FetchResult = { ok: true; data: T } | { ok: false; error: string }; * Compact an error for inclusion in a tool response: single line, * capped length, no stack frames. */ -function sanitizeFetchError(e: unknown): string { +export function sanitizeFetchError(e: unknown): string { const message = e instanceof Error ? e.message : String(e); return message.replace(/\s+/g, ' ').trim().slice(0, 200); } diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts index 603d2fc20d..1987b15bb8 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsPage.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -1,3 +1,4 @@ +import { sanitizeFetchError } from './describeMetric'; import type { DiscoverableMetricKind } from './metricKinds'; export type MetricEntry = { @@ -136,11 +137,7 @@ export function scanKindsForPage({ }, (e: unknown) => { if (done) return; - const message = e instanceof Error ? e.message : String(e); - slot.scan = { - status: 'error', - error: message.replace(/\s+/g, ' ').trim().slice(0, 200), - }; + slot.scan = { status: 'error', error: sanitizeFetchError(e) }; }, ) .finally(() => tryFinish(false)); From 427d320e510d1d72a81a0e0e7a2549e61d18bdbe Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 16:49:24 -0600 Subject: [PATCH 5/9] refactor(mcp): move sanitizeFetchError to mcp/utils/errors Keeps listMetricsPage free of tool-module imports (review bot minor). --- .../api/src/mcp/tools/sources/describeMetric.ts | 15 +++++---------- .../api/src/mcp/tools/sources/listMetricsPage.ts | 3 ++- packages/api/src/mcp/utils/errors.ts | 9 +++++++++ 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index cf7690e2fb..7e431748a7 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -15,7 +15,11 @@ import { getConnectionById } from '@/controllers/connection'; import { getSource } from '@/controllers/sources'; import { clickHouseErrorResult } from '@/mcp/tools/query/helpers'; import type { ToolRegistrar } from '@/mcp/tools/types'; -import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; +import { + mcpServerError, + mcpUserError, + sanitizeFetchError, +} from '@/mcp/utils/errors'; import logger from '@/utils/logger'; import { trimToolResponse } from '@/utils/trimToolResponse'; @@ -136,15 +140,6 @@ type KindDetail = { */ type FetchResult = { ok: true; data: T } | { ok: false; error: string }; -/** - * Compact an error for inclusion in a tool response: single line, - * capped length, no stack frames. - */ -export function sanitizeFetchError(e: unknown): string { - const message = e instanceof Error ? e.message : String(e); - return message.replace(/\s+/g, ' ').trim().slice(0, 200); -} - function parseTimeRange( startTime?: string, endTime?: string, diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts index 1987b15bb8..99fc22126a 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsPage.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -1,4 +1,5 @@ -import { sanitizeFetchError } from './describeMetric'; +import { sanitizeFetchError } from '@/mcp/utils/errors'; + import type { DiscoverableMetricKind } from './metricKinds'; export type MetricEntry = { diff --git a/packages/api/src/mcp/utils/errors.ts b/packages/api/src/mcp/utils/errors.ts index 89c9d8b333..b44a066c28 100644 --- a/packages/api/src/mcp/utils/errors.ts +++ b/packages/api/src/mcp/utils/errors.ts @@ -75,6 +75,15 @@ export function validateObjectId( return null; } +/** + * Compact an error for inclusion in a tool response: single line, + * capped length, no stack frames. + */ +export function sanitizeFetchError(e: unknown): string { + const message = e instanceof Error ? e.message : String(e); + return message.replace(/\s+/g, ' ').trim().slice(0, 200); +} + /** Render a Zod error as one `path: message` line per issue. */ export function formatZodIssues(error: z.ZodError): string { return error.errors From 000cfea550e1213fed79f6199f80b301ba93d634 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 17:04:43 -0600 Subject: [PATCH 6/9] refactor(mcp): split listMetrics.ts under 300 lines and share parseTimeRange - Move the input schema and cursor helpers to listMetricsSchema.ts - Move enrichEntries next to the queries it runs in listMetricsQueries.ts - Share parseTimeRange between list_metrics and describe_metric (jscpd clone) Addresses the greptile file-size finding. --- .../mcp/__tests__/listMetricsCursor.test.ts | 5 +- .../src/mcp/tools/sources/describeMetric.ts | 21 +- .../api/src/mcp/tools/sources/listMetrics.ts | 204 +----------------- .../mcp/tools/sources/listMetricsQueries.ts | 93 +++++++- .../mcp/tools/sources/listMetricsSchema.ts | 85 ++++++++ .../src/mcp/tools/sources/metricTimeRange.ts | 21 ++ 6 files changed, 212 insertions(+), 217 deletions(-) create mode 100644 packages/api/src/mcp/tools/sources/listMetricsSchema.ts create mode 100644 packages/api/src/mcp/tools/sources/metricTimeRange.ts diff --git a/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts b/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts index 8c1f182eb5..f1de6f49a8 100644 --- a/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts +++ b/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts @@ -6,7 +6,10 @@ jest.mock('@/utils/trimToolResponse', () => ({ trimToolResponse: (data: unknown) => ({ data, isTrimmed: false }), })); -import { decodeCursor, encodeCursor } from '@/mcp/tools/sources/listMetrics'; +import { + decodeCursor, + encodeCursor, +} from '@/mcp/tools/sources/listMetricsSchema'; describe('listMetrics cursor', () => { describe('encodeCursor / decodeCursor round-trip', () => { diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index 7e431748a7..4bd72d3e59 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -27,8 +27,8 @@ import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, } from './metricKinds'; +import { parseTimeRange } from './metricTimeRange'; -const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; // Matches the 30s cap the MCP query tools use. const DESCRIBE_TIMEOUT_MS = 30_000; @@ -140,25 +140,6 @@ type KindDetail = { */ type FetchResult = { ok: true; data: T } | { ok: false; error: string }; -function parseTimeRange( - startTime?: string, - endTime?: string, -): { error: string } | { startDate: Date; endDate: Date } { - const endDate = endTime ? new Date(endTime) : new Date(); - const startDate = startTime - ? new Date(startTime) - : new Date(endDate.getTime() - DEFAULT_LOOKBACK_MS); - if (isNaN(endDate.getTime()) || isNaN(startDate.getTime())) { - return { - error: 'Invalid startTime or endTime: must be valid ISO 8601 strings', - }; - } - if (startDate >= endDate) { - return { error: 'endTime must be greater than startTime' }; - } - return { startDate, endDate }; -} - /** * Fetch unit and description for a metric name on a single kind table. * Returns undefined values when the columns are absent from the schema. diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 53d091e10f..544e8ffaba 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -9,28 +9,20 @@ import { getSource } from '@/controllers/sources'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import logger from '@/utils/logger'; -import { - decodeCursor as decodeCursorPayload, - encodeCursor as encodeCursorPayload, -} from '@/utils/pagination'; +import { KIND_TIMED_OUT_ERROR, scanKindsForPage } from './listMetricsPage'; +import { enrichEntries, fetchMetricNames } from './listMetricsQueries'; import { - KIND_TIMED_OUT_ERROR, - type MetricEntry, - scanKindsForPage, -} from './listMetricsPage'; -import { - fetchMetricNames, - fetchMetricUnitsAndDescriptions, -} from './listMetricsQueries'; + decodeCursor, + DEFAULT_LIMIT, + encodeCursor, + listMetricsSchema, +} from './listMetricsSchema'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, } from './metricKinds'; - -const DEFAULT_LIMIT = 50; -const MAX_LIMIT = 500; -const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; +import { parseTimeRange } from './metricTimeRange'; // Wall-clock budget for the whole call, matching the 30s cap the MCP query // tools use. @@ -46,101 +38,6 @@ const ENRICH_RESERVE_MS = 4_000; const NAMES_MAX_EXEC_SECONDS = 24; const ENRICH_MAX_EXEC_SECONDS = 3; -// ─── Cursor ────────────────────────────────────────────────────────────────── - -const cursorPayloadSchema = z.object({ - kind: z.enum(DISCOVERABLE_METRIC_KINDS), - // Absent when the next page starts at the beginning of `kind`. - lastName: z.string().optional(), -}); - -export type ListMetricsCursorPayload = z.infer; - -/** @internal Exported for testing. */ -export function encodeCursor(payload: ListMetricsCursorPayload): string { - return encodeCursorPayload(payload); -} - -/** @internal Exported for testing. */ -export function decodeCursor(raw: string): ListMetricsCursorPayload | null { - return decodeCursorPayload(raw, cursorPayloadSchema); -} - -// ─── Schema ────────────────────────────────────────────────────────────────── - -const listMetricsSchema = z.object({ - sourceId: z - .string() - .describe( - 'Source ID. Must reference a metric source — get IDs from clickstack_list_sources.', - ), - kind: z - .enum(DISCOVERABLE_METRIC_KINDS) - .optional() - .describe( - 'Optional metric kind filter. Omit to scan every populated kind on the source ' + - '(gauge, sum, histogram, exponential histogram, summary). Set to narrow results to one kind. ' + - 'NOTE: summary metrics are discovery-only — they cannot be passed to ' + - 'clickstack_timeseries / clickstack_table; query them with clickstack_sql.', - ), - namePattern: z - .string() - .optional() - .describe( - 'Optional ClickHouse ILIKE pattern applied to MetricName server-side. ' + - 'Use % as the wildcard. Examples: "system.cpu.%", "%duration%", "http.server.%".', - ), - startTime: z - .string() - .optional() - .describe( - 'Restrict to metrics with data points after this ISO 8601 timestamp. ' + - 'Default: 24 hours before endTime (or now).', - ), - endTime: z - .string() - .optional() - .describe('End of the time window as ISO 8601. Default: now.'), - limit: z - .number() - .int() - .min(1) - .max(MAX_LIMIT) - .optional() - .default(DEFAULT_LIMIT) - .describe( - `Max metrics returned per page. Default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}.`, - ), - cursor: z - .string() - .optional() - .describe( - 'Opaque pagination cursor returned by a previous call as `nextCursor`. ' + - 'Pass it back unchanged to get the next page.', - ), -}); - -// ─── Helpers ───────────────────────────────────────────────────────────────── - -function parseTimeRange( - startTime?: string, - endTime?: string, -): { error: string } | { startDate: Date; endDate: Date } { - const endDate = endTime ? new Date(endTime) : new Date(); - const startDate = startTime - ? new Date(startTime) - : new Date(endDate.getTime() - DEFAULT_LOOKBACK_MS); - if (isNaN(endDate.getTime()) || isNaN(startDate.getTime())) { - return { - error: 'Invalid startTime or endTime: must be valid ISO 8601 strings', - }; - } - if (startDate >= endDate) { - return { error: 'endTime must be greater than startTime' }; - } - return { startDate, endDate }; -} - // ─── Tool registration ─────────────────────────────────────────────────────── export function registerListMetrics({ @@ -215,90 +112,6 @@ export function registerListMetrics({ ); } -type Enrichments = Awaited>; - -/** - * Attach unit and description to each entry. Best effort: on failure or - * timeout the names are still returned. - */ -async function enrichEntries({ - entries, - clickhouseClient, - metadata, - databaseName, - metricTables, - connectionId, - startDate, - endDate, - signal, -}: { - entries: MetricEntry[]; - clickhouseClient: ClickhouseClient; - metadata: ReturnType; - databaseName: string; - metricTables: Partial>; - connectionId: string; - startDate: Date; - endDate: Date; - signal: AbortSignal; -}): Promise { - const kinds = [...new Set(entries.map(e => e.kind))]; - // metadata.getColumns takes no abort signal, so race the whole lookup - // against it; otherwise a slow schema lookup could outlast the call's - // wall clock and discard the names already collected. - const aborted = new Promise(resolve => { - if (signal.aborted) resolve(undefined); - signal.addEventListener('abort', () => resolve(undefined), { once: true }); - }); - const lookups = Promise.all( - kinds.map(async (kind): Promise<[DiscoverableMetricKind, Enrichments]> => { - const tableName = metricTables[kind]!; - try { - // Skip MetricUnit / MetricDescription on non-OTel-default schemas. - const columns = await metadata.getColumns({ - databaseName, - tableName, - connectionId, - }); - const columnNames = new Set(columns.map(c => c.name)); - const enrichments = await fetchMetricUnitsAndDescriptions({ - clickhouseClient, - databaseName, - tableName, - connectionId, - names: entries.filter(e => e.kind === kind).map(e => e.name), - startDate, - endDate, - hasUnit: columnNames.has('MetricUnit'), - hasDescription: columnNames.has('MetricDescription'), - maxExecutionSeconds: ENRICH_MAX_EXEC_SECONDS, - signal, - }); - return [kind, enrichments]; - } catch (e) { - logger.warn( - { kind, tableName, error: e instanceof Error ? e.message : e }, - 'Failed to fetch metric unit/description', - ); - return [kind, new Map()]; - } - }), - ); - const byKind = await Promise.race([lookups, aborted]); - if (!byKind) { - logger.warn( - { kinds }, - 'Timed out fetching metric unit/description; returning names only', - ); - return entries; - } - const enrichments = new Map(byKind); - return entries.map(entry => ({ - ...entry, - ...enrichments.get(entry.kind)?.get(entry.name), - })); -} - async function listMetricsImpl( teamId: string, input: z.infer, @@ -414,6 +227,7 @@ async function listMetricsImpl( connectionId, startDate, endDate, + maxExecutionSeconds: ENRICH_MAX_EXEC_SECONDS, signal: enrichSignal, }); diff --git a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts index 85e261213c..3d32a38a15 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts @@ -4,9 +4,14 @@ import { concatChSql, tableExpr, } from '@hyperdx/common-utils/dist/clickhouse'; +import type { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import SqlString from 'sqlstring'; import type { ClickhouseClient } from '@/clickhouse'; +import logger from '@/utils/logger'; + +import type { MetricEntry } from './listMetricsPage'; +import type { DiscoverableMetricKind } from './metricKinds'; // Both queries use timeout_overflow_mode: 'break' so ClickHouse returns what // it has read when the cap is hit instead of failing. @@ -106,7 +111,7 @@ export async function fetchMetricNames({ * matches the `anyLast` this replaced; unit and description are effectively * constant per metric. */ -export async function fetchMetricUnitsAndDescriptions({ +async function fetchMetricUnitsAndDescriptions({ clickhouseClient, databaseName, tableName, @@ -170,3 +175,89 @@ export async function fetchMetricUnitsAndDescriptions({ } return enrichments; } + +type Enrichments = Awaited>; + +/** + * Attach unit and description to each entry. Best effort: on failure or + * timeout the names are still returned. + */ +export async function enrichEntries({ + entries, + clickhouseClient, + metadata, + databaseName, + metricTables, + connectionId, + startDate, + endDate, + maxExecutionSeconds, + signal, +}: { + entries: MetricEntry[]; + clickhouseClient: ClickhouseClient; + metadata: ReturnType; + databaseName: string; + metricTables: Partial>; + connectionId: string; + startDate: Date; + endDate: Date; + maxExecutionSeconds: number; + signal: AbortSignal; +}): Promise { + const kinds = [...new Set(entries.map(e => e.kind))]; + // metadata.getColumns takes no abort signal, so race the whole lookup + // against it; otherwise a slow schema lookup could outlast the call's + // wall clock and discard the names already collected. + const aborted = new Promise(resolve => { + if (signal.aborted) resolve(undefined); + signal.addEventListener('abort', () => resolve(undefined), { once: true }); + }); + const lookups = Promise.all( + kinds.map(async (kind): Promise<[DiscoverableMetricKind, Enrichments]> => { + const tableName = metricTables[kind]!; + try { + // Skip MetricUnit / MetricDescription on non-OTel-default schemas. + const columns = await metadata.getColumns({ + databaseName, + tableName, + connectionId, + }); + const columnNames = new Set(columns.map(c => c.name)); + const enrichments = await fetchMetricUnitsAndDescriptions({ + clickhouseClient, + databaseName, + tableName, + connectionId, + names: entries.filter(e => e.kind === kind).map(e => e.name), + startDate, + endDate, + hasUnit: columnNames.has('MetricUnit'), + hasDescription: columnNames.has('MetricDescription'), + maxExecutionSeconds, + signal, + }); + return [kind, enrichments]; + } catch (e) { + logger.warn( + { kind, tableName, error: e instanceof Error ? e.message : e }, + 'Failed to fetch metric unit/description', + ); + return [kind, new Map()]; + } + }), + ); + const byKind = await Promise.race([lookups, aborted]); + if (!byKind) { + logger.warn( + { kinds }, + 'Timed out fetching metric unit/description; returning names only', + ); + return entries; + } + const enrichments = new Map(byKind); + return entries.map(entry => ({ + ...entry, + ...enrichments.get(entry.kind)?.get(entry.name), + })); +} diff --git a/packages/api/src/mcp/tools/sources/listMetricsSchema.ts b/packages/api/src/mcp/tools/sources/listMetricsSchema.ts new file mode 100644 index 0000000000..304e3a016e --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsSchema.ts @@ -0,0 +1,85 @@ +import { z } from 'zod'; + +import { + decodeCursor as decodeCursorPayload, + encodeCursor as encodeCursorPayload, +} from '@/utils/pagination'; + +import { DISCOVERABLE_METRIC_KINDS } from './metricKinds'; + +export const DEFAULT_LIMIT = 50; +const MAX_LIMIT = 500; + +// ─── Cursor ────────────────────────────────────────────────────────────────── + +const cursorPayloadSchema = z.object({ + kind: z.enum(DISCOVERABLE_METRIC_KINDS), + // Absent when the next page starts at the beginning of `kind`. + lastName: z.string().optional(), +}); + +export type ListMetricsCursorPayload = z.infer; + +/** @internal Exported for testing. */ +export function encodeCursor(payload: ListMetricsCursorPayload): string { + return encodeCursorPayload(payload); +} + +/** @internal Exported for testing. */ +export function decodeCursor(raw: string): ListMetricsCursorPayload | null { + return decodeCursorPayload(raw, cursorPayloadSchema); +} + +// ─── Schema ────────────────────────────────────────────────────────────────── + +export const listMetricsSchema = z.object({ + sourceId: z + .string() + .describe( + 'Source ID. Must reference a metric source — get IDs from clickstack_list_sources.', + ), + kind: z + .enum(DISCOVERABLE_METRIC_KINDS) + .optional() + .describe( + 'Optional metric kind filter. Omit to scan every populated kind on the source ' + + '(gauge, sum, histogram, exponential histogram, summary). Set to narrow results to one kind. ' + + 'NOTE: summary metrics are discovery-only — they cannot be passed to ' + + 'clickstack_timeseries / clickstack_table; query them with clickstack_sql.', + ), + namePattern: z + .string() + .optional() + .describe( + 'Optional ClickHouse ILIKE pattern applied to MetricName server-side. ' + + 'Use % as the wildcard. Examples: "system.cpu.%", "%duration%", "http.server.%".', + ), + startTime: z + .string() + .optional() + .describe( + 'Restrict to metrics with data points after this ISO 8601 timestamp. ' + + 'Default: 24 hours before endTime (or now).', + ), + endTime: z + .string() + .optional() + .describe('End of the time window as ISO 8601. Default: now.'), + limit: z + .number() + .int() + .min(1) + .max(MAX_LIMIT) + .optional() + .default(DEFAULT_LIMIT) + .describe( + `Max metrics returned per page. Default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}.`, + ), + cursor: z + .string() + .optional() + .describe( + 'Opaque pagination cursor returned by a previous call as `nextCursor`. ' + + 'Pass it back unchanged to get the next page.', + ), +}); diff --git a/packages/api/src/mcp/tools/sources/metricTimeRange.ts b/packages/api/src/mcp/tools/sources/metricTimeRange.ts new file mode 100644 index 0000000000..8d58d81881 --- /dev/null +++ b/packages/api/src/mcp/tools/sources/metricTimeRange.ts @@ -0,0 +1,21 @@ +const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; + +/** Resolve the metric tools' time window; defaults to the last 24 hours. */ +export function parseTimeRange( + startTime?: string, + endTime?: string, +): { error: string } | { startDate: Date; endDate: Date } { + const endDate = endTime ? new Date(endTime) : new Date(); + const startDate = startTime + ? new Date(startTime) + : new Date(endDate.getTime() - DEFAULT_LOOKBACK_MS); + if (isNaN(endDate.getTime()) || isNaN(startDate.getTime())) { + return { + error: 'Invalid startTime or endTime: must be valid ISO 8601 strings', + }; + } + if (startDate >= endDate) { + return { error: 'endTime must be greater than startTime' }; + } + return { startDate, endDate }; +} From 9b7ae5db972192a67a2eff9ba77aa7a9eed7b8e6 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 1 Oct 2026 17:18:13 -0600 Subject: [PATCH 7/9] fix(mcp): report slow list_metrics kinds as timed out instead of truncated The names scan used timeout_overflow_mode 'break' with a 24s cap, below the 26s scan deadline, so ClickHouse could return a partial name set that looked complete and the cursor skipped names never read. Raise the cap above the deadline and throw on overflow so the kind is reported in partialFailure and the cursor resumes at it (review bot major). --- .../mcp/__tests__/listMetricsQueries.test.ts | 35 +++++++++++++++++++ .../api/src/mcp/tools/sources/listMetrics.ts | 8 +++-- .../mcp/tools/sources/listMetricsQueries.ts | 18 +++++++--- 3 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 packages/api/src/mcp/__tests__/listMetricsQueries.test.ts diff --git a/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts new file mode 100644 index 0000000000..fc3e7238e6 --- /dev/null +++ b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts @@ -0,0 +1,35 @@ +import type { ClickhouseClient } from '@/clickhouse'; +import { fetchMetricNames } from '@/mcp/tools/sources/listMetricsQueries'; + +describe('fetchMetricNames', () => { + it('throws on the ClickHouse cap instead of returning a truncated name set', async () => { + const query = jest.fn().mockResolvedValue({ + json: () => Promise.resolve({ data: [{ MetricName: 'a' }] }), + }); + const clickhouseClient = { query } as unknown as ClickhouseClient; + + const names = await fetchMetricNames({ + clickhouseClient, + databaseName: 'default', + tableName: 'otel_metrics_gauge', + connectionId: 'conn', + startDate: new Date(0), + endDate: new Date(1000), + namePattern: undefined, + afterName: undefined, + limit: 2, + maxExecutionSeconds: 28, + signal: new AbortController().signal, + }); + + expect(names).toEqual(['a']); + expect(query).toHaveBeenCalledWith( + expect.objectContaining({ + clickhouse_settings: { + max_execution_time: 28, + timeout_overflow_mode: 'throw', + }, + }), + ); + }); +}); diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 544e8ffaba..4660e45bca 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -33,9 +33,11 @@ const LIST_TIMEOUT_MS = 30_000; // timed out and the kinds that finished are returned. const ENRICH_RESERVE_MS = 4_000; -// Per-query ClickHouse caps. Both use timeout_overflow_mode: 'break', so -// ClickHouse returns what it has read before the wall clock fires. -const NAMES_MAX_EXEC_SECONDS = 24; +// Per-query ClickHouse caps. The names cap sits above the scan deadline +// (LIST_TIMEOUT_MS - ENRICH_RESERVE_MS) so a slow kind is aborted and +// reported as timed out, not cut short by ClickHouse. A partial name set +// would look complete and the cursor would skip the names never read. +const NAMES_MAX_EXEC_SECONDS = 28; const ENRICH_MAX_EXEC_SECONDS = 3; // ─── Tool registration ─────────────────────────────────────────────────────── diff --git a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts index 3d32a38a15..0a17276a90 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts @@ -13,19 +13,19 @@ import logger from '@/utils/logger'; import type { MetricEntry } from './listMetricsPage'; import type { DiscoverableMetricKind } from './metricKinds'; -// Both queries use timeout_overflow_mode: 'break' so ClickHouse returns what -// it has read when the cap is hit instead of failing. async function queryRows({ clickhouseClient, sql, connectionId, maxExecutionSeconds, + timeoutOverflowMode, signal, }: { clickhouseClient: ClickhouseClient; sql: ChSql; connectionId: string; maxExecutionSeconds: number; + timeoutOverflowMode: 'break' | 'throw'; signal: AbortSignal; }): Promise { const response = await clickhouseClient.query<'JSON'>({ @@ -35,7 +35,7 @@ async function queryRows({ connectionId, clickhouse_settings: { max_execution_time: maxExecutionSeconds, - timeout_overflow_mode: 'break', + timeout_overflow_mode: timeoutOverflowMode, }, abort_signal: signal, }); @@ -99,6 +99,8 @@ export async function fetchMetricNames({ sql, connectionId, maxExecutionSeconds, + // A truncated name set would be paged past as if complete. + timeoutOverflowMode: 'throw', signal, }); return rows.map(row => row.MetricName); @@ -166,7 +168,15 @@ async function fetchMetricUnitsAndDescriptions({ MetricName: string; MetricUnit?: string; MetricDescription?: string; - }>({ clickhouseClient, sql, connectionId, maxExecutionSeconds, signal }); + }>({ + clickhouseClient, + sql, + connectionId, + maxExecutionSeconds, + // Partial enrichment is fine; names without a row just lack unit/description. + timeoutOverflowMode: 'break', + signal, + }); for (const row of rows) { enrichments.set(row.MetricName, { ...(row.MetricUnit ? { unit: row.MetricUnit } : {}), From 5ae8de2f7080269cf1eb73558a29602e41d27d6d Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 8 Oct 2026 09:41:24 -0600 Subject: [PATCH 8/9] fix(mcp): keep list_metrics paging forward past a kind that always times out End the page at a timed-out kind only when it already has entries; otherwise record it in partialFailure and continue, so a call never returns the cursor it was given (review bot major). Drop ASCII section dividers (greptile P2). --- .../api/src/mcp/__tests__/listMetricsPage.test.ts | 14 ++++++++++---- packages/api/src/mcp/tools/sources/listMetrics.ts | 2 -- .../api/src/mcp/tools/sources/listMetricsPage.ts | 12 +++++++----- .../api/src/mcp/tools/sources/listMetricsSchema.ts | 4 ---- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/packages/api/src/mcp/__tests__/listMetricsPage.test.ts b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts index c974d486ae..d6df1b353b 100644 --- a/packages/api/src/mcp/__tests__/listMetricsPage.test.ts +++ b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts @@ -83,14 +83,20 @@ describe('assembleMetricsPage', () => { ]); }); - it("resumes a timed-out cursor kind from the cursor's position", () => { + it('skips a timed-out kind when nothing was collected so the cursor moves forward', () => { const page = assembleMetricsPage( - [{ kind: 'sum', afterName: 'm', scan: pending }], + [ + { kind: 'gauge', afterName: 'm', scan: pending }, + { kind: 'sum', scan: ok('a') }, + ], 10, true, ); - expect(page?.entries).toEqual([]); - expect(page?.next).toEqual({ kind: 'sum', lastName: 'm' }); + expect(page?.entries).toEqual([{ name: 'a', kind: 'sum' }]); + expect(page?.next).toBeUndefined(); + expect(page?.partialFailure).toEqual([ + { kind: 'gauge', error: KIND_TIMED_OUT_ERROR }, + ]); }); it('skips failed kinds and records them', () => { diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 4660e45bca..bbdfe719ad 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -40,8 +40,6 @@ const ENRICH_RESERVE_MS = 4_000; const NAMES_MAX_EXEC_SECONDS = 28; const ENRICH_MAX_EXEC_SECONDS = 3; -// ─── Tool registration ─────────────────────────────────────────────────────── - export function registerListMetrics({ context, registerTool, diff --git a/packages/api/src/mcp/tools/sources/listMetricsPage.ts b/packages/api/src/mcp/tools/sources/listMetricsPage.ts index 99fc22126a..57aab6e5c6 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsPage.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -39,8 +39,8 @@ export const KIND_TIMED_OUT_ERROR = * Build a page from per-kind scan results, filling `limit` entries in kind * order. Each scan holds up to `limit + 1` names so an overflow can be * detected. Returns null when a pending kind still decides the page's - * contents, unless `finalize` is set, in which case the first pending kind - * is reported as timed out and the page ends there. + * contents, unless `finalize` is set, in which case pending kinds are + * reported as timed out. * * @internal Exported for testing. */ @@ -60,10 +60,12 @@ export function assembleMetricsPage( const { kind, scan } = slot; if (scan.status === 'pending') { if (!finalize) return null; - // End the page at the timed-out kind so the cursor resumes there. - // Moving on to later kinds would leave its names unreachable. partialFailure.push({ kind, error: KIND_TIMED_OUT_ERROR }); - return resumeAt(slot); + // End the page at the timed-out kind so the cursor resumes there. + // With nothing collected that would hand back the caller's own + // cursor forever, so skip it like a failed kind instead. + if (entries.length > 0) return resumeAt(slot); + continue; } if (scan.status === 'error') { partialFailure.push({ kind, error: scan.error }); diff --git a/packages/api/src/mcp/tools/sources/listMetricsSchema.ts b/packages/api/src/mcp/tools/sources/listMetricsSchema.ts index 304e3a016e..f10ae9880c 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsSchema.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsSchema.ts @@ -10,8 +10,6 @@ import { DISCOVERABLE_METRIC_KINDS } from './metricKinds'; export const DEFAULT_LIMIT = 50; const MAX_LIMIT = 500; -// ─── Cursor ────────────────────────────────────────────────────────────────── - const cursorPayloadSchema = z.object({ kind: z.enum(DISCOVERABLE_METRIC_KINDS), // Absent when the next page starts at the beginning of `kind`. @@ -30,8 +28,6 @@ export function decodeCursor(raw: string): ListMetricsCursorPayload | null { return decodeCursorPayload(raw, cursorPayloadSchema); } -// ─── Schema ────────────────────────────────────────────────────────────────── - export const listMetricsSchema = z.object({ sourceId: z .string() From 0391b5a6b367a5c2798c88d1f5385b9cd3beae26 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 8 Oct 2026 09:58:47 -0600 Subject: [PATCH 9/9] refactor(mcp): drop duplicate parseTimeRange and fixture types; fix lint ceiling - Reuse parseTimeRange from mcp/tools/query/helpers with a defaultLookbackMs argument instead of a second copy (review bot minor) - Share a NumberMetricPoint type between the gauge and sum fixtures (jscpd) - Type fetchMetricNames' client as Pick so its test needs no cast, keeping api lint at the 302-warning ceiling after merging main --- packages/api/src/fixtures.ts | 37 ++++++++----------- .../mcp/__tests__/listMetricsQueries.test.ts | 4 +- packages/api/src/mcp/tools/query/helpers.ts | 3 +- .../src/mcp/tools/sources/describeMetric.ts | 13 +++++-- .../api/src/mcp/tools/sources/listMetrics.ts | 9 ++++- .../mcp/tools/sources/listMetricsQueries.ts | 6 +-- .../api/src/mcp/tools/sources/metricKinds.ts | 3 ++ .../src/mcp/tools/sources/metricTimeRange.ts | 21 ----------- 8 files changed, 41 insertions(+), 55 deletions(-) delete mode 100644 packages/api/src/mcp/tools/sources/metricTimeRange.ts diff --git a/packages/api/src/fixtures.ts b/packages/api/src/fixtures.ts index 4868ec8bbe..47d2edafd8 100644 --- a/packages/api/src/fixtures.ts +++ b/packages/api/src/fixtures.ts @@ -449,19 +449,19 @@ export const bulkInsertLogs = async ( // the on-disk row is byte-identical to today's behaviour. New tests that need // to exercise the cross-scope attribute hashing (see HDX-4466) can opt in by // passing one or both maps explicitly. -export const bulkInsertMetricsGauge = async ( - metrics: { - MetricName: string; - MetricUnit?: string; - MetricDescription?: string; - ResourceAttributes: Record; - ScopeAttributes?: Record; - Attributes?: Record; - ServiceName: string; - TimeUnix: Date; - Value: number; - }[], -) => { +type NumberMetricPoint = { + MetricName: string; + MetricUnit?: string; + MetricDescription?: string; + ResourceAttributes: Record; + ScopeAttributes?: Record; + Attributes?: Record; + ServiceName: string; + TimeUnix: Date; + Value: number; +}; + +export const bulkInsertMetricsGauge = async (metrics: NumberMetricPoint[]) => { if (!config.IS_CI) { throw new Error('ONLY execute this in CI env 😈 !!!'); } @@ -472,17 +472,10 @@ export const bulkInsertMetricsGauge = async ( }; export const bulkInsertMetricsSum = async ( - metrics: { + metrics: (NumberMetricPoint & { AggregationTemporality: number; IsMonotonic: boolean; - MetricName: string; - ResourceAttributes: Record; - ScopeAttributes?: Record; - Attributes?: Record; - ServiceName: string; - TimeUnix: Date; - Value: number; - }[], + })[], ) => { if (!config.IS_CI) { throw new Error('ONLY execute this in CI env 😈 !!!'); diff --git a/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts index fc3e7238e6..57eaf82ba9 100644 --- a/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts +++ b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts @@ -1,4 +1,3 @@ -import type { ClickhouseClient } from '@/clickhouse'; import { fetchMetricNames } from '@/mcp/tools/sources/listMetricsQueries'; describe('fetchMetricNames', () => { @@ -6,10 +5,9 @@ describe('fetchMetricNames', () => { const query = jest.fn().mockResolvedValue({ json: () => Promise.resolve({ data: [{ MetricName: 'a' }] }), }); - const clickhouseClient = { query } as unknown as ClickhouseClient; const names = await fetchMetricNames({ - clickhouseClient, + clickhouseClient: { query }, databaseName: 'default', tableName: 'otel_metrics_gauge', connectionId: 'conn', diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 8743c88fb0..d18af2e717 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -253,11 +253,12 @@ export function buildTile( export function parseTimeRange( startTime?: string, endTime?: string, + defaultLookbackMs: number = ms('15m'), ): { error: string } | { startDate: Date; endDate: Date } { const endDate = endTime ? new Date(endTime) : new Date(); const startDate = startTime ? new Date(startTime) - : new Date(endDate.getTime() - ms('15m')); + : new Date(endDate.getTime() - defaultLookbackMs); if (isNaN(endDate.getTime()) || isNaN(startDate.getTime())) { return { error: 'Invalid startTime or endTime: must be valid ISO 8601 strings', diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index 4bd72d3e59..1a3312cb16 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -13,7 +13,10 @@ import { z } from 'zod'; import { ClickhouseClient } from '@/clickhouse'; import { getConnectionById } from '@/controllers/connection'; import { getSource } from '@/controllers/sources'; -import { clickHouseErrorResult } from '@/mcp/tools/query/helpers'; +import { + clickHouseErrorResult, + parseTimeRange, +} from '@/mcp/tools/query/helpers'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, @@ -26,8 +29,8 @@ import { trimToolResponse } from '@/utils/trimToolResponse'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, + METRIC_DEFAULT_LOOKBACK_MS, } from './metricKinds'; -import { parseTimeRange } from './metricTimeRange'; // Matches the 30s cap the MCP query tools use. const DESCRIBE_TIMEOUT_MS = 30_000; @@ -480,7 +483,11 @@ async function describeMetricImpl( ); } - const timeRange = parseTimeRange(input.startTime, input.endTime); + const timeRange = parseTimeRange( + input.startTime, + input.endTime, + METRIC_DEFAULT_LOOKBACK_MS, + ); if ('error' in timeRange) { return mcpUserError(timeRange.error); } diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index bbdfe719ad..c3de415be9 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -6,6 +6,7 @@ import { z } from 'zod'; import { ClickhouseClient } from '@/clickhouse'; import { getConnectionById } from '@/controllers/connection'; import { getSource } from '@/controllers/sources'; +import { parseTimeRange } from '@/mcp/tools/query/helpers'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import logger from '@/utils/logger'; @@ -21,8 +22,8 @@ import { import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, + METRIC_DEFAULT_LOOKBACK_MS, } from './metricKinds'; -import { parseTimeRange } from './metricTimeRange'; // Wall-clock budget for the whole call, matching the 30s cap the MCP query // tools use. @@ -130,7 +131,11 @@ async function listMetricsImpl( ); } - const timeRange = parseTimeRange(input.startTime, input.endTime); + const timeRange = parseTimeRange( + input.startTime, + input.endTime, + METRIC_DEFAULT_LOOKBACK_MS, + ); if ('error' in timeRange) { return mcpUserError(timeRange.error); } diff --git a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts index 0a17276a90..442dbae169 100644 --- a/packages/api/src/mcp/tools/sources/listMetricsQueries.ts +++ b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts @@ -21,7 +21,7 @@ async function queryRows({ timeoutOverflowMode, signal, }: { - clickhouseClient: ClickhouseClient; + clickhouseClient: Pick; sql: ChSql; connectionId: string; maxExecutionSeconds: number; @@ -62,7 +62,7 @@ export async function fetchMetricNames({ maxExecutionSeconds, signal, }: { - clickhouseClient: ClickhouseClient; + clickhouseClient: Pick; databaseName: string; tableName: string; connectionId: string; @@ -126,7 +126,7 @@ async function fetchMetricUnitsAndDescriptions({ maxExecutionSeconds, signal, }: { - clickhouseClient: ClickhouseClient; + clickhouseClient: Pick; databaseName: string; tableName: string; connectionId: string; diff --git a/packages/api/src/mcp/tools/sources/metricKinds.ts b/packages/api/src/mcp/tools/sources/metricKinds.ts index 9df70ad590..6cdb7aa9a0 100644 --- a/packages/api/src/mcp/tools/sources/metricKinds.ts +++ b/packages/api/src/mcp/tools/sources/metricKinds.ts @@ -93,3 +93,6 @@ export function sanitizeMetricTables( } return Object.keys(out).length > 0 ? out : undefined; } + +/** Default time window for the metric discovery tools when startTime is omitted. */ +export const METRIC_DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; diff --git a/packages/api/src/mcp/tools/sources/metricTimeRange.ts b/packages/api/src/mcp/tools/sources/metricTimeRange.ts deleted file mode 100644 index 8d58d81881..0000000000 --- a/packages/api/src/mcp/tools/sources/metricTimeRange.ts +++ /dev/null @@ -1,21 +0,0 @@ -const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; - -/** Resolve the metric tools' time window; defaults to the last 24 hours. */ -export function parseTimeRange( - startTime?: string, - endTime?: string, -): { error: string } | { startDate: Date; endDate: Date } { - const endDate = endTime ? new Date(endTime) : new Date(); - const startDate = startTime - ? new Date(startTime) - : new Date(endDate.getTime() - DEFAULT_LOOKBACK_MS); - if (isNaN(endDate.getTime()) || isNaN(startDate.getTime())) { - return { - error: 'Invalid startTime or endTime: must be valid ISO 8601 strings', - }; - } - if (startDate >= endDate) { - return { error: 'endTime must be greater than startTime' }; - } - return { startDate, endDate }; -}