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
7 changes: 7 additions & 0 deletions .changeset/markdown-tile-variables.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@hyperdx/common-utils': patch
'@hyperdx/app': patch
'@hyperdx/api': patch
---

feat: Substitute dashboard variables in markdown tiles
10 changes: 5 additions & 5 deletions packages/api/src/mcp/__tests__/dashboards/validation.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -790,19 +790,19 @@ describe('getTileVariableWarnings', () => {
expect(warnings.join('\n')).toContain('(none)');
});

it('ignores markdown tiles, which have no expressions to check', () => {
it('warns about an unknown variable in a markdown tile', () => {
const markdownTile: ExternalDashboardTileWithId = {
id: 'md',
x: 0,
y: 0,
w: 12,
h: 3,
name: 'Notes',
config: { displayType: 'markdown', markdown: 'Pick a $service' },
config: { displayType: 'markdown', markdown: '# $service on $env' },
};
expect(getTileVariableWarnings([markdownTile], [variableFilter])).toEqual(
[],
);
expect(getTileVariableWarnings([markdownTile], [variableFilter])).toEqual([
'Tile "Notes": The markdown references unknown variable $env. Available variables: service.',
]);
});
});

Expand Down
8 changes: 7 additions & 1 deletion packages/api/src/mcp/prompts/dashboards/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -991,7 +991,7 @@ For configType: "sql" tiles, write ClickHouse SQL with template macros:
table 1 to 20 select items. Optional groupBy defines row groups. Per-series numberFormat lets one column render as a duration while a sibling count column stays a plain number.
heatmap Exactly 1 select item with a non-empty valueExpression. No aggFn or alias on the select item (the chart-level displayType: "heatmap" is the discriminator). Trace sources only (no Log/Metric/Session). No groupBy. Optional where filter applied before bucketing.
search No select items (select is a column list string). where is the filter.
markdown No select items. Set markdown field with content.
markdown No select items. Set markdown field with content, which may reference dashboard variables (see DASHBOARD VARIABLES).
== METRIC SOURCES ==
Expand Down Expand Up @@ -1221,6 +1221,7 @@ Only add one when the default is wrong. \${service:sqlstring} is redundant in a
lucene ("a" OR "b") ("") the default in Lucene inputs; ("") is a match-all, so no guard is needed
regex (a|b) .* use with match()
csv a,b <empty> use INSIDE a string literal
markdown a, b <empty> the default in markdown tiles; markdown syntax in values is escaped
BUILDER TILES
Expand All @@ -1234,6 +1235,11 @@ In a LUCENE input the macros have no meaning and are matched as literal text. Re
select: [{ aggFn: "count", whereLanguage: "lucene", where: "ServiceName:$service" }]
When in doubt on a variable-driven tile, set whereLanguage: "sql" and use $__filter.
MARKDOWN TILES
The markdown field substitutes $variableName / \${variableName} / \${variableName:format} with the selected values as plain text, so a note can name what the dashboard is scoped to. Nothing is selected on a freshly-opened dashboard, so the reference renders as nothing until the user picks a value; write the surrounding text so it still reads. The macros have no meaning here and are left as written.
markdown: "Latency for the selected services: $service"
RAW SQL TILES (for advanced use-cases only)
SELECT $__timeInterval(Timestamp) AS ts, count() AS errors
Expand Down
23 changes: 19 additions & 4 deletions packages/api/src/mcp/tools/dashboards/validation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ import {
DisplayType,
QueryExpressionDashboardFilter,
SavedChartConfig,
SearchConditionLanguage,
} from '@hyperdx/common-utils/dist/types';
import {
getVariableReferences,
mapBuilderVariableTemplates,
TemplateLanguage,
validateVariableReferencesInTemplate,
} from '@hyperdx/common-utils/dist/variables';

Expand Down Expand Up @@ -244,6 +244,19 @@ export function getFilterVariableWarnings(
return warnings;
}

function variableIssueSubject(language: TemplateLanguage): string {
switch (language) {
case 'sql':
return 'SQL';
case 'lucene':
return 'The Lucene filter';
case 'promql':
return 'The PromQL expression';
case 'markdown':
return 'The markdown';
}
}

/**
* Non-blocking checks on the dashboard variables a tile's expressions
* reference, run against the variables the dashboard's filters actually
Expand Down Expand Up @@ -273,9 +286,9 @@ export function getTileVariableWarnings(
}

const issues: string[] = [];
const validate = (template: string, language: SearchConditionLanguage) => {
const validate = (template: string, language: TemplateLanguage) => {
const result = validateVariableReferencesInTemplate(template, variables, {
subject: language === 'lucene' ? 'The Lucene filter' : 'SQL',
subject: variableIssueSubject(language),
language,
});
issues.push(...result.errors, ...result.warnings);
Expand All @@ -285,8 +298,10 @@ export function getTileVariableWarnings(
validate(config.sqlTemplate, 'sql');
} else if (
isBuilderSavedChartConfig(config) &&
config.displayType !== DisplayType.Markdown
config.displayType === DisplayType.Markdown
) {
if (config.markdown) validate(config.markdown, 'markdown');

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — MCP warns about $word prose in markdown even when the dashboard has no variables

HDXMarkdownChart deliberately skips validation when !variables?.length, because nothing is substituted and $HOME or $PATH in a runbook note is just prose. getTileVariableWarnings still validates against [], so every markdown tile with a $word gets 'unknown variable … Available variables: (none)'. Skip the markdown validation when variables.length === 0 so it matches the UI.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Comment thread
pulpdrew marked this conversation as resolved.
Resolved
Comment thread
pulpdrew marked this conversation as resolved.
Resolved
} else if (isBuilderSavedChartConfig(config)) {
mapBuilderVariableTemplates(config, (template, language) => {
validate(template, language);
return template;
Expand Down
19 changes: 19 additions & 0 deletions packages/app/src/DBDashboardPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -596,6 +596,21 @@ const Tile = ({
[serializedTileVariables],
);

// Serialized for the same reason as `tileVariables`. Markdown tiles flag
// references to names outside this list, which `tileVariables` filters out.
const serializedVariableNames = useMemo(
() =>
variables
? JSON.stringify(variables.map(variable => variable.name))
: undefined,
[variables],
);
const variableNames = useMemo<string[] | undefined>(
() =>
serializedVariableNames ? JSON.parse(serializedVariableNames) : undefined,
[serializedVariableNames],
);

// Serialized for the same reason as `tileVariables`: any change to the
// dashboard's filters hands this tile a new array, and only a change to the
// names this tile is blocked on should churn the render memo below.
Expand Down Expand Up @@ -1377,6 +1392,8 @@ const Tile = ({
title={title}
toolbarItems={toolbar}
config={effectiveMarkdownConfig}
variables={tileVariables}
availableVariableNames={variableNames}
/>
)}
{effectiveQueriedConfig?.displayType === DisplayType.Search &&
Expand Down Expand Up @@ -1495,6 +1512,8 @@ const Tile = ({
annotations,
isLive,
readOnly,
tileVariables,
variableNames,
],
);

Expand Down
60 changes: 57 additions & 3 deletions packages/app/src/HDXMarkdownChart.tsx
Original file line number Diff line number Diff line change
@@ -1,28 +1,82 @@
import { memo } from 'react';
import { memo, useMemo } from 'react';
import ReactMarkdown from 'react-markdown';
import { ChartVariable } from '@hyperdx/common-utils/dist/types';
import {
substituteVariables,
validateVariableReferencesInTemplate,
} from '@hyperdx/common-utils/dist/variables';

import ChartContainer from './components/charts/ChartContainer';
import {
hasVariableIssues,
VariableIssueIndicator,
} from './components/SQLEditor/variableValidation';

const HDXMarkdownChart = memo(
({
config: { markdown },
title,
toolbarItems,
variables: referencedVariables,
availableVariableNames,
}: {
title?: React.ReactNode;
toolbarItems?: React.ReactNode[];
config: {
markdown?: string;
};
/** The variables to substitute. Limited to the ones this chart references. */
variables?: ChartVariable[];
/** Every variable name in scope, for flagging unknown references. */
availableVariableNames?: string[];
}) => {
const content = useMemo(() => {
if (!markdown || referencedVariables == null) return markdown ?? '';
try {
return substituteVariables(markdown, {
variables: referencedVariables,
inputLanguage: 'markdown',
});
Comment thread
pulpdrew marked this conversation as resolved.
Resolved
} catch {
// An unknown `${name:format}` throws; show the markdown as written.
return markdown;
}
}, [markdown, referencedVariables]);

const toolbar = useMemo(() => {
const names =
availableVariableNames ??
referencedVariables?.map(variable => variable.name);

// Without variables in scope nothing is substituted, so a `$word` is prose.
if (!markdown || !names?.length) return toolbarItems;

// Only names are checked for markdown, so the selections don't matter.
const allVariables = names.map(name => ({ name, values: [] }));
const issues = validateVariableReferencesInTemplate(
markdown,
allVariables,
{
subject: 'Markdown',
language: 'markdown',
},
);
if (!hasVariableIssues(issues)) return toolbarItems;

return [
<VariableIssueIndicator key="variable-issues" issues={issues} />,
...(toolbarItems ?? []),
];
}, [markdown, availableVariableNames, referencedVariables, toolbarItems]);

return (
<ChartContainer
title={title}
toolbarItems={toolbarItems}
toolbarItems={toolbar}
disableReactiveContainer
>
<div className="hdx-markdown">
<ReactMarkdown>{markdown ?? ''}</ReactMarkdown>
<ReactMarkdown>{content}</ReactMarkdown>
</div>
</ChartContainer>
);
Expand Down
73 changes: 73 additions & 0 deletions packages/app/src/__tests__/HDXMarkdownChart.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
import React from 'react';
import { screen } from '@testing-library/react';

import HDXMarkdownChart from '@/HDXMarkdownChart';

const service = { name: 'service', values: ['api', 'web'] };

describe('HDXMarkdownChart', () => {
it('substitutes variable references', () => {
renderWithMantine(
<HDXMarkdownChart
config={{ markdown: '# Services: $service' }}
variables={[service]}
/>,
);
expect(screen.getByText('# Services: api, web')).toBeInTheDocument();
Comment thread
pulpdrew marked this conversation as resolved.
Resolved
});

it('renders the markdown as written without variables', () => {
renderWithMantine(
<HDXMarkdownChart config={{ markdown: '# Services: $service' }} />,
);
expect(screen.getByText('# Services: $service')).toBeInTheDocument();
});

it('renders the markdown as written when a format is unknown', () => {
renderWithMantine(
<HDXMarkdownChart
config={{ markdown: '${service:nope}' }}
variables={[service]}
/>,
);
expect(screen.getByText('${service:nope}')).toBeInTheDocument();
});

it('flags a reference to an unknown variable', () => {
renderWithMantine(
<HDXMarkdownChart
config={{ markdown: '$service $nope' }}
variables={[service]}
/>,
);
expect(screen.getByTestId('variable-validation')).toHaveAccessibleName(
'Markdown references unknown variable $nope. Available variables: service.',
);
});

it('checks references against the available names when given', () => {
renderWithMantine(
<HDXMarkdownChart
config={{ markdown: '$service $env' }}
variables={[service]}
availableVariableNames={['service', 'env']}
/>,
);
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
});

it('flags nothing when every reference is known', () => {
renderWithMantine(
<HDXMarkdownChart
config={{ markdown: '$service' }}
variables={[service]}
/>,
);
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
});

it('flags nothing without variables', () => {
renderWithMantine(<HDXMarkdownChart config={{ markdown: '$nope' }} />);
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
});
});
Original file line number Diff line number Diff line change
Expand Up @@ -1090,6 +1090,7 @@ export default function EditTimeChartForm({
config={{
markdown: markdown || 'Preview',
}}
variables={variables}
/>
</Box>
</div>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,11 +65,12 @@ describe('buildPromqlVariableCompletions', () => {
expect(labels([SERVICE])).not.toContain('$__filter($service)');
});

it('withholds the formats that emit SQL or Lucene syntax', () => {
it('withholds the formats that emit SQL, Lucene, or markdown syntax', () => {
// Still honoured if hand-typed — just never suggested, because neither
// `'api', 'web'` nor `("api" OR "web")` parses inside a PromQL expression.
expect(labels([SERVICE])).not.toContain('${service:sqlstring}');
expect(labels([SERVICE])).not.toContain('${service:lucene}');
expect(labels([SERVICE])).not.toContain('${service:markdown}');
});

it('offers the same set of forms for every variable', () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ describe('buildSqlVariableCompletions', () => {
);
});

it('withholds the markdown format, which only applies to markdown tiles', () => {
expect(labels([SERVICE])).not.toContain('${service:markdown}');
});

it('withholds the macros that a chart builder input never expands', () => {
// Only the variable macros are substituted into builder expressions, so
// offering $__timeFilter and friends here would suggest SQL that reaches
Expand Down
Loading
Loading