Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .changeset/mcp-list-metrics-speedup.md
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 15 additions & 20 deletions packages/api/src/fixtures.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string>;
ScopeAttributes?: Record<string, string>;
Attributes?: Record<string, string>;
ServiceName: string;
TimeUnix: Date;
Value: number;
}[],
) => {
type NumberMetricPoint = {
MetricName: string;
MetricUnit?: string;
MetricDescription?: string;
ResourceAttributes: Record<string, string>;
ScopeAttributes?: Record<string, string>;
Attributes?: Record<string, string>;
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 😈 !!!');
}
Expand All @@ -470,17 +472,10 @@ export const bulkInsertMetricsGauge = async (
};

export const bulkInsertMetricsSum = async (
metrics: {
metrics: (NumberMetricPoint & {
AggregationTemporality: number;
IsMonotonic: boolean;
MetricName: string;
ResourceAttributes: Record<string, string>;
ScopeAttributes?: Record<string, string>;
Attributes?: Record<string, string>;
ServiceName: string;
TimeUnix: Date;
Value: number;
}[],
})[],
) => {
if (!config.IS_CI) {
throw new Error('ONLY execute this in CI env 😈 !!!');
Expand Down
11 changes: 7 additions & 4 deletions packages/api/src/mcp/__tests__/listMetricsCursor.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down Expand Up @@ -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', () => {
Expand Down
182 changes: 182 additions & 0 deletions packages/api/src/mcp/__tests__/listMetricsPage.test.ts
Original file line number Diff line number Diff line change
@@ -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<string[]>((_, 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 },
]);
});
});
33 changes: 33 additions & 0 deletions packages/api/src/mcp/__tests__/listMetricsQueries.test.ts
Original file line number Diff line number Diff line change
@@ -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',
},
}),
);
});
});
58 changes: 58 additions & 0 deletions packages/api/src/mcp/__tests__/sources.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', {
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading
Loading