Skip to content
Open
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
4 changes: 2 additions & 2 deletions .changeset/claude-charts-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
---

feat: add a Claude Code plugin that connects the ClickStack MCP server and draws
`clickstack_timeseries` and `clickstack_table` results as terminal charts, using
the CLI's renderers. Install with
`clickstack_timeseries`, `clickstack_table` and `clickstack_heatmap` results as
terminal charts, using the CLI's renderers. Install with
`/plugin install hyperdx-charts --marketplace hyperdxio/hyperdx`.
5 changes: 5 additions & 0 deletions .changeset/cli-heatmap-tiles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@hyperdx/cli': patch
---

feat: `hdx` draws distribution heatmap tiles as shaded terminal charts.
10 changes: 10 additions & 0 deletions .changeset/mcp-distribution-heatmap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@hyperdx/api': patch
'@hyperdx/common-utils': patch
---

feat: add a `clickstack_heatmap` MCP tool that returns how a value such as span
latency is distributed over time, as counts per time bucket and value range.
`clickstack_query_tile` now returns the same grid for distribution heatmap
tiles instead of failing. The distribution heatmap queries the web app runs
moved to common-utils so the API and CLI share them.
1 change: 1 addition & 0 deletions MCP.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ with:
| `clickstack_describe_metric` | Per-metric drill-down: kind(s), unit, description, attribute keys per map column, and sampled values |
| `clickstack_timeseries` | Plot metrics over time as a line or stacked bar chart (works on log, trace, and metric sources) |
| `clickstack_table` | Compute aggregated metrics as a table, single number, or pie chart (works on log, trace, and metric sources) |
| `clickstack_heatmap` | Show how a value such as span latency is distributed over time (trace sources) |
| `clickstack_search` | Browse individual log, event, or trace rows |
| `clickstack_event_patterns` | Discover the most common log messages and event patterns using Drain clustering |
| `clickstack_event_deltas` | Compare two row groups and rank properties by how their value distributions differ |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -103,4 +103,19 @@ describe('withDeadline', () => {
await expect(withDeadline(work, Date.now() + 1000)).resolves.toBe('done');
expect(captured?.aborted).toBe(true);
});

it('summarizes a distribution heatmap by its time buckets', () => {
const counts = [
[0, 2, 0],
[0, 0, 0],
];
expect(summarizeRows(JSON.stringify({ heatmap: { counts } }))).toEqual({
hasData: true,
rowCount: 2,
});
expect(summarizeRows(JSON.stringify({ heatmap: null }))).toEqual({
hasData: false,
rowCount: 0,
});
});
});
259 changes: 259 additions & 0 deletions packages/api/src/mcp/__tests__/heatmapTool.int.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,259 @@
import { SourceKind } from '@hyperdx/common-utils/dist/types';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { ObjectId } from 'mongodb';

import * as config from '@/config';
import {
bulkInsertData,
DEFAULT_DATABASE,
DEFAULT_LOGS_TABLE,
DEFAULT_TRACES_TABLE,
getLoggedInAgent,
getServer,
} from '@/fixtures';
import { McpContext } from '@/mcp/tools/types';
import Connection from '@/models/connection';
import Dashboard from '@/models/dashboard';
import { Source } from '@/models/source';

import { callTool, createTestClient, getFirstText } from './mcpTestUtils';

type HeatmapBody = {
heatmap: {
scale: string;
granularity: string;
numberFormat?: { output: string; factor: number };
times: string[];
valueEdges: number[];
counts: number[][];
} | null;
hints: string[];
};

describe('MCP Heatmap Tool', () => {
const server = getServer();
let client: Client;
let traceSourceId: string;
let logSourceId: string;
// otel_traces is not truncated between tests, so each test filters to its own spans.
let where: string;
const now = Date.now();

beforeAll(async () => {
await server.start();
});

beforeEach(async () => {
const { team, user } = await getLoggedInAgent(server);
const connection = await Connection.create({
team: team._id,
name: 'Default',
host: config.CLICKHOUSE_HOST,
username: config.CLICKHOUSE_USER,
password: config.CLICKHOUSE_PASSWORD,
});
const traceSource = await Source.create({
kind: SourceKind.Trace,
team: team._id,
from: { databaseName: DEFAULT_DATABASE, tableName: DEFAULT_TRACES_TABLE },
timestampValueExpression: 'Timestamp',
connection: connection._id,
name: 'Traces',
traceIdExpression: 'TraceId',
spanIdExpression: 'SpanId',
parentSpanIdExpression: 'ParentSpanId',
spanNameExpression: 'SpanName',
spanKindExpression: 'SpanKind',
durationExpression: 'Duration',
durationPrecision: 9,
serviceNameExpression: 'ServiceName',
statusCodeExpression: 'StatusCode',
statusMessageExpression: 'StatusMessage',
});
const logSource = await Source.create({
kind: SourceKind.Log,
team: team._id,
from: { databaseName: DEFAULT_DATABASE, tableName: DEFAULT_LOGS_TABLE },
timestampValueExpression: 'Timestamp',
connection: connection._id,
name: 'Logs',
});
traceSourceId = traceSource._id.toString();
logSourceId = logSource._id.toString();

const service = `heatmap-${new ObjectId().toString()}`;
where = `ServiceName:"${service}"`;

// A fast mode (~1ms) and a slow tail (~1s), so the heatmap is bimodal.
const durations = [
...Array.from({ length: 50 }, (_, i) => 1e6 + i * 1e3),
...Array.from({ length: 5 }, (_, i) => 1e9 + i * 1e6),
];
await bulkInsertData(
`${DEFAULT_DATABASE}.${DEFAULT_TRACES_TABLE}`,
durations.map((Duration, i) => ({
Timestamp: new Date(now - (i % 5) * 60_000 - 30_000),
TraceId: `trace-${i}`,
SpanId: `span-${i}`,
ParentSpanId: '',
SpanName: 'GET /api',
SpanKind: 'Server',
ServiceName: service,
Duration,
StatusCode: 'Ok',
StatusMessage: '',
SpanAttributes: {},
ResourceAttributes: {},
})),
);

const context: McpContext = {
teamId: team._id.toString(),
userId: user._id.toString(),
};
client = await createTestClient(context);
});

afterEach(async () => {
await client.close();
await server.clearDBs();
});

afterAll(async () => {
await server.stop();
});

it('returns counts per time bucket and value range', async () => {
const result = await callTool(client, 'clickstack_heatmap', {
sourceId: traceSourceId,
valueExpression: 'Duration',
where,
startTime: new Date(now - 10 * 60_000).toISOString(),
endTime: new Date(now).toISOString(),
granularity: '1 minute',
});

expect(result.isError).toBeFalsy();
const body: HeatmapBody = JSON.parse(getFirstText(result));
const heatmap = body.heatmap!;
expect(heatmap.scale).toBe('log');
expect(heatmap.numberFormat).toEqual({ output: 'duration', factor: 1e-9 });
expect(heatmap.counts).toHaveLength(heatmap.times.length);
// One count per bucket plus an under- and overflow count.
for (const column of heatmap.counts) {
expect(column).toHaveLength(heatmap.valueEdges.length + 1);
}
expect(heatmap.counts.flat().reduce((a, b) => a + b, 0)).toBe(55);

// The slow tail lands in a higher value range than the fast mode.
const rowTotals = heatmap.counts.reduce((totals, column) =>
totals.map((total, r) => total + (column.at(r) ?? 0)),
);
const populated = rowTotals.flatMap((n, r) => (n > 0 ? [r] : []));
// Row r counts [valueEdges[r - 1], valueEdges[r]).
expect(heatmap.valueEdges[populated.at(-1)! - 1]).toBeGreaterThan(1e8);
expect(heatmap.valueEdges[populated[0]]).toBeLessThan(1e7);
});

it('rejects a granularity the time buckets cannot step by', async () => {
const result = await callTool(client, 'clickstack_heatmap', {
sourceId: traceSourceId,
valueExpression: 'Duration',
granularity: '1 week',
});
expect(result.isError).toBe(true);
});

it('coarsens a granularity that would flood the grid, and says so', async () => {
const result = await callTool(client, 'clickstack_heatmap', {
sourceId: traceSourceId,
valueExpression: 'Duration',
where,
startTime: new Date(now - 24 * 60 * 60_000).toISOString(),
endTime: new Date(now).toISOString(),
granularity: '1 second',
});
const body: HeatmapBody = JSON.parse(getFirstText(result));
expect(body.heatmap!.times.length).toBeLessThanOrEqual(48 * 4);
expect(body.hints.join(' ')).toContain('Granularity "1 second" would make');
});

it('answers clickstack_query_tile for a saved distribution heatmap tile', async () => {
const saved = await callTool(client, 'clickstack_save_dashboard', {
name: 'Latency',
tiles: [
{
name: 'Span latency',
config: {
displayType: 'heatmap',
sourceId: traceSourceId,
select: [{ valueExpression: 'Duration' }],
where,
},
},
],
});
expect(saved.isError).toBeFalsy();
const dashboard = JSON.parse(getFirstText(saved));

const result = await callTool(client, 'clickstack_query_tile', {
dashboardId: dashboard.id,
tileId: dashboard.tiles[0].id,
startTime: new Date(now - 10 * 60_000).toISOString(),
endTime: new Date(now).toISOString(),
});
expect(result.isError).toBeFalsy();
const body: HeatmapBody = JSON.parse(getFirstText(result));
expect(body.heatmap!.counts.flat().reduce((a, b) => a + b, 0)).toBe(55);
});

it('uses the granularity saved on the tile', async () => {
const saved = await callTool(client, 'clickstack_save_dashboard', {
name: 'Latency',
tiles: [
{
name: 'Span latency',
config: {
displayType: 'heatmap',
sourceId: traceSourceId,
select: [{ valueExpression: 'Duration' }],
where,
},
},
],
});
const dashboard = JSON.parse(getFirstText(saved));
// The external tile format has no granularity; the web editor stores one.
await Dashboard.updateOne(
{ _id: dashboard.id },
{ $set: { 'tiles.0.config.granularity': '1 minute' } },
);

const range = {
dashboardId: dashboard.id,
startTime: new Date(now - 10 * 60_000).toISOString(),
endTime: new Date(now).toISOString(),
};
const single = await callTool(client, 'clickstack_query_tile', {
...range,
tileId: dashboard.tiles[0].id,
});
const body: HeatmapBody = JSON.parse(getFirstText(single));
expect(body.heatmap!.granularity).toBe('1 minute');

// A heatmap summary's rowCount is its number of time buckets.
const batch = await callTool(client, 'clickstack_query_tiles', range);
const [summary] = JSON.parse(getFirstText(batch)).tiles;
expect(summary.rowCount).toBe(body.heatmap!.times.length);
expect(summary.rowCount).toBeLessThanOrEqual(11);
});

it('rejects a non-trace source', async () => {
const result = await callTool(client, 'clickstack_heatmap', {
sourceId: logSourceId,
valueExpression: 'Duration',
});
expect(result.isError).toBe(true);
expect(getFirstText(result)).toContain('need a trace source');
});
});
11 changes: 9 additions & 2 deletions packages/api/src/mcp/tools/dashboards/queryTile.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import { parseTimeRange, runConfigTile } from '@/mcp/tools/query/helpers';
import {
parseTimeRange,
runConfigTile,
savedTileGranularity,
} from '@/mcp/tools/query/helpers';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand Down Expand Up @@ -96,7 +100,10 @@ export function registerQueryTile({
tile,
startDate,
endDate,
{ variables: resolvedVariables.variables },
{
variables: resolvedVariables.variables,
savedGranularity: savedTileGranularity(dashboard.tiles, tileId),
},
);

// Surface non-blocking missing macro and variable warnings alongside
Expand Down
27 changes: 26 additions & 1 deletion packages/api/src/mcp/tools/dashboards/queryTiles.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@ import PQueue from '@esm2cjs/p-queue';
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import { parseTimeRange, runConfigTile } from '@/mcp/tools/query/helpers';
import {
parseTimeRange,
runConfigTile,
savedTileGranularity,
} from '@/mcp/tools/query/helpers';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import { runWithTimeout } from '@/mcp/utils/timeout';
Expand Down Expand Up @@ -127,6 +131,23 @@ export function summarizeRows(text: string): {
} catch {
return {};
}
if (parsed != null && typeof parsed === 'object' && 'heatmap' in parsed) {
// A distribution heatmap: one row per time bucket, null when empty.
const { heatmap } = parsed;
const counts: unknown[] =
heatmap != null &&
typeof heatmap === 'object' &&
'counts' in heatmap &&
Array.isArray(heatmap.counts)
? heatmap.counts
: [];
return {
hasData: counts.some(
column => Array.isArray(column) && column.some(n => n > 0),
),
rowCount: counts.length,
};
}
if (parsed == null || typeof parsed !== 'object' || !('result' in parsed)) {
return {};
}
Expand Down Expand Up @@ -306,6 +327,10 @@ export function registerQueryTiles({
runConfigTile(teamId.toString(), tile, startDate, endDate, {
abortSignal: signal,
variables,
savedGranularity: savedTileGranularity(
dashboard.tiles,
tile.id,
),
}),
deadlineAt,
);
Expand Down
1 change: 1 addition & 0 deletions packages/api/src/mcp/tools/query/builderCatalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
export const BUILDER_TOOLS_LIST = [
' • clickstack_table — aggregations, top-N, single-value KPIs, breakdowns',
' • clickstack_timeseries — trends / metrics over time',
' • clickstack_heatmap — how a value (e.g. latency) is distributed over time',
' • clickstack_search — browsing individual log/trace rows',
' • clickstack_event_patterns — recurring log/event pattern discovery',
' • clickstack_event_deltas — attributes that differ between two row groups',
Expand Down
Loading
Loading