Repository navigation
feat(promql): a query_promql MCP tool #2665
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
+859
−1
Open
Changes from all commits
Commits
Show all changes
30 commits
Select commit
Hold shift + click to select a range
2d925ab
feat(promql): a query_promql MCP tool
Makisuo 94b6911
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 2a31d37
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 291cc4a
fix(promql): rank infinite peaks when capping, and refuse a zero step
Makisuo 7638eef
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo eb36576
fix(promql): suggest a sub-second step the tool accepts
Makisuo cd67e5b
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 8700188
fix(promql): escape series names once in query_promql tables
Makisuo 42dcf2f
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 6a6b571
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo eadf875
fix(promql): an empty instant result points at end_time, not start_time
Makisuo 4583d20
fix(promql): seconds in sampled times, infinities in the statistics
Makisuo ea0c9e9
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo af53b47
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 1ec418c
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo bbb4c0f
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 1059ed4
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo b10e1a3
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 0f53ecc
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 812048f
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 721a0b4
fix(ai): MCP request writes pick the live server when they run, not w…
Makisuo 1766b66
fix(promql): query_promql quotes label values in series names
Makisuo 913e198
fix(promql): query_promql blames a too-fine step on step, prints step…
Makisuo 41309d6
chore(promql): escape label values with one character class
Makisuo f580c64
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 64561ca
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo 3e8a051
test(promql): assert sampled times keep their seconds in the point list
Makisuo 1000ab4
Merge branch 'promql/3-pushdown' into promql/4-mcp
Makisuo c485dee
fix(promql): query_promql's step gate counts the window's end point, …
Makisuo bb15f5f
fix(promql): query_promql's min/avg/max cover every point, not only t…
Makisuo File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,197 @@ | ||
| // query_promql's model-facing text: per series its labels, summary stats and a few points. | ||
| import { Array as Arr, Option, Order, pipe, Record as Rec, String as Str } from "effect" | ||
| import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" | ||
| import { formatNumber, tableCell, truncate } from "./format" | ||
| import { doc, type DocBlock, type NextCall, type ToolDoc } from "./tool-doc" | ||
| import { MAX_POINTS } from "./promql-result" | ||
|
|
||
| type Output = typeof QueryPromqlOutput.Type | ||
| type Series = typeof PromqlSeries.Type | ||
|
|
||
| /** Series that also list sampled points, and how many points each. */ | ||
| const DETAILED_SERIES = 5 | ||
| const SAMPLED_POINTS = 6 | ||
|
|
||
| export const formatSample = (value: typeof PromqlSampleValue.Type): string => { | ||
| if (typeof value === "string") return value | ||
| if (Number.isInteger(value)) return formatNumber(value) | ||
| const abs = Math.abs(value) | ||
| return abs >= 1000 ? formatNumber(Math.round(value * 100) / 100) : String(Number(value.toPrecision(4))) | ||
| } | ||
|
|
||
| /** `MM-DD HH:MM:SS`, UTC, with milliseconds when a step is finer than a second. */ | ||
| const formatTime = (ms: number): string => | ||
| Str.replace("T", " ")(Str.slice(5, ms % 1000 === 0 ? 19 : 23)(new Date(ms).toISOString())) | ||
|
|
||
| /** A label value as Prometheus quotes it: backslash, double quote and newline escaped. */ | ||
| const escapeLabelValue = (value: string): string => | ||
| pipe(value, Str.replace(/[\\"]/g, "\\$&"), Str.replace(/\n/g, "\\n")) | ||
|
|
||
| /** `name{k="v", ...}`, the way Prometheus prints a series. */ | ||
| export const seriesName = (labels: Series["labels"]): string => { | ||
| const name = labels.__name__ ?? "" | ||
| const rest = Arr.sort( | ||
| Arr.filter(Rec.toEntries(labels), ([key]) => key !== "__name__"), | ||
| Order.mapInput(Order.String, ([key]: readonly [string, string]) => key), | ||
| ) | ||
| const inner = Arr.join( | ||
| Arr.map(rest, ([key, value]) => `${key}="${escapeLabelValue(value)}"`), | ||
| ", ", | ||
| ) | ||
| return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` | ||
| } | ||
|
|
||
| const stats = (series: Series) => | ||
| series.stats === undefined | ||
| ? { min: "-", avg: "-", max: "-" } | ||
| : { | ||
| min: formatSample(series.stats.min), | ||
| avg: formatSample(series.stats.avg), | ||
| max: formatSample(series.stats.max), | ||
| } | ||
|
|
||
| const lastValue = (series: Series): string => | ||
| Option.match(Arr.last(series.points), { onNone: () => "-", onSome: (p) => formatSample(p.v) }) | ||
|
|
||
| /** Evenly spaced points across the series, its last point included. */ | ||
| const sampled = (series: Series): string => { | ||
| const n = series.points.length | ||
| const stride = Math.max(1, Math.ceil(n / SAMPLED_POINTS)) | ||
| const picked = Arr.filter(series.points, (_, i) => (n - 1 - i) % stride === 0) | ||
| return Arr.join( | ||
| Arr.map(Arr.takeRight(picked, SAMPLED_POINTS), (p) => `${formatTime(p.t)} ${formatSample(p.v)}`), | ||
| ", ", | ||
| ) | ||
| } | ||
|
|
||
| const matrixBlocks = (series: ReadonlyArray<Series>): ReadonlyArray<DocBlock> => [ | ||
| doc.table( | ||
| ["Series", "Points", "Min", "Avg", "Max", "Last"], | ||
| Arr.map(series, (s) => { | ||
| const { min, avg, max } = stats(s) | ||
| return [ | ||
| truncate(seriesName(s.labels), 100), | ||
| formatNumber(s.totalPoints), | ||
| min, | ||
| avg, | ||
| max, | ||
| lastValue(s), | ||
| ] | ||
| }), | ||
| ), | ||
| doc.list( | ||
| Arr.map( | ||
| Arr.take(series, DETAILED_SERIES), | ||
| // Table cells are escaped by the renderer; list items are not. | ||
| (s) => `${tableCell(seriesName(s.labels), 100)}: ${sampled(s)}`, | ||
| ), | ||
| ), | ||
| ] | ||
|
|
||
| const bodyOf = (output: Output): ReadonlyArray<DocBlock> => { | ||
| switch (output.resultType) { | ||
| case "matrix": | ||
| return output.series.length === 0 ? [] : matrixBlocks(output.series) | ||
| case "vector": | ||
| return output.series.length === 0 | ||
| ? [] | ||
| : [ | ||
| doc.table( | ||
| ["Series", "Value"], | ||
| Arr.map(output.series, (s) => [ | ||
| truncate(seriesName(s.labels), 100), | ||
| lastValue(s), | ||
| ]), | ||
| ), | ||
| ] | ||
| case "scalar": | ||
| return [ | ||
| doc.fields([ | ||
| [ | ||
| "Value", | ||
| Option.match(Arr.head(output.series), { onNone: () => "-", onSome: lastValue }), | ||
| ], | ||
| ]), | ||
| ] | ||
| case "string": | ||
| return [doc.fields([["Value", output.stringValue]])] | ||
| } | ||
| } | ||
|
|
||
| /** Rerun with the series summed per service; only for expressions that yield instant vectors. */ | ||
| const aggregateNext = (output: Output): NextCall | undefined => | ||
| output.resultType === "vector" || (output.resultType === "matrix" && !output.instant) | ||
| ? doc.next( | ||
| "query_promql", | ||
| { | ||
| query: `sum by (job) (${output.query})`, | ||
| start_time: output.timeRange.start, | ||
| end_time: output.timeRange.end, | ||
| ...(output.instant ? { instant: true } : { step: stepText(output.stepSeconds) }), | ||
| }, | ||
| "fewer series: one per service", | ||
| ) | ||
| : undefined | ||
|
|
||
| /** A step the tool's own `step` parameter accepts: whole seconds, or ms below a second. */ | ||
| const stepText = (seconds: number): string => | ||
| Number.isInteger(seconds) ? `${seconds}s` : `${Math.round(seconds * 1000)}ms` | ||
|
|
||
| export const renderPromqlOutput = (output: Output): ToolDoc => { | ||
| const empty = output.resultType !== "string" && output.series.length === 0 | ||
| const clipped = Arr.some(output.series, (s) => s.totalPoints > s.points.length) | ||
| const aggregate = aggregateNext(output) | ||
| return { | ||
| title: "PromQL Result", | ||
| scope: [ | ||
| ["Query", output.query], | ||
| ["Type", output.resultType], | ||
| output.instant | ||
| ? ["At", output.timeRange.end] | ||
| : ["Window", `${output.timeRange.start} to ${output.timeRange.end}`], | ||
| ["Step", output.instant ? undefined : stepText(output.stepSeconds)], | ||
| ], | ||
| blocks: bodyOf(output), | ||
| ...(empty | ||
| ? { | ||
| empty: { | ||
| message: "No series matched this query in the window.", | ||
| hints: [ | ||
| "Names are Prometheus-style: `http.server.request.duration` (s) is `http_server_request_duration_seconds_bucket`/`_count`/`_sum`, a monotonic sum ends in `_total`.", | ||
| // An instant query reads only the 5 minutes before end_time; start_time cannot help it. | ||
| output.instant | ||
| ? "Labels use underscores (`host_name`); `job` is the service name. An instant query reads the 5 minutes before end_time: move end_time, or check names with list_metrics." | ||
| : "Labels use underscores (`host_name`); `job` is the service name. Widen start_time, or check names with list_metrics.", | ||
| ], | ||
| }, | ||
| } | ||
| : undefined), | ||
| ...(output.totalSeries > output.series.length | ||
| ? { | ||
| truncation: { | ||
| shown: output.series.length, | ||
| total: output.totalSeries, | ||
| noun: "series (highest peaks kept)", | ||
| }, | ||
| } | ||
| : undefined), | ||
| ...(clipped | ||
| ? { | ||
| notices: [ | ||
| `Each series shows its last ${MAX_POINTS} points; a coarser step covers the whole window.`, | ||
| ], | ||
| } | ||
| : undefined), | ||
| next: empty | ||
| ? [ | ||
| doc.next( | ||
| "list_metrics", | ||
| { start_time: output.timeRange.start, end_time: output.timeRange.end }, | ||
| "find the metric's OTel name", | ||
| ), | ||
| ] | ||
| : output.totalSeries > output.series.length && aggregate !== undefined | ||
| ? [aggregate] | ||
| : [], | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| // Turns a PromQL evaluation into query_promql's output: steps, capped series, encoded values. | ||
| import { Array as Arr, Option, Order, String as Str, type Context, type Effect } from "effect" | ||
| import type { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" | ||
| import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" | ||
|
|
||
| export type PromqlResult = Effect.Success< | ||
| ReturnType<Context.Service.Shape<typeof PromqlQueryService>["query"]> | ||
| > | ||
|
|
||
| export const MAX_SERIES = 20 | ||
| export const MAX_POINTS = 200 | ||
|
|
||
| const unitSeconds = (unit: string | undefined): number => { | ||
| switch (unit) { | ||
| case "ms": | ||
| return 0.001 | ||
| case "m": | ||
| return 60 | ||
| case "h": | ||
| return 3600 | ||
| case "d": | ||
| return 86_400 | ||
| case "w": | ||
| return 604_800 | ||
| case "y": | ||
| return 31_536_000 | ||
| default: | ||
| return 1 | ||
| } | ||
| } | ||
|
|
||
| const DURATION = /^(?:\d+(?:ms|s|m|h|d|w|y))+$/ | ||
| const DURATION_PART = /(\d+)(ms|s|m|h|d|w|y)/g | ||
|
|
||
| /** A Prometheus duration (`1m`, `1h30m`) or float seconds, in seconds; undefined when neither. */ | ||
| export const parseStepSeconds = (raw: string): number | undefined => { | ||
| const text = Str.trim(raw) | ||
| if (DURATION.test(text)) { | ||
| const seconds = Arr.reduce(Arr.fromIterable(Str.matchAll(DURATION_PART)(text)), 0, (total, part) => { | ||
| return total + Number(part[1]) * unitSeconds(part[2]) | ||
| }) | ||
| return seconds > 0 ? seconds : undefined | ||
| } | ||
| const seconds = Number(text) | ||
| return text !== "" && Number.isFinite(seconds) && seconds > 0 ? seconds : undefined | ||
| } | ||
|
|
||
| const NICE_STEPS = [15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 10_800, 21_600, 43_200, 86_400] | ||
|
|
||
| /** The smallest round step that keeps a range at no more than 120 points. */ | ||
| export const defaultStepSeconds = (rangeSeconds: number): number => | ||
| Option.getOrElse( | ||
| Arr.findFirst(NICE_STEPS, (step) => rangeSeconds / step <= 120), | ||
| () => Math.ceil(rangeSeconds / 120), | ||
| ) | ||
|
|
||
| /** Prometheus' spelling of a non-finite sample, so the output survives JSON. */ | ||
| export const encodeSample = (value: number): typeof PromqlSampleValue.Type => | ||
| Number.isFinite(value) ? value : Number.isNaN(value) ? "NaN" : value > 0 ? "+Inf" : "-Inf" | ||
|
|
||
| interface RawSeries { | ||
| readonly labels: Readonly<Record<string, string>> | ||
| readonly points: ReadonlyArray<{ readonly t: number; readonly v: number }> | ||
| } | ||
|
|
||
| const rawSeries = (result: PromqlResult): ReadonlyArray<RawSeries> => { | ||
| switch (result.resultType) { | ||
| case "matrix": | ||
| return result.result | ||
| case "vector": | ||
| return Arr.map(result.result, (s) => ({ labels: s.labels, points: [{ t: s.t, v: s.value }] })) | ||
| case "scalar": | ||
| return [{ labels: {}, points: [result.result] }] | ||
| case "string": | ||
| return [] | ||
| } | ||
| } | ||
|
|
||
| const peak = (series: RawSeries): number => | ||
| Arr.reduce(series.points, Number.NEGATIVE_INFINITY, (max, p) => | ||
| // NaN never ranks; +Inf (a division by zero) ranks highest, as the peak it is. | ||
| !Number.isNaN(p.v) && p.v > max ? p.v : max, | ||
| ) | ||
|
|
||
| // Peaks are computed once per series, not once per comparison. | ||
| const byPeakDescending = Order.mapInput( | ||
| Order.flip(Order.Number), | ||
| ([max]: readonly [number, RawSeries]) => max, | ||
| ) | ||
|
|
||
| /** Over {@link MAX_SERIES}, the series with the highest peaks; each keeps its last {@link MAX_POINTS} points. */ | ||
| export const capSeries = (result: PromqlResult): ReadonlyArray<typeof PromqlSeries.Type> => { | ||
| const all = rawSeries(result) | ||
| const kept = | ||
| all.length > MAX_SERIES | ||
| ? Arr.map( | ||
| Arr.take( | ||
| Arr.sort( | ||
| Arr.map(all, (series) => [peak(series), series] as const), | ||
| byPeakDescending, | ||
| ), | ||
| MAX_SERIES, | ||
| ), | ||
| ([, series]) => series, | ||
| ) | ||
| : all | ||
| return Arr.map(kept, (series) => { | ||
| const stats = seriesStats(series) | ||
| return { | ||
| labels: series.labels, | ||
| points: Arr.map(Arr.takeRight(series.points, MAX_POINTS), (p) => ({ | ||
| t: p.t, | ||
| v: encodeSample(p.v), | ||
| })), | ||
| totalPoints: series.points.length, | ||
| ...(stats === undefined ? undefined : { stats }), | ||
| } | ||
| }) | ||
| } | ||
|
|
||
| /** Min, average and max over every point before the cap; infinities count, NaN does not. */ | ||
| const seriesStats = (series: RawSeries) => { | ||
| const values = Arr.filter( | ||
| Arr.map(series.points, (p) => p.v), | ||
| (v) => !Number.isNaN(v), | ||
| ) | ||
| if (values.length === 0) return undefined | ||
| const sum = Arr.reduce(values, 0, (a, b) => a + b) | ||
| return { | ||
| min: encodeSample(Arr.reduce(values, Infinity, (a, b) => Math.min(a, b))), | ||
| avg: encodeSample(sum / values.length), | ||
| max: encodeSample(Arr.reduce(values, -Infinity, (a, b) => Math.max(a, b))), | ||
| } | ||
| } | ||
|
|
||
| export const toOutput = (input: { | ||
| readonly query: string | ||
| readonly instant: boolean | ||
| readonly timeRange: { readonly start: string; readonly end: string } | ||
| readonly stepSeconds: number | ||
| readonly result: PromqlResult | ||
| }): typeof QueryPromqlOutput.Type => ({ | ||
| query: input.query, | ||
| resultType: input.result.resultType, | ||
| instant: input.instant, | ||
| timeRange: input.timeRange, | ||
| stepSeconds: input.stepSeconds, | ||
| series: capSeries(input.result), | ||
| totalSeries: rawSeries(input.result).length, | ||
| ...(input.result.resultType === "string" ? { stringValue: input.result.result.v } : undefined), | ||
| }) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Preserve fractional milliseconds when formatting steps.
For a one-second range,
step: "0.0004"passes validation and the engine permits the grid. This formatter rounds the resolution to0ms, which the tool rejects. Suggested queries also reuse this formatter. Use float seconds when the resolution is not a whole number of milliseconds, or reject that precision before querying. (raw.githubusercontent.com)