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/fixtures.ts b/packages/api/src/fixtures.ts index 414ac9eebf..47d2edafd8 100644 --- a/packages/api/src/fixtures.ts +++ b/packages/api/src/fixtures.ts @@ -449,17 +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; - 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 😈 !!!'); } @@ -470,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__/listMetricsCursor.test.ts b/packages/api/src/mcp/__tests__/listMetricsCursor.test.ts index 6cb4fbe105..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', () => { @@ -77,11 +80,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 new file mode 100644 index 0000000000..d6df1b353b --- /dev/null +++ b/packages/api/src/mcp/__tests__/listMetricsPage.test.ts @@ -0,0 +1,182 @@ +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' }; + +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( + slots(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( + slots(ok('a'), ok('b', 'c', 'd'), pending), + 2, + false, + ); + expect(page?.entries.map(e => e.name)).toEqual(['a', 'b']); + expect(page?.next).toEqual({ kind: 'sum', lastName: 'b' }); + }); + + it('points the cursor at the next kind with names when an earlier kind exactly fills the page', () => { + const page = assembleMetricsPage( + slots(ok('a', 'b'), ok(), ok('c')), + 2, + false, + ); + expect(page?.entries.map(e => e.name)).toEqual(['a', '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(slots(ok('a'), pending, ok('b')), 10, false), + ).toBeNull(); + }); + + it('ends the page at a timed-out kind and resumes the cursor there', () => { + const page = assembleMetricsPage( + slots(ok('a'), pending, ok('b')), + 10, + true, + ); + 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('skips a timed-out kind when nothing was collected so the cursor moves forward', () => { + const page = assembleMetricsPage( + [ + { kind: 'gauge', afterName: 'm', scan: pending }, + { kind: 'sum', scan: ok('a') }, + ], + 10, + true, + ); + 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', () => { + const page = assembleMetricsPage( + slots({ 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 = (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: [{ kind: 'gauge' }, { kind: '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: [{ kind: 'gauge' }, { kind: '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(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('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: [{ kind: 'gauge' }, { kind: 'sum' }, { kind: 'histogram' }], + limit: 10, + deadlineAt: Date.now() + 50, + signal: new AbortController().signal, + fetchNames: ({ kind }, signal) => + kind === 'sum' ? never(signal) : Promise.resolve([kind]), + }); + 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__/listMetricsQueries.test.ts b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts new file mode 100644 index 0000000000..57eaf82ba9 --- /dev/null +++ b/packages/api/src/mcp/__tests__/listMetricsQueries.test.ts @@ -0,0 +1,33 @@ +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 names = await fetchMetricNames({ + clickhouseClient: { query }, + 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/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts index cfe23e7f2f..7e86e7c3a5 100644 --- a/packages/api/src/mcp/__tests__/sources.int.test.ts +++ b/packages/api/src/mcp/__tests__/sources.int.test.ts @@ -895,6 +895,64 @@ 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: { + 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; + } + 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/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 513b0c576a..f1dcbe426a 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -258,11 +258,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 d42bc23f68..1a3312cb16 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -13,19 +13,27 @@ 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, mcpUserError } from '@/mcp/utils/errors'; +import { + mcpServerError, + mcpUserError, + sanitizeFetchError, +} from '@/mcp/utils/errors'; import logger from '@/utils/logger'; import { trimToolResponse } from '@/utils/trimToolResponse'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, + METRIC_DEFAULT_LOOKBACK_MS, } 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 +42,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; @@ -132,34 +143,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. - */ -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, -): { 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. @@ -500,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 5ad4f60dea..c3de415be9 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -1,237 +1,45 @@ -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'; 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'; -import { - decodeCursor as decodeCursorPayload, - encodeCursor as encodeCursorPayload, -} from '@/utils/pagination'; +import { KIND_TIMED_OUT_ERROR, scanKindsForPage } from './listMetricsPage'; +import { enrichEntries, fetchMetricNames } from './listMetricsQueries'; +import { + decodeCursor, + DEFAULT_LIMIT, + encodeCursor, + listMetricsSchema, +} from './listMetricsSchema'; import { DISCOVERABLE_METRIC_KINDS, type DiscoverableMetricKind, + METRIC_DEFAULT_LOOKBACK_MS, } from './metricKinds'; -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; - -// Server-side ClickHouse execution cap per query. Matches the bounds -// used by describeMetric's fetchAttributeKeys / sampleAttributeValues. -const MAX_EXEC_SECONDS = 8; - -// ─── Cursor ────────────────────────────────────────────────────────────────── - -const cursorPayloadSchema = z.object({ - kind: z.enum(DISCOVERABLE_METRIC_KINDS), - lastName: z.string(), -}); - -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 ───────────────────────────────────────────────────────────────── - -type MetricEntry = { - name: string; - kind: DiscoverableMetricKind; - unit?: string; - description?: 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 }; -} - -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'); +// Wall-clock budget for the whole call, matching the 30s cap the MCP query +// tools use. +const LIST_TIMEOUT_MS = 30_000; - const projections = [ - chSql`MetricName`, - ...(hasUnit - ? [chSql`anyLast(${{ Identifier: 'MetricUnit' }}) AS MetricUnit`] - : []), - ...(hasDescription - ? [ - chSql`anyLast(${{ Identifier: 'MetricDescription' }}) AS MetricDescription`, - ] - : []), - ]; +// 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; - 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 ─────────────────────────────────────────────────────── +// 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; export function registerListMetrics({ context, @@ -266,6 +74,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 +86,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) { @@ -302,6 +116,7 @@ export function registerListMetrics({ async function listMetricsImpl( teamId: string, input: z.infer, + deadlineAt: number, signal: AbortSignal, ) { const source = await getSource(teamId, input.sourceId); @@ -316,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); } @@ -334,9 +153,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 — @@ -365,65 +184,71 @@ 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).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, afterName }, 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); + // 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, + maxExecutionSeconds: ENRICH_MAX_EXEC_SECONDS, + 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..57aab6e5c6 --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsPage.ts @@ -0,0 +1,151 @@ +import { sanitizeFetchError } from '@/mcp/utils/errors'; + +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 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[]; + /** + * 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 }[]; +}; + +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( + slots: KindSlot[], + limit: number, + finalize: boolean, +): MetricsPage | null { + const entries: MetricEntry[] = []; + const partialFailure: MetricsPage['partialFailure'] = []; + 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; + partialFailure.push({ kind, error: KIND_TIMED_OUT_ERROR }); + // 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 }); + 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) { + 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 }; + } + } + return { entries, partialFailure }; +} + +/** + * 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, + limit, + deadlineAt, + signal, + fetchNames, +}: { + kinds: KindToScan[]; + limit: number; + deadlineAt: number; + signal: AbortSignal; + fetchNames: (kind: KindToScan, signal: AbortSignal) => Promise; +}): Promise { + const slots: KindSlot[] = kinds.map(k => ({ + ...k, + scan: { 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(slots, 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()), + ); + for (const slot of slots) { + fetchNames(slot, controller.signal) + .then( + names => { + slot.scan = { status: 'ok', names }; + }, + (e: unknown) => { + if (done) return; + slot.scan = { status: 'error', error: sanitizeFetchError(e) }; + }, + ) + .finally(() => tryFinish(false)); + } + // Resolves right away when there are no kinds to scan. + tryFinish(false); + }); +} 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..442dbae169 --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsQueries.ts @@ -0,0 +1,273 @@ +import { + type ChSql, + chSql, + 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'; + +async function queryRows({ + clickhouseClient, + sql, + connectionId, + maxExecutionSeconds, + timeoutOverflowMode, + signal, +}: { + clickhouseClient: Pick; + sql: ChSql; + connectionId: string; + maxExecutionSeconds: number; + timeoutOverflowMode: 'break' | 'throw'; + 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: timeoutOverflowMode, + }, + 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: Pick; + 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, + // A truncated name set would be paged past as if complete. + timeoutOverflowMode: 'throw', + 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. + */ +async function fetchMetricUnitsAndDescriptions({ + clickhouseClient, + databaseName, + tableName, + connectionId, + names, + startDate, + endDate, + hasUnit, + hasDescription, + maxExecutionSeconds, + signal, +}: { + clickhouseClient: Pick; + 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, + // 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 } : {}), + ...(row.MetricDescription ? { description: row.MetricDescription } : {}), + }); + } + 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..f10ae9880c --- /dev/null +++ b/packages/api/src/mcp/tools/sources/listMetricsSchema.ts @@ -0,0 +1,81 @@ +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; + +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); +} + +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/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/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