diff --git a/.changeset/termchart-legend-matches-chart.md b/.changeset/termchart-legend-matches-chart.md new file mode 100644 index 0000000000..6718872e23 --- /dev/null +++ b/.changeset/termchart-legend-matches-chart.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/cli': patch +--- + +fix: stacked bar charts in `hdx` give palette colors to the largest series +first, list only series that are visible in the legend (with a count of the +rest), color a partial top cell by the series filling most of it, and separate +wide bars with a gap. diff --git a/packages/cli/src/__tests__/chartData.test.ts b/packages/cli/src/__tests__/chartData.test.ts index 888fee1693..95dceecad5 100644 --- a/packages/cli/src/__tests__/chartData.test.ts +++ b/packages/cli/src/__tests__/chartData.test.ts @@ -52,4 +52,26 @@ describe('formatResponseForTimeChart', () => { expect(graphResults.length).toBe(2); }, ); + + it('colors series largest first so the biggest get distinct palette colors', () => { + const { series } = formatResponseForTimeChart({ + response: { + meta: [ + { name: 'ts', type: 'DateTime' }, + { name: 'count()', type: 'UInt64' }, + { name: 'service', type: 'String' }, + ], + data: [ + { ts: '2026-07-02T00:00:00Z', 'count()': '1', service: 'small' }, + { ts: '2026-07-02T00:00:00Z', 'count()': '900', service: 'big' }, + { ts: '2026-07-03T00:00:00Z', 'count()': '50', service: 'mid' }, + ], + rows: 3, + }, + dateRange, + generateEmptyBuckets: false, + }); + expect(series.map(s => s.displayName)).toEqual(['big', 'mid', 'small']); + expect(series[0].color).toBe('blue'); + }); }); diff --git a/packages/cli/src/__tests__/termchart.test.ts b/packages/cli/src/__tests__/termchart.test.ts index 802ac23703..60c051aaac 100644 --- a/packages/cli/src/__tests__/termchart.test.ts +++ b/packages/cli/src/__tests__/termchart.test.ts @@ -1,5 +1,6 @@ import { describe, expect, it } from '@jest/globals'; +import { renderLegend } from '@/termchart/ansi'; import { niceTicks, renderLineChart, @@ -297,4 +298,111 @@ describe('renderStackedBarChart', () => { expect(topRow).toContain('█'); expect(topRow).toContain('100'); }); + + it('leaves series too small to draw out of the legend', () => { + const output = stripAnsi( + renderStackedBarChart({ + data: makeTimeChartData({ + big: [1000, 1000, 1000], + mid: [400, 400, 400], + tiny: [0.001, 0.001, 0.001], + none: [0, 0, 0], + }), + width: 60, + height: 14, + }), + ); + const legend = output.split('\n').at(-1); + expect(legend).toContain('● big'); + expect(legend).toContain('● mid'); + expect(legend).not.toContain('tiny'); + expect(legend).toContain('+2 not shown'); + }); + + it('credits a partial top cell to the series filling most of it, not a sliver on top', () => { + const output = stripAnsi( + renderStackedBarChart({ + data: makeTimeChartData({ + base: [1000, 1000], + sliver: [60, 60], + crumb: [1, 1], + }), + width: 60, + height: 14, + }), + ); + const legend = output.split('\n').at(-1); + expect(legend).toContain('● sliver'); + expect(legend).not.toContain('crumb'); + }); + + it('gives a partial cell to the series covering most of it', () => { + // Top cell holds ~0.26 rows of b, 0.22 of c and 0.12 of d. + const output = stripAnsi( + renderStackedBarChart({ + data: makeTimeChartData({ a: [1000], b: [13], c: [11], d: [6] }), + width: 60, + height: 28, + }), + ); + const legend = output.split('\n').at(-1); + expect(legend).toContain('● b'); + expect(legend).not.toContain('● c'); + }); + + it('keeps the legend and its hidden count within the width', () => { + const name = (c: string) => c.repeat(25); + const output = stripAnsi( + renderStackedBarChart({ + data: makeTimeChartData({ + [name('a')]: [1000, 1000], + [name('b')]: [900, 900], + [name('c')]: [0.001, 0.001], + }), + width: 60, + height: 14, + }), + ); + const legendLines = output.split('\n').slice(-2); + for (const line of legendLines) expect(line.length).toBeLessThanOrEqual(60); + // Both drawn series stay listed; the count moves to the spare legend row. + expect(legendLines[0]).toContain(name('a')); + expect(legendLines[0]).toContain(name('b')); + expect(legendLines[1]).toBe('+1 not shown'); + }); + + it('separates wide bars with a gap column', () => { + const output = stripAnsi( + renderStackedBarChart({ + data: makeTimeChartData({ events: [5, 5, 5] }), + width: 42, + height: 8, + showLegend: false, + }), + ); + const bottomRow = output.split('\n').at(-2)!; + const bars = bottomRow.slice(bottomRow.indexOf('┤') + 1); + expect(bars.trimEnd().split(/ +/)).toHaveLength(3); + }); +}); + +describe('renderLegend', () => { + const series = Array.from({ length: 8 }, (_, i) => ({ + displayName: `service-${i}-${'x'.repeat(12)}`, + color: 'blue', + })); + + it('fits a "+K more" overflow within the width on the last allowed line', () => { + const lines = stripAnsi(renderLegend(series, 60, 2)).split('\n'); + expect(lines).toHaveLength(2); + for (const line of lines) expect(line.length).toBeLessThanOrEqual(60); + const listed = (lines.join(' ').match(/●/g) ?? []).length; + expect(lines[1]).toMatch(new RegExp(`\\+${series.length - listed} more$`)); + }); + + it('counts hidden series in a "+N not shown" tail, even with one line', () => { + const line = stripAnsi(renderLegend(series.slice(0, 2), 60, 1, 3)); + expect(line.length).toBeLessThanOrEqual(60); + expect(line).toMatch(/\+\d+ not shown$/); + }); }); diff --git a/packages/cli/src/shared/chartData.ts b/packages/cli/src/shared/chartData.ts index b4f3fc15db..3dca9f9d94 100644 --- a/packages/cli/src/shared/chartData.ts +++ b/packages/cli/src/shared/chartData.ts @@ -289,6 +289,7 @@ export function formatResponseForTimeChart({ > = {}; const firstGroupIsLogLevel = firstGroupColumnIsLogLevel(source, groupColumns); + const peakByKey = new Map(); for (const row of response.data) { const date = new Date(row[timestampColumn.name] as string | number); @@ -319,6 +320,12 @@ export function formatResponseForTimeChart({ : Number.parseFloat(String(rawValue)); tsBucket[keyName] = value; + if (Number.isFinite(value)) { + peakByKey.set( + keyName, + Math.max(peakByKey.get(keyName) ?? 0, Math.abs(value)), + ); + } // Special handling for log level / trace severity colors let color: string | undefined = undefined; @@ -337,12 +344,15 @@ export function formatResponseForTimeChart({ } } - // Sort log-level series info < warn < error, matching the web ordering + // Sort log-level series info < warn < error, then by peak per series so the + // 8-color palette goes to the largest first. The web ranks by peak only to cap + // series counts, and by group rather than per value column. const logLevelColorOrder = ['green', 'yellow', 'red']; const sortedSeries = Object.values(seriesMap).sort((a, b) => { return ( logLevelColorOrder.findIndex(color => color === a.color) - - logLevelColorOrder.findIndex(color => color === b.color) + logLevelColorOrder.findIndex(color => color === b.color) || + (peakByKey.get(b.dataKey) ?? 0) - (peakByKey.get(a.dataKey) ?? 0) ); }); diff --git a/packages/cli/src/termchart/ansi.ts b/packages/cli/src/termchart/ansi.ts index e8c82c9e91..9ce217e00f 100644 --- a/packages/cli/src/termchart/ansi.ts +++ b/packages/cli/src/termchart/ansi.ts @@ -148,31 +148,58 @@ export function renderLegend( series: Pick[], width: number, maxLines = 2, + /** Series left out before layout (e.g. never drawn), counted in the tail */ + hiddenCount = 0, ): string { - const lines: string[] = []; - let current = ''; - let currentLen = 0; - let shown = 0; - - for (const s of series) { - const label = `● ${truncate(s.displayName, 40)}`; - const sep = currentLen > 0 ? ' ' : ''; - if (currentLen + sep.length + label.length > width) { - lines.push(current); - if (lines.length >= maxLines) { - const remaining = series.length - shown; - if (remaining > 0) { - lines[lines.length - 1] += chalk.dim(` +${remaining} more`); - } - return lines.join('\n'); - } - current = ''; - currentLen = 0; + const labels = series.map(s => ({ + text: `● ${truncate(s.displayName, 40)}`, + color: s.color, + })); + const lines: (typeof labels)[] = [[]]; + const lineLen = (line: typeof labels) => + line.reduce((n, l, i) => n + (i > 0 ? 2 : 0) + l.text.length, 0); + for (const label of labels) { + const last = lines[lines.length - 1]; + if (last.length > 0 && lineLen(last) + 2 + label.text.length > width) { + if (lines.length >= maxLines) break; + lines.push([]); } - current += (currentLen > 0 ? ' ' : '') + chalkColor(s.color)(label); - currentLen += (currentLen > 0 ? 2 : 0) + label.length; - shown++; + lines[lines.length - 1].push(label); } - if (current) lines.push(current); - return lines.join('\n'); + + // The tail must fit on the last line, so drop labels until it does. + const tail = (listed: number) => { + const missing = series.length - listed + hiddenCount; + if (missing <= 0) return ''; + return hiddenCount > 0 ? `+${missing} not shown` : `+${missing} more`; + }; + const listed = () => lines.reduce((n, l) => n + l.length, 0); + const fits = (line: typeof labels) => + lineLen(line) + (line.length > 0 ? 2 : 0) + tail(listed()).length <= width; + if ( + tail(listed()) && + !fits(lines[lines.length - 1]) && + lines.length < maxLines + ) { + lines.push([]); + } + const last = lines[lines.length - 1]; + while ( + tail(listed()) && + last.length > 0 && + lineLen(last) + 2 + tail(listed()).length > width + ) { + last.pop(); + } + + const text = lines.map(line => + line.map(l => chalkColor(l.color)(l.text)).join(' '), + ); + const tailText = tail(listed()); + if (tailText) { + text[text.length - 1] = [text[text.length - 1], chalk.dim(tailText)] + .filter(Boolean) + .join(' '); + } + return text.filter(Boolean).join('\n'); } diff --git a/packages/cli/src/termchart/index.ts b/packages/cli/src/termchart/index.ts index 0468415be2..a84c69697e 100644 --- a/packages/cli/src/termchart/index.ts +++ b/packages/cli/src/termchart/index.ts @@ -16,7 +16,8 @@ export { renderTableChart, } from '@/termchart/charts'; export { niceTicks, resampleSeries } from '@/termchart/scale'; -export { renderLineChart, renderStackedBarChart } from '@/termchart/timeseries'; +export { renderStackedBarChart } from '@/termchart/stackedBar'; +export { renderLineChart } from '@/termchart/timeseries'; export type { CategoricalEntry, TableColumn, diff --git a/packages/cli/src/termchart/stackedBar.ts b/packages/cli/src/termchart/stackedBar.ts new file mode 100644 index 0000000000..8da68ec44f --- /dev/null +++ b/packages/cli/src/termchart/stackedBar.ts @@ -0,0 +1,191 @@ +/** + * Stacked bar (column) renderer: one column per time bucket, series + * stacked largest first. + */ + +import chalk from 'chalk'; + +import { + chalkColor, + defaultFormatValue, + FULL_BLOCK, + NO_DATA_TEXT, + PARTIAL_BLOCKS, + renderLegend, + renderTimeAxis, + truncate, +} from '@/termchart/ansi'; +import { niceTicks, resampleLinear } from '@/termchart/scale'; +import type { RenderTimeChartOptions } from '@/termchart/timeseries'; + +/** + * Render a stacked bar (column) chart. One terminal column per time + * bucket; series stack bottom-up with per-cell colors. + */ +export function renderStackedBarChart({ + data, + width, + height, + formatTick = defaultFormatValue, + showLegend = true, +}: RenderTimeChartOptions): string { + const { graphResults, timestampColumn, series } = data; + if (graphResults.length === 0 || series.length === 0) { + return chalk.dim(NO_DATA_TEXT); + } + + // Sized for every series; the drawn legend lists only those that show up. + const fullLegend = showLegend ? renderLegend(series, width) : ''; + const legendHeight = fullLegend ? fullLegend.split('\n').length + 1 : 0; + + const labelWidth = 10; + const gutterWidth = labelWidth + 2; + const plotHeight = Math.max(2, height - 1 - legendHeight); + const plotWidth = Math.max(10, width - gutterWidth); + + const buckets = graphResults; + + const totals = buckets.map(b => + series.reduce((acc, s) => { + const v = b[s.dataKey]; + return acc + (typeof v === 'number' && Number.isFinite(v) ? v : 0); + }, 0), + ); + const maxTotal = Math.max(...totals, 0); + if (maxTotal <= 0) { + return chalk.dim(NO_DATA_TEXT); + } + + // Nice y-axis: scale bars against a rounded-up axis max and label the + // rows nearest each nice tick (stacked bars are anchored at zero). + const axisTicks = niceTicks(0, maxTotal); + const axisMax = axisTicks.ticks.length > 0 ? axisTicks.niceMax : maxTotal; + const labelByRow = new Map(); + for (const tick of axisTicks.ticks) { + if (tick <= 0) continue; // row 0 spans (0, 1] — no zero baseline row + const row = Math.min( + plotHeight - 1, + Math.max(0, Math.round((tick / axisMax) * plotHeight) - 1), + ); + if (!labelByRow.has(row)) { + labelByRow.set(row, formatTick(tick)); + } + } + + // Map every terminal column to a bucket so the chart fills the full + // plot width. Upscaling (the common case) is a nearest-neighbor + // stretch. When downscaling, each column covers a bucket range — pick + // the range's max-total bucket so spikes are never silently dropped. + const colToBucket = Array.from({ length: plotWidth }, (_, col) => { + const start = Math.min( + buckets.length - 1, + Math.floor((col * buckets.length) / plotWidth), + ); + const end = Math.max( + start + 1, + Math.min( + buckets.length, + Math.floor(((col + 1) * buckets.length) / plotWidth), + ), + ); + let best = start; + for (let j = start + 1; j < end; j++) { + if (totals[j] > totals[best]) best = j; + } + return best; + }); + + // Adjacent bars of similar height read as one block, so leave a gap + // column between buckets once each is wide enough to spare one. + const isGap = (col: number) => + plotWidth >= buckets.length * 3 && + col + 1 < plotWidth && + colToBucket[col + 1] !== colToBucket[col]; + + // Build the grid row by row (top row first) + const drawn = new Set(); + const rows: string[] = []; + for (let row = plotHeight - 1; row >= 0; row--) { + let line = ''; + for (let col = 0; col < plotWidth; col++) { + if (isGap(col)) { + line += ' '; + continue; + } + const bucketIdx = colToBucket[col]; + const bucket = buckets[bucketIdx]; + // Total stacked height of this column, in rows + const totalRows = (totals[bucketIdx] / axisMax) * plotHeight; + if (totalRows <= row) { + line += ' '; + continue; + } + + // The series covering most of the cell's filled part takes it, so a + // partial top cell isn't handed to a thin series stacked on top. + const cellTop = Math.min(row + 1, totalRows); + let cum = 0; + let cellSeries = series[series.length - 1]; + let bestOverlap = 0; + for (const s of series) { + const v = bucket[s.dataKey]; + const sv = typeof v === 'number' && Number.isFinite(v) ? v : 0; + const start = cum; + cum += (sv / axisMax) * plotHeight; + const overlap = Math.min(cum, cellTop) - Math.max(start, row); + if (overlap > bestOverlap) { + bestOverlap = overlap; + cellSeries = s; + } + if (cum >= cellTop) break; + } + drawn.add(cellSeries.dataKey); + const cellColor = cellSeries.color; + + if (totalRows >= row + 1) { + line += chalkColor(cellColor)(FULL_BLOCK); + } else { + const fraction = totalRows - row; + const idx = Math.max(0, Math.min(7, Math.round(fraction * 8) - 1)); + line += chalkColor(cellColor)(PARTIAL_BLOCKS[idx]); + } + } + + // y-axis label on nice tick rows + const label = labelByRow.has(row) + ? truncate(labelByRow.get(row) as string, labelWidth).padStart(labelWidth) + : ' '.repeat(labelWidth); + rows.push(`${chalk.dim(label)} ${chalk.dim('┤')}${line}`); + } + + const timestamps = resampleLinear( + buckets.map(r => (r[timestampColumn.name] ?? 0) as number), + plotWidth, + ).map(ts => Math.round(ts)); + const axis = renderTimeAxis({ + timestamps, + gutterWidth, + plotWidth, + }); + + // Series can go undrawn when they are too thin for a cell or when buckets + // are merged to fit the width; the legend counts them instead of listing them. + const shownSeries = series.filter(s => drawn.has(s.dataKey)); + const legendLines = showLegend + ? renderLegend( + shownSeries, + width, + Math.max(1, legendHeight - 1), + series.length - shownSeries.length, + ) + : ''; + + return [ + rows.join('\n'), + axis, + legendLines ? '' : undefined, + legendLines || undefined, + ] + .filter(part => part !== undefined) + .join('\n'); +} diff --git a/packages/cli/src/termchart/timeseries.ts b/packages/cli/src/termchart/timeseries.ts index b2dea6a7e3..48cd1f5402 100644 --- a/packages/cli/src/termchart/timeseries.ts +++ b/packages/cli/src/termchart/timeseries.ts @@ -1,17 +1,13 @@ /** - * Time-series renderers: multi-series line chart and stacked bar - * (column) chart. Pure functions — shaped data plus dimensions in, ANSI - * string out. + * Time-series line chart renderer. Pure function: shaped data plus + * dimensions in, ANSI string out. Stacked bars live in stackedBar.ts. */ import chalk from 'chalk'; import { - chalkColor, defaultFormatValue, - FULL_BLOCK, NO_DATA_TEXT, - PARTIAL_BLOCKS, PLOT_COLORS, renderLegend, renderTimeAxis, @@ -144,143 +140,3 @@ export function renderLineChart({ .filter(part => part !== undefined) .join('\n'); } - -/** - * Render a stacked bar (column) chart. One terminal column per time - * bucket; series stack bottom-up with per-cell colors. - */ -export function renderStackedBarChart({ - data, - width, - height, - formatTick = defaultFormatValue, - showLegend = true, -}: RenderTimeChartOptions): string { - const { graphResults, timestampColumn, series } = data; - if (graphResults.length === 0 || series.length === 0) { - return chalk.dim(NO_DATA_TEXT); - } - - const legendLines = showLegend ? renderLegend(series, width) : ''; - const legendHeight = legendLines ? legendLines.split('\n').length + 1 : 0; - - const labelWidth = 10; - const gutterWidth = labelWidth + 2; - const plotHeight = Math.max(2, height - 1 - legendHeight); - const plotWidth = Math.max(10, width - gutterWidth); - - const buckets = graphResults; - - const totals = buckets.map(b => - series.reduce((acc, s) => { - const v = b[s.dataKey]; - return acc + (typeof v === 'number' && Number.isFinite(v) ? v : 0); - }, 0), - ); - const maxTotal = Math.max(...totals, 0); - if (maxTotal <= 0) { - return chalk.dim(NO_DATA_TEXT); - } - - // Nice y-axis: scale bars against a rounded-up axis max and label the - // rows nearest each nice tick (stacked bars are anchored at zero). - const axisTicks = niceTicks(0, maxTotal); - const axisMax = axisTicks.ticks.length > 0 ? axisTicks.niceMax : maxTotal; - const labelByRow = new Map(); - for (const tick of axisTicks.ticks) { - if (tick <= 0) continue; // row 0 spans (0, 1] — no zero baseline row - const row = Math.min( - plotHeight - 1, - Math.max(0, Math.round((tick / axisMax) * plotHeight) - 1), - ); - if (!labelByRow.has(row)) { - labelByRow.set(row, formatTick(tick)); - } - } - - // Map every terminal column to a bucket so the chart fills the full - // plot width. Upscaling (the common case) is a nearest-neighbor - // stretch. When downscaling, each column covers a bucket range — pick - // the range's max-total bucket so spikes are never silently dropped. - const colToBucket = Array.from({ length: plotWidth }, (_, col) => { - const start = Math.min( - buckets.length - 1, - Math.floor((col * buckets.length) / plotWidth), - ); - const end = Math.max( - start + 1, - Math.min( - buckets.length, - Math.floor(((col + 1) * buckets.length) / plotWidth), - ), - ); - let best = start; - for (let j = start + 1; j < end; j++) { - if (totals[j] > totals[best]) best = j; - } - return best; - }); - - // Build the grid row by row (top row first) - const rows: string[] = []; - for (let row = plotHeight - 1; row >= 0; row--) { - let line = ''; - for (let col = 0; col < plotWidth; col++) { - const bucketIdx = colToBucket[col]; - const bucket = buckets[bucketIdx]; - // Total stacked height of this column, in rows - const totalRows = (totals[bucketIdx] / axisMax) * plotHeight; - if (totalRows <= row) { - line += ' '; - continue; - } - - // Which series occupies this row? Find via cumulative heights. - let cum = 0; - let cellColor = series[series.length - 1].color; - const target = Math.min(row + 0.5, totalRows - 0.001); - for (const s of series) { - const v = bucket[s.dataKey]; - const sv = typeof v === 'number' && Number.isFinite(v) ? v : 0; - cum += (sv / axisMax) * plotHeight; - if (cum > target) { - cellColor = s.color; - break; - } - } - - if (totalRows >= row + 1) { - line += chalkColor(cellColor)(FULL_BLOCK); - } else { - const fraction = totalRows - row; - const idx = Math.max(0, Math.min(7, Math.round(fraction * 8) - 1)); - line += chalkColor(cellColor)(PARTIAL_BLOCKS[idx]); - } - } - - // y-axis label on nice tick rows - const label = labelByRow.has(row) - ? truncate(labelByRow.get(row) as string, labelWidth).padStart(labelWidth) - : ' '.repeat(labelWidth); - rows.push(`${chalk.dim(label)} ${chalk.dim('┤')}${line}`); - } - - const timestamps = resampleLinear( - buckets.map(r => (r[timestampColumn.name] ?? 0) as number), - plotWidth, - ).map(ts => Math.round(ts)); - const axis = renderTimeAxis({ - timestamps, - gutterWidth, - plotWidth, - }); - - return [ - rows.join('\n'), - axis, - legendLines ? '' : undefined, - legendLines || undefined, - ] - .filter(part => part !== undefined) - .join('\n'); -}