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
6 changes: 6 additions & 0 deletions .changeset/promql-histogram-heatmap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@hyperdx/common-utils": patch
"@hyperdx/app": patch
---

feat: Support histogram heatmaps from PromQL bucket metrics
13 changes: 7 additions & 6 deletions packages/app/src/components/ChartDisplaySettingsDrawer.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ import { isTimeSeriesDisplayType } from '@hyperdx/common-utils/dist/core/utils';
import {
ChartConfigWithDateRange,
DisplayType,
HeatmapMode,
MAX_LEGEND_TEMPLATE_LENGTH,
NumberFormat,
PromqlHeatmapMode,
} from '@hyperdx/common-utils/dist/types';
import {
Alert,
Expand Down Expand Up @@ -89,8 +89,8 @@ interface ChartDisplaySettingsDrawerProps {
configType?: 'sql' | 'builder' | 'promql';
/** Whether a PromQL tile's queried expression runs over a range. */
promqlUsesRange?: boolean;
/** A builder heatmap's mode; only distribution heatmaps have a numeric y axis to scale. */
heatmapMode?: HeatmapMode;
/** A heatmap's mode; only distribution heatmaps have a numeric y axis to scale. */
heatmapMode?: PromqlHeatmapMode;
/** The heatmap scale used when the tile has none set. */
defaultHeatmapScaleType?: HeatmapScaleType;
previousDateRange?: [Date, Date];
Expand Down Expand Up @@ -227,13 +227,14 @@ export default function ChartDisplaySettingsDrawer({
displayType === DisplayType.Heatmap && heatmapMode === 'distribution';

// Every PromQL display that surfaces a series name. A number tile shows one
// value, a table gives each label its own column, and a distribution heatmap
// merges every series into one, so none has a legend.
// value, a table gives each label its own column, a distribution heatmap
// merges every series into one, and a histogram heatmap labels rows by
// bucket, so none has a legend.
const showLegendTemplate =
configType === 'promql' &&
displayType !== DisplayType.Number &&
displayType !== DisplayType.Table &&
!isDistributionHeatmap;
!(displayType === DisplayType.Heatmap && heatmapMode !== 'series');

// On pie/bar builder charts, seriesLimit becomes a plain SQL LIMIT on the
// number of slices/bars; on PromQL it trims the reduced series client-side
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ import {
import { isTimeSeriesDisplayType } from '@hyperdx/common-utils/dist/core/utils';
import {
DisplayType,
HeatmapMode,
MAX_PROMQL_EXPRESSIONS,
PromqlHeatmapMode,
SourceKind,
} from '@hyperdx/common-utils/dist/types';
import { Box, Button, Divider, Flex, Group, Text } from '@mantine/core';
Expand All @@ -26,6 +26,7 @@ import { useSource } from '@/source';

import PromqlExpressionEditor from './PromqlExpressionEditor';
import { ChartEditorFormState } from './types';
import { promqlExpressionPlaceholder } from './utils';

export default function PromqlChartEditor({
control,
Expand All @@ -41,8 +42,8 @@ export default function PromqlChartEditor({
allowedSourceKinds: SourceKind[];
onSubmit: (suppressErrorNotification?: boolean) => void;
onOpenDisplaySettings: () => void;
heatmapMode: HeatmapMode;
onHeatmapModeChange: (mode: HeatmapMode) => void;
heatmapMode: PromqlHeatmapMode;
onHeatmapModeChange: (mode: PromqlHeatmapMode) => void;
}) {
const {
fields: expressions,
Expand Down Expand Up @@ -118,6 +119,7 @@ export default function PromqlChartEditor({
<HeatmapModeControl
mode={heatmapMode}
onModeChange={onHeatmapModeChange}
allowHistogram
/>
</Box>
)}
Expand All @@ -128,6 +130,7 @@ export default function PromqlChartEditor({
index={index}
length={expressions.length}
metricNames={metricNames}
placeholder={promqlExpressionPlaceholder(displayType, heatmapMode)}
isIgnored={!displayTypeSupportsMultiExpression && index > 0}
isInstantQuerySupported={displayTypeSupportsInstantQuery({
displayType,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ export default function PromqlExpressionEditor({
index,
length,
metricNames,
placeholder,
isIgnored,
isInstantQuerySupported,
isReducerSupported,
Expand All @@ -26,6 +27,7 @@ export default function PromqlExpressionEditor({
index: number;
length: number;
metricNames: string[] | undefined;
placeholder: string;
/** Whether the display type leaves this expression unqueried. */
isIgnored: boolean;
/** Whether the display type lets this expression choose between instant and range queries. */
Expand Down Expand Up @@ -62,7 +64,7 @@ export default function PromqlExpressionEditor({
value={expressionField.value ?? ''}
onChange={expressionField.onChange}
onSubmit={() => onSubmit()}
placeholder="rate(http_requests_total{service='api'}[5m])"
placeholder={placeholder}
metricNames={metricNames}
enableMacros
/>
Expand Down
95 changes: 95 additions & 0 deletions packages/app/src/components/ChartEditor/__tests__/utils.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import {
convertFormStateToSavedChartConfig,
convertSavedChartConfigToFormState,
getAllowedSourceKinds,
promqlExpressionPlaceholder,
validateChartForm,
} from '@/components/ChartEditor/utils';

Expand Down Expand Up @@ -688,6 +689,21 @@ describe('PromQL expressions', () => {
});
});

it('saves a histogram heatmap', () => {
expect(
convertFormStateToSavedChartConfig(
{
...promqlForm(
[{ expression: 'sum by (le) (x_bucket)' }],
DisplayType.Heatmap,
),
heatmap: { mode: 'histogram' },
},
undefined,
),
).toMatchObject({ heatmap: { mode: 'histogram' } });
});

it('queries a heatmap with its heatmap settings', () => {
const result = convertFormStateToChartConfig(
{
Expand Down Expand Up @@ -1929,6 +1945,22 @@ describe('validateChartForm', () => {
expect.objectContaining({ path: 'series.0.valueExpression' }),
);
});

it('requires a value expression on a builder heatmap left in histogram mode', () => {
const errors = validateChartForm(
makeForm({
displayType: DisplayType.Heatmap,
source: 'source-trace',
heatmap: { mode: 'histogram' },
series: [{ ...seriesItem, valueExpression: '' }],
}),
traceSource,
jest.fn(),
);
expect(errors).toContainEqual(
expect.objectContaining({ path: 'series.0.valueExpression' }),
);
});
});

describe('color round-trip (sql/promql Number tile)', () => {
Expand Down Expand Up @@ -2082,6 +2114,41 @@ describe('heatmap round-trip', () => {
});
});

describe('builder heatmap settings', () => {
const form: ChartEditorFormState = {
displayType: DisplayType.Heatmap,
source: 'source-trace',
where: '',
series: [{ ...seriesItem, valueExpression: 'Duration' }],
};

it('fall back to distribution mode from PromQL-only histogram mode', () => {
const histogramForm: ChartEditorFormState = {
...form,
heatmap: { mode: 'histogram', scaleType: 'log' },
};
expect(
convertFormStateToSavedChartConfig(histogramForm, traceSource),
).toHaveProperty('heatmap', { mode: undefined });
expect(
convertFormStateToChartConfig(
histogramForm,
[new Date(0), new Date(1000)],
traceSource,
),
).toHaveProperty('heatmap', { mode: undefined });
});

it('keep series mode, without PromQL-only settings', () => {
expect(
convertFormStateToSavedChartConfig(
{ ...form, heatmap: { mode: 'series', scaleType: 'log' } },
traceSource,
),
).toHaveProperty('heatmap', { mode: 'series' });
});
});

describe('metric formulas (HDX-5080)', () => {
const metricSeriesItem = {
aggFn: 'avg' as const,
Expand Down Expand Up @@ -2489,6 +2556,16 @@ describe('getAllowedSourceKinds', () => {
).toEqual([SourceKind.Trace]);
});

it('treats a leftover histogram mode on a builder heatmap as distribution', () => {
expect(
getAllowedSourceKinds({
configType: 'builder',
displayType: DisplayType.Heatmap,
heatmapMode: 'histogram',
}),
).toEqual([SourceKind.Trace]);
});

it('offers only PromQL sources on PromQL heatmap tiles', () => {
expect(
getAllowedSourceKinds({
Expand All @@ -2499,3 +2576,21 @@ describe('getAllowedSourceKinds', () => {
).toEqual([SourceKind.Promql]);
});
});

describe('promqlExpressionPlaceholder', () => {
it.each([
['distribution', /_sum\[5m\]\) \/ rate\(.*_count/],
['series', /^sum by \(service\)/],
['histogram', /^sum by \(le\) \(rate\(.*_bucket/],
] as const)('suggests a %s heatmap expression', (mode, pattern) => {
expect(promqlExpressionPlaceholder(DisplayType.Heatmap, mode)).toMatch(
pattern,
);
});

it('suggests the same expression on every non-heatmap chart', () => {
expect(promqlExpressionPlaceholder(DisplayType.Line, 'histogram')).toBe(
promqlExpressionPlaceholder(DisplayType.Number, 'distribution'),
);
});
});
8 changes: 6 additions & 2 deletions packages/app/src/components/ChartEditor/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,13 @@ export type SavedChartConfigWithSelectArray = Omit<
* `promqlExpressions` is the PromQL counterpart, holding the array form of
* `promqlExpression` (which a saved tile may carry as a bare string).
**/
export type ChartEditorFormState = Partial<BuilderSavedChartConfig> &
export type ChartEditorFormState = Partial<
Omit<BuilderSavedChartConfig, 'heatmap'>
> &
Partial<Omit<RawSqlSavedChartConfig, 'configType'>> &
Partial<Omit<PromqlSavedChartConfig, 'configType'>> & {
Partial<Omit<PromqlSavedChartConfig, 'configType' | 'heatmap'>> & {
// The PromQL settings are a superset of the builder's.
heatmap?: PromqlSavedChartConfig['heatmap'];
alert?: BuilderSavedChartConfig['alert'] & {
id?: string;
createdBy?: AlertWithCreatedBy['createdBy'];
Expand Down
46 changes: 43 additions & 3 deletions packages/app/src/components/ChartEditor/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ import {
isRangeThresholdType,
isTraceSource,
PromqlChartConfig,
PromqlHeatmapMode,
PromqlSavedChartConfig,
PromqlSeries,
RawSqlChartConfig,
Expand Down Expand Up @@ -228,13 +229,13 @@ export function getAllowedSourceKinds({
}: {
configType: ChartEditorFormState['configType'];
displayType: DisplayType | undefined;
heatmapMode?: HeatmapMode;
heatmapMode?: PromqlHeatmapMode;
}): SourceKind[] {
if (configType === 'promql' && isPromqlDisplayType(displayType)) {
return [SourceKind.Promql];
}
if (displayType === DisplayType.Heatmap) {
return [...getHeatmapSourceKinds(heatmapMode)];
return [...getHeatmapSourceKinds(toBuilderHeatmapMode(heatmapMode))];
}
if (isStringSelectDisplayType(displayType)) {
return ROW_LISTING_SOURCE_KINDS;
Expand Down Expand Up @@ -324,6 +325,7 @@ export function convertFormStateToSavedChartConfig(
'promqlExpression',
'promqlExpressions',
]),
heatmap: formBuilderHeatmap(form),
select: [],
where: form.where ?? '',
source: source?.id ?? form.source ?? '',
Expand All @@ -342,6 +344,7 @@ export function convertFormStateToSavedChartConfig(
'promqlExpression',
'promqlExpressions',
]),
heatmap: formBuilderHeatmap(form),
select: isStringSelectDisplayType(form.displayType)
? typeof form.select === 'string'
? form.select
Expand Down Expand Up @@ -446,6 +449,7 @@ export function convertFormStateToChartConfig(
'promqlExpression',
'promqlExpressions',
]),
heatmap: formBuilderHeatmap(form),
from: source.from,
timestampValueExpression: source.timestampValueExpression,
dateRange,
Expand Down Expand Up @@ -554,6 +558,42 @@ function formPromqlExpressions(form: ChartEditorFormState): PromqlSeries[] {
}));
}

/** The form's heatmap settings, formatted for a builder tile */
function formBuilderHeatmap(
form: ChartEditorFormState,
): BuilderSavedChartConfig['heatmap'] {
return form.heatmap == null
? undefined
: { mode: toBuilderHeatmapMode(form.heatmap.mode) };
}

/** A heatmap mode as a builder heatmap's, which has no histogram mode. */
export function toBuilderHeatmapMode(
mode: PromqlHeatmapMode | undefined,
): HeatmapMode | undefined {
return mode === 'histogram' ? undefined : mode;
}

const DEFAULT_PROMQL_PLACEHOLDER =
"rate(http_requests_total{service='api'}[5m])";

const PROMQL_HEATMAP_PLACEHOLDERS: Record<PromqlHeatmapMode, string> = {
distribution:
'rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m])',
series: 'sum by (service) (rate(http_requests_total[5m]))',
histogram: 'sum by (le) (rate(http_request_duration_seconds_bucket[5m]))',
};

/** An example PromQL expression suited to the display type and heatmap mode. */
export function promqlExpressionPlaceholder(
displayType: DisplayType | undefined,
heatmapMode: PromqlHeatmapMode,
): string {
return displayType === DisplayType.Heatmap
? PROMQL_HEATMAP_PLACEHOLDERS[heatmapMode]
: DEFAULT_PROMQL_PLACEHOLDER;
}

/** Heatmap settings are dropped from PromQL tiles that are not heatmaps. */
function formPromqlHeatmap(
form: ChartEditorFormState,
Expand Down Expand Up @@ -762,7 +802,7 @@ export const validateChartForm = (
!isRawSqlChart &&
!isPromqlChart &&
form.displayType === DisplayType.Heatmap &&
getHeatmapMode(form) === 'distribution' &&
getHeatmapMode({ heatmap: formBuilderHeatmap(form) }) === 'distribution' &&
Array.isArray(form.series) &&
form.series.length > 0 &&
!form.series[0]?.valueExpression
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,8 @@ function HeatmapSQLPreview({
};
const query = toHeatmapQuery(configWithTimestamp);

// Only PromQL heatmaps are calculated, and they have no SQL to preview
if (query.mode === 'calculated') {
// Only PromQL heatmaps are calculated or histograms, and they have no SQL
if (query.mode === 'calculated' || query.mode === 'histogram') {
return null;
}

Expand Down
Loading
Loading