From 2d925ab65ca7a8d67b4fbe04e454537b1f9c0888 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 15:21:18 +0100 Subject: [PATCH 01/14] feat(promql): a query_promql MCP tool Agents can run PromQL against an org's metrics through PromqlQueryService. Range evaluation over the shared start_time/end_time window by default, at a round step giving about 60 to 120 points unless step is given; instant=true evaluates once at end_time. The output keeps at most 20 series (highest peaks) and the last 200 points of each, with non-finite samples spelled as Prometheus does. The rendered doc gives each series' min/avg/max/last and a few sampled points, and suggests summing by job when series were cut. Invalid PromQL and evaluation failures are invalid input carrying the engine's message. --- apps/ai/src/mcp/lib/promql-render.ts | 192 ++++++++++++++ apps/ai/src/mcp/lib/promql-result.ts | 111 ++++++++ apps/ai/src/mcp/tool-descriptors.generated.ts | 1 + apps/ai/src/mcp/tools/query-promql.test.ts | 239 ++++++++++++++++++ apps/ai/src/mcp/tools/query-promql.ts | 94 +++++++ apps/ai/src/mcp/tools/registry.ts | 2 + apps/ai/src/mcp/tools/runtime-services.ts | 2 + .../test/mcp/unimplemented-tool-services.ts | 2 + packages/domain/src/mcp-outputs/catalog.ts | 2 + packages/domain/src/mcp-outputs/index.ts | 1 + packages/domain/src/mcp-outputs/promql.ts | 31 +++ 11 files changed, 677 insertions(+) create mode 100644 apps/ai/src/mcp/lib/promql-render.ts create mode 100644 apps/ai/src/mcp/lib/promql-result.ts create mode 100644 apps/ai/src/mcp/tools/query-promql.test.ts create mode 100644 apps/ai/src/mcp/tools/query-promql.ts create mode 100644 packages/domain/src/mcp-outputs/promql.ts diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts new file mode 100644 index 0000000000..91fb72067b --- /dev/null +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -0,0 +1,192 @@ +// query_promql's model-facing text: per series its labels, summary stats and a few points. +import { Array as Arr, Option, Order, Record as Rec, String as Str } from "effect" +import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" +import { formatNumber, tableCell } 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`, UTC. */ +const formatTime = (ms: number): string => Str.replace("T", " ")(Str.slice(5, 16)(new Date(ms).toISOString())) + +/** `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}="${value}"`), + ", ", + ) + return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` +} + +const finiteValues = (series: Series): ReadonlyArray => + Arr.filter( + Arr.map(series.points, (p) => p.v), + (v): v is number => typeof v === "number", + ) + +const stats = (series: Series) => { + const values = finiteValues(series) + if (values.length === 0) return { min: "-", avg: "-", max: "-" } + const sum = Arr.reduce(values, 0, (a, b) => a + b) + return { + min: formatSample(Math.min(...values)), + avg: formatSample(sum / values.length), + max: formatSample(Math.max(...values)), + } +} + +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): ReadonlyArray => [ + doc.table( + ["Series", "Points", "Min", "Avg", "Max", "Last"], + Arr.map(series, (s) => { + const { min, avg, max } = stats(s) + return [ + tableCell(seriesName(s.labels), 100), + formatNumber(s.totalPoints), + min, + avg, + max, + lastValue(s), + ] + }), + ), + doc.list( + Arr.map( + Arr.take(series, DETAILED_SERIES), + (s) => `${tableCell(seriesName(s.labels), 100)}: ${sampled(s)}`, + ), + ), +] + +const bodyOf = (output: Output): ReadonlyArray => { + 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) => [ + tableCell(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: `${output.stepSeconds}s` }), + }, + "fewer series: one per service", + ) + : undefined + +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 : `${output.stepSeconds}s`], + ], + 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`.", + "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] + : [], + } +} diff --git a/apps/ai/src/mcp/lib/promql-result.ts b/apps/ai/src/mcp/lib/promql-result.ts new file mode 100644 index 0000000000..e8e16288ed --- /dev/null +++ b/apps/ai/src/mcp/lib/promql-result.ts @@ -0,0 +1,111 @@ +// 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["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)) { + return Arr.reduce(Arr.fromIterable(Str.matchAll(DURATION_PART)(text)), 0, (total, part) => { + return total + Number(part[1]) * unitSeconds(part[2]) + }) + } + 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> + readonly points: ReadonlyArray<{ readonly t: number; readonly v: number }> +} + +const rawSeries = (result: PromqlResult): ReadonlyArray => { + 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) => + Number.isFinite(p.v) && p.v > max ? p.v : max, + ) + +const byPeakDescending = Order.mapInput(Order.flip(Order.Number), peak) + +/** Over {@link MAX_SERIES}, the series with the highest peaks; each keeps its last {@link MAX_POINTS} points. */ +export const capSeries = (result: PromqlResult): ReadonlyArray => { + const all = rawSeries(result) + const kept = all.length > MAX_SERIES ? Arr.take(Arr.sort(all, byPeakDescending), MAX_SERIES) : all + return Arr.map(kept, (series) => ({ + labels: series.labels, + points: Arr.map(Arr.takeRight(series.points, MAX_POINTS), (p) => ({ t: p.t, v: encodeSample(p.v) })), + totalPoints: series.points.length, + })) +} + +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), +}) diff --git a/apps/ai/src/mcp/tool-descriptors.generated.ts b/apps/ai/src/mcp/tool-descriptors.generated.ts index 8d0056df9a..c4b1b2179f 100644 --- a/apps/ai/src/mcp/tool-descriptors.generated.ts +++ b/apps/ai/src/mcp/tool-descriptors.generated.ts @@ -26,6 +26,7 @@ export const MCP_TOOL_DESCRIPTORS: ReadonlyArray = [ {"name":"error_detail","title":"Error Detail","description":"Sample traces (failing span, correlated logs) and a summary for one error, by `fingerprint` (decimal UInt64 from find_errors) or `issue_id` (UUID from list_error_issues). Without start_time/end_time it counts the last 30 days and samples the 6 hours before the last occurrence. Use inspect_trace on a trace_id for the full span tree.","inputSchema":{"type":"object","properties":{"fingerprint":{"type":"string","description":"The error FingerprintHash from find_errors or list_error_issues: a decimal UInt64 string, e.g. \"11640295108927840024\"."},"issue_id":{"type":"string","description":"An error issue id from list_error_issues (its UUID or its REST id, iss_\u2026), instead of fingerprint."},"start_time":{"type":"string","description":"Start of the window, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Omit both bounds to anchor on the error's last occurrence in the past 30 days."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"include_timeseries":{"type":"boolean","description":"Include error count over time to see if the error is trending up or down"},"limit":{"type":"number","description":"Max sample traces to return (default 5, max 20)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"fingerprintHash":{"type":"string"},"error":{"type":"object","properties":{"label":{"type":"string"},"exceptionType":{"type":"string"},"message":{"type":"string"},"serviceName":{"type":"string"}},"required":["label","exceptionType","message","serviceName"],"additionalProperties":true},"issueId":{"type":"string"},"otherFingerprints":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"occurrences":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"firstSeen":{"type":"string"},"lastSeen":{"type":"string"},"services":{"type":"array","items":{"type":"string"}},"serviceCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"noExceptionCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["timeRange","occurrences","firstSeen","lastSeen","services","serviceCount","noExceptionCount"],"additionalProperties":true},"anchored":{"type":"boolean"},"related":{"type":"array","items":{"type":"object","properties":{"fingerprintHash":{"type":"string"},"label":{"type":"string"},"serviceName":{"type":"string"},"traces":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["fingerprintHash","label","serviceName","traces"],"additionalProperties":true}},"traces":{"type":"array","items":{"type":"object","properties":{"traceId":{"type":"string"},"rootSpanName":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"spanCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"services":{"type":"array","items":{"type":"string"}},"startTime":{"type":"string"},"errorMessage":{"type":"string"},"errorSpan":{"type":"object","properties":{"spanId":{"type":"string"},"name":{"type":"string"},"serviceName":{"type":"string"},"statusMessage":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["spanId","name","serviceName","statusMessage","attributes"],"additionalProperties":true},"logs":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"severityText":{"type":"string"},"body":{"type":"string"}},"required":["timestamp","severityText","body"],"additionalProperties":true}}},"required":["traceId","rootSpanName","durationMs","spanCount","services","startTime","logs"],"additionalProperties":true}},"timeseries":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"count":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["bucket","count"],"additionalProperties":true}},"service":{"type":"string"}},"required":["timeRange","fingerprintHash","traces"],"additionalProperties":true},"annotations":{"title":"Error Detail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"list_metrics","title":"List Metrics","description":"Discover custom metrics with their type, unit, monotonicity and data volume. Pass a discovered `metric_name` and `metric_type` to query_data source=metrics.","inputSchema":{"type":"object","properties":{"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time. Covers at most 30 days; a wider window is narrowed to the 30 days before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"search":{"type":"string","description":"Substring of the metric name"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"],"description":"Only metrics of this type"},"offset":{"type":"number","description":"Rows to skip, for paging (default 0). Use the `next` call a truncated result gives."},"limit":{"type":"number","description":"Max metrics to return (default 50, max 500)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"pagination":{"type":"object","properties":{"offset":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"hasMore":{"type":"boolean"},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"nextOffset":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["offset","limit","hasMore"],"additionalProperties":true},"summary":{"type":"array","items":{"type":"object","properties":{"metricType":{"type":"string"},"metricCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"dataPointCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["metricType","metricCount","dataPointCount"],"additionalProperties":true}},"metrics":{"type":"array","items":{"type":"object","properties":{"metricName":{"type":"string"},"metricType":{"type":"string"},"serviceName":{"type":"string"},"metricUnit":{"type":"string"},"isMonotonic":{"type":"boolean"},"dataPointCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["metricName","metricType","serviceName","metricUnit","isMonotonic","dataPointCount"],"additionalProperties":true}},"filters":{"type":"object","properties":{"service":{"type":"string"},"search":{"type":"string"},"metricType":{"type":"string"}},"additionalProperties":true}},"required":["timeRange","summary","metrics"],"additionalProperties":true},"annotations":{"title":"List Metrics","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"query_data","title":"Query Data","description":"Aggregate traces, logs, metrics or product events into a timeseries or a top-N breakdown. Start here for trends, comparisons and top-N; for errors prefer find_errors and error_detail; for a shape this tool cannot express, run_sql. Applied defaults are listed in the result. A traces breakdown by span_name or attribute reads raw spans: set `service` and keep the window short (a window too large is narrowed, with a note). For endpoint volume over days use route_usage.","inputSchema":{"type":"object","properties":{"source":{"type":"string","enum":["traces","logs","metrics","product_events"],"description":"'traces' for request/span analysis (latency, errors, throughput); 'logs' for log volume; 'metrics' for a custom metric (needs metric_name and metric_type from list_metrics); 'product_events' for track() events, page views and server events (names from list_product_events). Signups and accounts in a connected system (Clerk, a database) are data sources: search_data_sources."},"kind":{"type":"string","enum":["timeseries","breakdown"],"description":"'timeseries' for how a value changed over time; 'breakdown' for top-N or distribution. Pick the right one first rather than calling twice."},"metric":{"type":"string","description":"Traces: count, avg_duration, p50_duration, p95_duration, p99_duration, error_rate (0-1 ratio; for a count of errors use count with status Error, which error_count is read as), apdex (needs apdex_threshold_ms). Logs: count. Product events: count, sessions, persons, users, visitors. Metrics: avg, sum, min, max, count, rate, increase. For counters (sum metrics, Prometheus *_total gauges) use increase (total over the window) or rate (per second); both are per-series and reset-aware. sum adds raw samples. Default: count, or avg for metrics."},"group_by":{"type":"string","description":"Traces: service, span_name, status_code, http_method, attribute, resource_attribute. Logs: service, severity; breakdowns also attribute, resource_attribute. Metrics: service, attribute, resource_attribute. Product events: event_name, kind, source, host, page_path, service, group, attribute. 'attribute' and 'resource_attribute' need attribute_key (resource_attribute reads resource keys such as k8s.pod.name or deployment.environment; per commit is resource_attribute with attribute_key=vcs.ref.head.revision). Timeseries also take 'none' (the default); breakdown defaults to service."},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"span_name":{"type":"string","description":"Filter by span name (traces only). Exact match first; when nothing matches exactly it is matched as a case-insensitive substring"},"root_spans_only":{"type":"boolean","description":"Only include root spans (traces only)"},"environments":{"type":"array","items":{"type":"string"},"description":"Only these deployment environments (traces, logs, metrics; explore_attributes source=services lists them)"},"commit_shas":{"type":"array","items":{"type":"string"},"description":"Commit SHAs to filter (traces only)"},"apdex_threshold_ms":{"type":"number","description":"Apdex threshold in ms (traces only; needed for metric=apdex)"},"severity":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"],"description":"Only this log severity (logs only)"},"event_name":{"type":"array","items":{"type":"string"},"description":"Only these event names (product_events only)"},"event_kind":{"type":"array","items":{"type":"string","enum":["navigation","custom","screen"]},"description":"Only these event kinds (product_events only)"},"host":{"type":"string","description":"Only events fired on this site host (product_events only)"},"page_path":{"type":"string","description":"Only events fired on this page path (product_events only)"},"metric_name":{"type":"string","description":"The metric, from list_metrics (source=metrics only)"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"],"description":"Type of `metric_name`, as list_metrics reports it"},"attribute_key":{"type":"string","description":"Attribute to filter on, or to group by with group_by=attribute. Span (or log/metric label) and resource attributes both work; the scope is resolved automatically"},"attribute_value":{"type":"string","description":"Exact value for attribute_key. Also applies when grouping by the same key"},"attribute_scope":{"type":"string","enum":["span","resource"],"description":"Where attribute_key lives: 'span' (span, log or metric-datapoint attributes) or 'resource' (deployment.environment, k8s.pod.name...). Resolved from the known keys when omitted"},"bucket_seconds":{"type":"number","description":"Bucket width in seconds (timeseries only; auto-computed when omitted)"},"limit":{"type":"number","description":"Max rows of a breakdown (default 10, max 100)"}},"required":["source","kind"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"kind":{"type":"string"},"metric":{"type":"string"},"groupBy":{"type":"string"},"decisions":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"queryContext":{"type":"object","properties":{"source":{"type":"string","enum":["traces","logs","metrics","product_events"]},"serviceName":{"type":"string"},"eventName":{"type":"string"},"eventKind":{"type":"string"},"host":{"type":"string"},"pagePath":{"type":"string"},"spanName":{"type":"string"},"rootSpansOnly":{"type":"boolean"},"environments":{"type":"array","items":{"type":"string"}},"commitShas":{"type":"array","items":{"type":"string"}},"severity":{"type":"string"},"metricName":{"type":"string"},"metricType":{"type":"string"},"attributeFilters":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"mode":{"type":"string"}},"required":["key","mode"],"additionalProperties":true}},"apdexThresholdMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"bucketSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["source"],"additionalProperties":true},"unit":{"type":"string","enum":["duration_ms","duration_us","duration_s","duration_ns","percent","number","bytes","requests_per_sec"]},"result":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["timeseries"]},"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"series":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}}},"required":["bucket","series"],"additionalProperties":true}}},"required":["kind","data"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["breakdown"]},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["name","value"],"additionalProperties":true}}},"required":["kind","data"],"additionalProperties":true}]},"emptyHints":{"type":"array","items":{"type":"string"}}},"required":["timeRange","kind","metric","queryContext","unit","result"],"additionalProperties":true},"annotations":{"title":"Query Data","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, + {"name":"query_promql","title":"Query PromQL","description":"Run a PromQL query over the org's metrics, Prometheus-exact. Range evaluation over start_time..end_time by default; instant=true evaluates once at end_time. Metric names are Prometheus-style, translated from OTel: dots become underscores and the unit is a suffix (`http.server.request.duration` in s is `http_server_request_duration_seconds`), monotonic sums end in `_total`, histograms read as `_bucket` (with `le`), `_count` and `_sum`. Labels are attribute keys with underscores (`host.name` is `host_name`); `job` is the service name, `instance` the service instance id. Examples: `sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`; `histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket[5m])))`; `sum by (job) (rate(http_server_request_duration_seconds_count{http_response_status_code=~\"5..\"}[5m])) / sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`. Use list_metrics to find the OTel names. Returns at most 20 series (highest peaks) and the last 200 points of each.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"PromQL expression, e.g. sum by (job) (rate(http_server_request_duration_seconds_count[5m]))"},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 1 hour before end_time. Covers at most 7 days; a wider window is narrowed to the 7 days before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"step":{"type":"string","description":"Range resolution as a Prometheus duration (`30s`, `1m`, `1h`) or seconds. Default: a round step giving about 60 to 120 points."},"instant":{"type":"boolean","description":"Evaluate once at end_time instead of over the window (default false)"}},"required":["query"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"query":{"type":"string"},"resultType":{"type":"string","enum":["matrix","vector","scalar","string"]},"instant":{"type":"boolean"},"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"stepSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"series":{"type":"array","items":{"type":"object","properties":{"labels":{"type":"object","additionalProperties":{"type":"string"}},"points":{"type":"array","items":{"type":"object","properties":{"t":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"v":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]}},"required":["t","v"],"additionalProperties":true}},"totalPoints":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["labels","points","totalPoints"],"additionalProperties":true}},"totalSeries":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"stringValue":{"type":"string"}},"required":["query","resultType","instant","timeRange","stepSeconds","series","totalSeries"],"additionalProperties":true},"annotations":{"title":"Query PromQL","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"run_sql","title":"Run SQL","description":"Run one read-only ClickHouse SELECT against Maple's own telemetry warehouse (this org's traces, logs, metrics) and return its rows: at most 1000 are fetched and the first 100 rendered, with the count reported. Use it for what query_data cannot express, to spot-check data, or to test SQL for a raw_sql widget. For trends and top-N prefer query_data. The SQL must AND in `$__orgFilter`; macros are listed on `sql`. Spans are in `traces` (no otel_spans/spans table), log lines in `logs`; also metrics_sum/metrics_gauge/metrics_histogram, error_events, session_replays, product_events and *_hourly/*_minutely rollups. Select 64-bit IDs and hashes as toString(col). Attribute columns are Map(String, String): SpanAttributes['http.route'], never JSON* functions. In traces the name is SpanName, StatusCode is 'Ok'/'Error' and Duration is nanoseconds. trace_list_mv is one root span per trace with HttpRoute/HttpMethod/HttpStatusCode (a String) columns and no attribute maps or ParentSpanId. Rollups (*_hourly/*_minutely) keep time in Hour/Minute and counts in SpanCount; merge their AggregateFunction columns. Compare timestamps to 'YYYY-MM-DD HH:MM:SS', not ISO T/Z strings; bucket with toStartOfInterval. Call describe_warehouse_tables for a table's columns, units and enum casing before guessing names. It cannot reach databases or APIs the org connected as data sources: query those with query_data_source.","inputSchema":{"type":"object","properties":{"sql":{"type":"string","description":"The SELECT. It MUST contain `$__orgFilter` (expands to `(OrgId = '')`) as a top-level AND condition; a query without it, or with it OR-ed against another condition, is rejected. In joins use `$__orgFilter(alias)` (`(alias.OrgId = '')`) once per joined table. Other macros: `$__timeFilter(Column)` (`Column >= AND Column <= `), `$__startTime`, `$__endTime`, `$__interval_s` (bucket width for toStartOfInterval). Only one statement; DDL/DML, SETTINGS and system tables are rejected."},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"granularity_seconds":{"type":"number","description":"Value of `$__interval_s`. Auto-computed from the window when omitted."},"max_cell_chars":{"type":"number","description":"Clip each rendered cell to this many characters (default 120, max 2000). Raise it to read long values such as log bodies or stack traces."},"show_sql":{"type":"boolean","description":"Also return the macro-expanded SQL that ran (default false)."},"reason":{"type":"string","description":"Why you are running this query, in a sentence. Optional; does not change the query."}},"required":["sql"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"rowCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object"}},"truncated":{"type":"boolean"},"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"maxCellChars":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"windowApplied":{"type":"boolean"},"expandedSql":{"type":"string"},"atRowCap":{"type":"boolean"},"rewrites":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"reason":{"type":"string"}},"required":["from","to"],"additionalProperties":true}},"managedOnlyTables":{"type":"array","items":{"type":"string"}}},"required":["rowCount","columns","rows","truncated","timeRange"],"additionalProperties":true},"annotations":{"title":"Run SQL","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"service_map","title":"Service Map","description":"Show service-to-service dependencies with call counts, error rates, and latency per edge. Use to understand system architecture and identify problematic inter-service calls.","inputSchema":{"type":"object","properties":{"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only edges involving this service, as source or target (exact `service.name`)"},"environment":{"type":"string","description":"Only this deployment environment (e.g. production, staging)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"edges":{"type":"array","items":{"type":"object","properties":{"sourceService":{"type":"string"},"targetService":{"type":"string"},"callCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"errorCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"avgDurationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"maxDurationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["sourceService","targetService","callCount","errorCount","avgDurationMs","maxDurationMs"],"additionalProperties":true}},"serviceCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"service":{"type":"string"},"environment":{"type":"string"}},"required":["timeRange","edges","serviceCount"],"additionalProperties":true},"annotations":{"title":"Service Map","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"list_alert_rules","title":"List Alert Rules","description":"List configured alert rules with severity, signal type and condition. Use list_alert_incidents for what has fired.","inputSchema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"string"},"description":"Only rules covering any of these services: scoped to them, scoped to every service, or raw_query rules whose SQL or name mentions them"},"signal_type":{"type":"string","enum":["error_rate","p95_latency","p99_latency","apdex","throughput","builder_query","raw_query","anomaly"],"description":"Only rules on this signal type"},"severity":{"type":"string","enum":["warning","critical"],"description":"Only rules with this severity"},"enabled_only":{"type":"boolean","description":"Only enabled rules"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"severity":{"type":"string"},"serviceNames":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"string"}},"anomalySignals":{"type":"array","items":{"type":"string"}},"signalType":{"type":"string"},"comparator":{"type":"string"},"threshold":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"windowMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"evaluationIntervalMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"slowedIntervalMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"destinationIds":{"type":"array","items":{"type":"string"}},"escalationChains":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"chainId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["severity","chainId"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","enabled","severity","serviceNames","environments","signalType","comparator","threshold","windowMinutes","evaluationIntervalMinutes","slowedIntervalMinutes","destinationIds","createdAt","updatedAt"],"additionalProperties":true}},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"services":{"type":"array","items":{"type":"string"}},"signalType":{"type":"string"},"severity":{"type":"string"},"enabledOnly":{"type":"boolean"}},"required":["rules","total"],"additionalProperties":true},"annotations":{"title":"List Alert Rules","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts new file mode 100644 index 0000000000..5537a53ccf --- /dev/null +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -0,0 +1,239 @@ +import { afterEach, describe, expect, it } from "@effect/vitest" +import { Array as Arr, ConfigProvider, Effect, Layer, Schema } from "effect" +import { TestClock } from "effect/testing" +import { OrgId, UserId } from "@maple/domain/http" +import { Env } from "@maple/backend/platform/Env" +import { EdgeCacheServiceLive } from "@maple/backend/platform/CacheBackendLive" +import { cleanupTestDbs, createTestDb, type TestDb } from "@maple/backend/testing/test-pglite" +import { + PromqlBadQueryError, + PromqlQueryService, + type PromqlQuery, +} from "@maple/backend/services/promql/PromqlQueryService" +import { CurrentMcpTenant } from "../tenant" +import { renderToolDoc } from "../lib/tool-doc" +import { defaultStepSeconds, parseStepSeconds, type PromqlResult } from "../lib/promql-result" +import { registerQueryPromqlTool } from "./query-promql" +import type { McpToolError, McpToolRegistrar } from "./types" +import type { McpToolRequirements } from "./runtime-services" +import type { ToolDoc } from "../lib/tool-doc" +import { unimplementedMcpToolServices } from "../../../test/mcp/unimplemented-tool-services" + +const trackedDbs: TestDb[] = [] +afterEach(() => cleanupTestDbs(trackedDbs)) + +const WINDOW = { start_time: "2026-11-15 10:00:00", end_time: "2026-11-15 11:00:00" } +const END_MS = Date.parse("2026-11-15T11:00:00Z") + +type Invoke = ( + params: Readonly>, +) => Effect.Effect< + { readonly output: unknown; readonly doc: ToolDoc; readonly text: string }, + McpToolError, + McpToolRequirements +> + +const promqlTool = (): Invoke => { + let invoke: Invoke = () => Effect.die("unregistered") + const registrar: McpToolRegistrar = { + define: (spec) => { + invoke = (params) => + Schema.decodeEffect(spec.parameters)(params).pipe( + Effect.orDie, + Effect.flatMap(spec.handler), + Effect.map((output) => { + const doc = spec.render(output) + return { output, doc, text: renderToolDoc(doc) } + }), + ) + }, + } + registerQueryPromqlTool(registrar) + return invoke +} + +/** Runs the tool against a PromQL service that records each query and answers with `answer`. */ +const run = ( + params: Readonly>, + answer: (input: PromqlQuery) => Effect.Effect, + calls: Array = [], +) => + // it.effect starts its clock at 0; the window must be in the past. + TestClock.setTime(END_MS + 60_000).pipe( + Effect.andThen(promqlTool()(params)), + Effect.provide( + Layer.mergeAll( + Layer.mock(PromqlQueryService)({ + query: (_tenant, input) => { + calls.push(input) + return answer(input) + }, + }), + Layer.succeed(CurrentMcpTenant, { + orgId: Schema.decodeSync(OrgId)("org_promql"), + userId: Schema.decodeSync(UserId)("user_promql"), + roles: [], + authMode: "self_hosted", + }), + ).pipe( + Layer.provideMerge(unimplementedMcpToolServices), + Layer.provide(Layer.mergeAll(createTestDb(trackedDbs).layer, EdgeCacheServiceLive)), + Layer.provideMerge(Env.layer), + Layer.provide( + ConfigProvider.layer( + ConfigProvider.fromUnknown({ + TINYBIRD_HOST: "https://api.tinybird.co", + TINYBIRD_TOKEN: "test-token", + MAPLE_AUTH_MODE: "self_hosted", + MAPLE_ROOT_PASSWORD: "test-root-password", + MAPLE_DEFAULT_ORG_ID: "default", + MAPLE_INGEST_KEY_ENCRYPTION_KEY: Buffer.alloc(32, 1).toString("base64"), + MAPLE_INGEST_KEY_LOOKUP_HMAC_KEY: "maple-test-lookup-secret", + INTERNAL_SERVICE_TOKEN: "test-internal-token", + }), + ), + ), + ), + ), + ) + +const series = (job: string, values: ReadonlyArray, stepMs = 30_000) => ({ + labels: { job, http_route: "/checkout" }, + points: Arr.map(values, (v, i) => ({ t: END_MS - (values.length - 1 - i) * stepMs, v })), +}) + +const QUERY = "sum by (job, http_route) (rate(http_server_request_duration_seconds_count[5m]))" + +describe("query_promql", () => { + it.effect("evaluates a range at a default step and renders each series' stats and points", () => + Effect.gen(function* () { + const calls: Array = [] + const { text } = yield* run( + { query: QUERY, ...WINDOW }, + () => + Effect.succeed({ + resultType: "matrix" as const, + result: [series("api", [2, 4, 6]), series("web", [1, Number.NaN, 0.5])], + }), + calls, + ) + // One hour at 30s is 120 points. + expect(calls).toEqual([ + { query: QUERY, startMs: END_MS - 3_600_000, endMs: END_MS, stepMs: 30_000 }, + ]) + expect(text).toContain("Step: 30s") + expect(text).toContain('| {http_route="/checkout", job="api"} | 3 | 2 | 4 | 6 | 6 |') + expect(text).toContain('| {http_route="/checkout", job="web"} | 3 | 0.5 | 0.75 | 1 | 0.5 |') + expect(text).toContain( + '{http_route="/checkout", job="web"}: 11-15 10:59 1, 11-15 10:59 NaN, 11-15 11:00 0.5', + ) + }), + ) + + it.effect("evaluates once at end_time for an instant query", () => + Effect.gen(function* () { + const calls: Array = [] + const { output, text } = yield* run( + { query: "up", ...WINDOW, instant: true }, + () => + Effect.succeed({ + resultType: "vector" as const, + result: [{ labels: { __name__: "up", job: "api" }, value: 1, t: END_MS }], + }), + calls, + ) + expect(calls).toEqual([{ query: "up", startMs: END_MS, endMs: END_MS, stepMs: 0 }]) + expect(output).toMatchObject({ + resultType: "vector", + instant: true, + stepSeconds: 0, + totalSeries: 1, + }) + expect(text).toContain("| Series | Value |") + expect(text).toContain('| up{job="api"} | 1 |') + expect(text).not.toContain("Step:") + }), + ) + + it.effect("reports invalid PromQL as invalid input with the parser's message", () => + Effect.gen(function* () { + const error = yield* Effect.flip( + run({ query: "sum(rate(x[5m]", ...WINDOW }, () => + Effect.fail( + new PromqlBadQueryError({ message: "unclosed left parenthesis", position: 4 }), + ), + ), + ) + expect(error).toMatchObject({ + _tag: "@maple/mcp/errors/McpInvalidInputError", + parameter: "query", + message: "Invalid PromQL: unclosed left parenthesis (at position 4)", + }) + }), + ) + + it.effect("refuses a step that is not a duration", () => + Effect.gen(function* () { + const error = yield* Effect.flip( + run({ query: "up", ...WINDOW, step: "soon" }, () => Effect.die("not reached")), + ) + expect(error).toMatchObject({ _tag: "@maple/mcp/errors/McpInvalidInputError", parameter: "step" }) + }), + ) + + it.effect("keeps the 20 highest series and the last 200 points, and suggests summing by service", () => + Effect.gen(function* () { + const many = Arr.makeBy(25, (i) => + series( + `svc-${i}`, + Arr.makeBy(300, (k) => i + k / 1000), + ), + ) + const { output, doc, text } = yield* run({ query: QUERY, ...WINDOW, step: "1m" }, () => + Effect.succeed({ resultType: "matrix" as const, result: many }), + ) + const decoded = Schema.decodeUnknownSync( + Schema.Struct({ + totalSeries: Schema.Number, + series: Schema.Array( + Schema.Struct({ + labels: Schema.Record(Schema.String, Schema.String), + points: Schema.Array(Schema.Unknown), + totalPoints: Schema.Number, + }), + ), + }), + )(output) + expect(decoded.totalSeries).toBe(25) + expect(decoded.series).toHaveLength(20) + expect(decoded.series[0]?.labels.job).toBe("svc-24") + expect(Arr.map(decoded.series, (s) => s.points.length)).toEqual(Arr.makeBy(20, () => 200)) + expect(decoded.series[0]?.totalPoints).toBe(300) + expect(text).toContain("Showing 20 of 25 series (highest peaks kept).") + expect(text).toContain("Note: Each series shows its last 200 points") + expect(doc.next).toEqual([ + { + tool: "query_promql", + args: { query: `sum by (job) (${QUERY})`, ...WINDOW, step: "60s" }, + why: "fewer series: one per service", + }, + ]) + }), + ) +}) + +describe("query_promql steps", () => { + it("reads Prometheus durations and seconds", () => { + expect(parseStepSeconds("1m")).toBe(60) + expect(parseStepSeconds("1h30m")).toBe(5400) + expect(parseStepSeconds("15")).toBe(15) + expect(parseStepSeconds("0")).toBeUndefined() + expect(parseStepSeconds("1 minute")).toBeUndefined() + }) + + it("picks a round step giving at most 120 points", () => { + expect(defaultStepSeconds(3600)).toBe(30) + expect(defaultStepSeconds(6 * 3600)).toBe(300) + expect(defaultStepSeconds(7 * 86_400)).toBe(7200) + }) +}) diff --git a/apps/ai/src/mcp/tools/query-promql.ts b/apps/ai/src/mcp/tools/query-promql.ts new file mode 100644 index 0000000000..b519ae1932 --- /dev/null +++ b/apps/ai/src/mcp/tools/query-promql.ts @@ -0,0 +1,94 @@ +import type { McpToolRegistrar } from "./types" +import { McpInvalidInputError } from "./types" +import { CurrentMcpTenant } from "../tenant" +import { warehouseReadToMcpHandlers } from "../lib/map-warehouse-error" +import { defaultStepSeconds, parseStepSeconds, toOutput } from "../lib/promql-result" +import { renderPromqlOutput } from "../lib/promql-render" +import * as P from "../lib/params" +import { Effect, Schema } from "effect" +import { parseWarehouseDateTime } from "@maple/query-engine" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" + +const WINDOW = P.timeWindow({ defaultHours: 1, maxHours: 7 * 24 }) + +const EXAMPLE = "sum by (job) (rate(http_server_request_duration_seconds_count[5m]))" + +const DESCRIPTION = [ + "Run a PromQL query over the org's metrics, Prometheus-exact. Range evaluation over start_time..end_time by default; instant=true evaluates once at end_time.", + "Metric names are Prometheus-style, translated from OTel: dots become underscores and the unit is a suffix (`http.server.request.duration` in s is `http_server_request_duration_seconds`), monotonic sums end in `_total`, histograms read as `_bucket` (with `le`), `_count` and `_sum`. Labels are attribute keys with underscores (`host.name` is `host_name`); `job` is the service name, `instance` the service instance id.", + `Examples: \`${EXAMPLE}\`; \`histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket[5m])))\`; \`sum by (job) (rate(http_server_request_duration_seconds_count{http_response_status_code=~"5.."}[5m])) / sum by (job) (rate(http_server_request_duration_seconds_count[5m]))\`.`, + "Use list_metrics to find the OTel names. Returns at most 20 series (highest peaks) and the last 200 points of each.", +].join(" ") + +export function registerQueryPromqlTool(server: McpToolRegistrar) { + server.define({ + name: "query_promql", + title: "Query PromQL", + description: DESCRIPTION, + parameters: Schema.Struct({ + query: P.text(`PromQL expression, e.g. ${EXAMPLE}`), + ...WINDOW.fields, + step: P.optionalText( + "Range resolution as a Prometheus duration (`30s`, `1m`, `1h`) or seconds. Default: a round step giving about 60 to 120 points.", + ), + instant: P.optionalFlag("Evaluate once at end_time instead of over the window (default false)"), + }), + hints: { readOnly: true }, + phrases: ["Running a PromQL query", "Querying metrics"], + handler: Effect.fn("McpTool.queryPromql")(function* (params) { + const { st, et } = yield* WINDOW.resolve(params, "query_promql") + const tenant = yield* CurrentMcpTenant + const promql = yield* PromqlQueryService + const instant = params.instant === true + const endMs = parseWarehouseDateTime(et) + const startMs = instant ? endMs : parseWarehouseDateTime(st) + const requested = params.step === undefined ? undefined : parseStepSeconds(params.step) + if (params.step !== undefined && requested === undefined) { + return yield* new McpInvalidInputError({ + message: `step "${params.step}" is not a Prometheus duration or a number of seconds.`, + parameter: "step", + example: "1m", + }) + } + const stepSeconds = instant ? 0 : (requested ?? defaultStepSeconds((endMs - startMs) / 1000)) + yield* Effect.annotateCurrentSpan({ + orgId: tenant.orgId, + "maple.ai.promql.instant": instant, + "maple.ai.promql.step_seconds": stepSeconds, + }) + + const result = yield* promql + .query(tenant, { query: params.query, startMs, endMs, stepMs: stepSeconds * 1000 }) + .pipe( + Effect.catchTags({ + "@maple/backend/promql/PromqlBadQueryError": (error) => + Effect.fail( + new McpInvalidInputError({ + message: `Invalid PromQL: ${error.message}${error.position === undefined ? "" : ` (at position ${error.position})`}`, + parameter: "query", + example: EXAMPLE, + }), + ), + "@maple/backend/promql/PromqlExecutionError": (error) => + Effect.fail( + new McpInvalidInputError({ + message: `PromQL could not be evaluated: ${error.message}`, + parameter: "query", + }), + ), + ...warehouseReadToMcpHandlers("query_promql"), + }), + ) + const output = toOutput({ + query: params.query, + instant, + timeRange: { start: st, end: et }, + stepSeconds, + result, + }) + yield* Effect.annotateCurrentSpan("result.rowCount", output.totalSeries) + return output + }), + render: renderPromqlOutput, + }) +} diff --git a/apps/ai/src/mcp/tools/registry.ts b/apps/ai/src/mcp/tools/registry.ts index 625e9715e6..7b97ff208b 100644 --- a/apps/ai/src/mcp/tools/registry.ts +++ b/apps/ai/src/mcp/tools/registry.ts @@ -109,6 +109,7 @@ import { registerListDashboardsTool } from "./list-dashboards" import { registerListMetricsTool } from "./list-metrics" import { registerListServicesTool } from "./list-services" import { registerQueryDataTool } from "./query-data" +import { registerQueryPromqlTool } from "./query-promql" import { registerRunSqlTool } from "./run-sql" import { registerRemoveDashboardWidgetTool } from "./remove-dashboard-widget" import { registerReplaceDashboardWidgetsTool } from "./replace-dashboard-widgets" @@ -465,6 +466,7 @@ const collectMapleToolDefinitions = (): ReadonlyArray => { registerErrorDetailTool(registrar) registerListMetricsTool(registrar) registerQueryDataTool(registrar) + registerQueryPromqlTool(registrar) registerRunSqlTool(registrar) registerServiceMapTool(registrar) registerListAlertRulesTool(registrar) diff --git a/apps/ai/src/mcp/tools/runtime-services.ts b/apps/ai/src/mcp/tools/runtime-services.ts index 5e8f53bae6..19f13bb306 100644 --- a/apps/ai/src/mcp/tools/runtime-services.ts +++ b/apps/ai/src/mcp/tools/runtime-services.ts @@ -39,6 +39,7 @@ import { IntegrationInventoryService } from "@maple/backend/services/integration import { SourcesService } from "@maple/backend/services/org/SourcesService" import { AgentFeedbackService } from "@maple/backend/services/feedback/AgentFeedbackService" import { QueryEngineService } from "@maple/backend/services/warehouse/QueryEngineService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { SecurityAuditStore } from "@maple/backend/services/security-audit/SecurityAuditStore" import { DependencyScanReader } from "@maple/backend/services/dependency-scan/DependencyScanService" import { RuntimeReleaseCatalog } from "@maple/backend/services/security/RuntimeReleaseCatalog" @@ -82,6 +83,7 @@ export const McpRuntimeServicesLive = Layer.mergeAll( InvestigationService.layer, IssueFixVerificationService.layer, QueryEngineService.layer, + PromqlQueryService.layer, RailwayMetricsService.layer, RecommendationIssueService.layer, RepoSandboxService.layer, diff --git a/apps/ai/test/mcp/unimplemented-tool-services.ts b/apps/ai/test/mcp/unimplemented-tool-services.ts index a579401f81..9a262a5550 100644 --- a/apps/ai/test/mcp/unimplemented-tool-services.ts +++ b/apps/ai/test/mcp/unimplemented-tool-services.ts @@ -43,6 +43,7 @@ import { StatusPagesService } from "@maple/backend/services/status-pages/StatusP import { StatusPageSnapshotBuilder } from "@maple/backend/services/status-pages/StatusPageSnapshotBuilder" import { RepoSandboxService } from "@maple/backend/services/sandbox/RepoSandboxService" import { QueryEngineService } from "@maple/backend/services/warehouse/QueryEngineService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" import { SecurityAuditStore } from "@maple/backend/services/security-audit/SecurityAuditStore" import { DependencyScanReader } from "@maple/backend/services/dependency-scan/DependencyScanService" @@ -93,6 +94,7 @@ export const unimplementedMcpToolServices = Layer.mergeAll( Layer.mock(OrganizationFeatureFlagsService)({}), Layer.mock(RepoSandboxService)({}), Layer.mock(QueryEngineService)({}), + Layer.mock(PromqlQueryService)({}), SecurityAuditStore.layer, Layer.mock(DependencyScanReader)({}), Layer.mock(RuntimeReleaseCatalog)({}), diff --git a/packages/domain/src/mcp-outputs/catalog.ts b/packages/domain/src/mcp-outputs/catalog.ts index 90a583b377..904a991a31 100644 --- a/packages/domain/src/mcp-outputs/catalog.ts +++ b/packages/domain/src/mcp-outputs/catalog.ts @@ -86,6 +86,7 @@ import { UpdateDashboardWidgetOutput, } from "./dashboards" import { ErrorDetailOutput, FindErrorsOutput } from "./errors" +import { QueryPromqlOutput } from "./promql" import { GetInvestigationOutput } from "./investigations" import { ClaimErrorIssueOutput, @@ -265,6 +266,7 @@ export const McpToolOutputs = { propose_fix: ProposeFixOutput, query_data: QueryDataOutput, query_funnel: QueryFunnelOutput, + query_promql: QueryPromqlOutput, read_source_file: ReadSourceFileOutput, register_agent: RegisterAgentOutput, release_error_issue: ReleaseErrorIssueOutput, diff --git a/packages/domain/src/mcp-outputs/index.ts b/packages/domain/src/mcp-outputs/index.ts index 101a5aa2d8..aeea9a2375 100644 --- a/packages/domain/src/mcp-outputs/index.ts +++ b/packages/domain/src/mcp-outputs/index.ts @@ -26,4 +26,5 @@ export * from "./uptime" export * from "./slo" export * from "./status-pages" export * from "./users" +export * from "./promql" export * from "./catalog" diff --git a/packages/domain/src/mcp-outputs/promql.ts b/packages/domain/src/mcp-outputs/promql.ts new file mode 100644 index 0000000000..db3ab5114f --- /dev/null +++ b/packages/domain/src/mcp-outputs/promql.ts @@ -0,0 +1,31 @@ +import { Schema } from "effect" +import { OutputTimeRange } from "./shared" + +/** A sample value: a finite number, or Prometheus' spelling of a non-finite one. */ +export const PromqlSampleValue = Schema.Union([Schema.Finite, Schema.Literals(["NaN", "+Inf", "-Inf"])]) + +/** One sample: epoch ms and value. */ +export const PromqlPoint = Schema.Struct({ t: Schema.Number, v: PromqlSampleValue }) + +export const PromqlSeries = Schema.Struct({ + /** Prometheus labels, `__name__` included when the expression keeps it. */ + labels: Schema.Record(Schema.String, Schema.String), + /** The last `points` samples of the series; `totalPoints` counts them all. */ + points: Schema.Array(PromqlPoint), + totalPoints: Schema.Number, +}) + +export const QueryPromqlOutput = Schema.Struct({ + query: Schema.String, + resultType: Schema.Literals(["matrix", "vector", "scalar", "string"]), + /** Evaluated at `timeRange.end` alone, not over the range. */ + instant: Schema.Boolean, + timeRange: OutputTimeRange, + /** Resolution step of a range evaluation, 0 for an instant one. */ + stepSeconds: Schema.Number, + /** Series kept, at most the cap; a scalar is one series with no labels. */ + series: Schema.Array(PromqlSeries), + totalSeries: Schema.Number, + /** A `string` result's value. */ + stringValue: Schema.optionalKey(Schema.String), +}) From 291cc4a47f39054de1022ad0458dc62498a053d5 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 15:52:08 +0100 Subject: [PATCH 02/14] fix(promql): rank infinite peaks when capping, and refuse a zero step query_promql dropped series whose values were +Inf (a division by zero) when it kept the 20 highest peaks; +Inf now ranks highest. A step of 0s passed the tool's own check and surfaced as an invalid query; it is now invalid input on step. --- apps/ai/src/mcp/lib/promql-result.ts | 6 ++++-- apps/ai/src/mcp/tools/query-promql.test.ts | 15 ++++++++++++++- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-result.ts b/apps/ai/src/mcp/lib/promql-result.ts index e8e16288ed..90a0a61a7e 100644 --- a/apps/ai/src/mcp/lib/promql-result.ts +++ b/apps/ai/src/mcp/lib/promql-result.ts @@ -36,9 +36,10 @@ const DURATION_PART = /(\d+)(ms|s|m|h|d|w|y)/g export const parseStepSeconds = (raw: string): number | undefined => { const text = Str.trim(raw) if (DURATION.test(text)) { - return Arr.reduce(Arr.fromIterable(Str.matchAll(DURATION_PART)(text)), 0, (total, part) => { + 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 @@ -77,7 +78,8 @@ const rawSeries = (result: PromqlResult): ReadonlyArray => { const peak = (series: RawSeries): number => Arr.reduce(series.points, Number.NEGATIVE_INFINITY, (max, p) => - Number.isFinite(p.v) && p.v > max ? p.v : max, + // 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, ) const byPeakDescending = Order.mapInput(Order.flip(Order.Number), peak) diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 5537a53ccf..5a1a3b850b 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -12,7 +12,7 @@ import { } from "@maple/backend/services/promql/PromqlQueryService" import { CurrentMcpTenant } from "../tenant" import { renderToolDoc } from "../lib/tool-doc" -import { defaultStepSeconds, parseStepSeconds, type PromqlResult } from "../lib/promql-result" +import { capSeries, defaultStepSeconds, parseStepSeconds, type PromqlResult } from "../lib/promql-result" import { registerQueryPromqlTool } from "./query-promql" import type { McpToolError, McpToolRegistrar } from "./types" import type { McpToolRequirements } from "./runtime-services" @@ -228,6 +228,7 @@ describe("query_promql steps", () => { expect(parseStepSeconds("1h30m")).toBe(5400) expect(parseStepSeconds("15")).toBe(15) expect(parseStepSeconds("0")).toBeUndefined() + expect(parseStepSeconds("0s")).toBeUndefined() expect(parseStepSeconds("1 minute")).toBeUndefined() }) @@ -236,4 +237,16 @@ describe("query_promql steps", () => { expect(defaultStepSeconds(6 * 3600)).toBe(300) expect(defaultStepSeconds(7 * 86_400)).toBe(7200) }) + + it("keeps an infinite series when capping, the way a peak ranks", () => { + const series = (i: number, v: number) => ({ labels: { id: String(i) }, points: [{ t: 0, v }] }) + const result: PromqlResult = { + resultType: "matrix", + result: [ + series(0, Number.POSITIVE_INFINITY), + ...Array.from({ length: 25 }, (_, i) => series(i + 1, i)), + ], + } + expect(capSeries(result).some((s) => s.labels.id === "0")).toBe(true) + }) }) From eb36576daf16f50f6d3454d9dc05158c8a06525f Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 16:17:10 +0100 Subject: [PATCH 03/14] fix(promql): suggest a sub-second step the tool accepts query_promql's sum by (job) suggestion wrote a 0.5 s step as 0.5s, which its own step parameter rejects; sub-second steps are written in ms. --- apps/ai/src/mcp/lib/promql-render.ts | 6 +++++- apps/ai/src/mcp/tools/query-promql.test.ts | 10 ++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index 91fb72067b..0f25df1a51 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -129,12 +129,16 @@ const aggregateNext = (output: Output): NextCall | undefined => query: `sum by (job) (${output.query})`, start_time: output.timeRange.start, end_time: output.timeRange.end, - ...(output.instant ? { instant: true } : { step: `${output.stepSeconds}s` }), + ...(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) diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 5a1a3b850b..0053c45924 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -220,6 +220,16 @@ describe("query_promql", () => { ]) }), ) + + it.effect("suggests a sub-second step the tool accepts again", () => + Effect.gen(function* () { + const many = Arr.makeBy(25, (i) => series(`svc-${i}`, [i])) + const { doc } = yield* run({ query: QUERY, ...WINDOW, step: "500ms" }, () => + Effect.succeed({ resultType: "matrix" as const, result: many }), + ) + expect(doc.next?.[0]?.args).toMatchObject({ step: "500ms" }) + }), + ) }) describe("query_promql steps", () => { From 8700188330fc1a9b19f794d3d35ada6181bb2261 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 16:21:52 +0100 Subject: [PATCH 04/14] fix(promql): escape series names once in query_promql tables The renderer already escapes table cells; escaping the series name too turned a label value a|b into a\\\|b. Only the list items, which the renderer leaves alone, are escaped here now. --- apps/ai/src/mcp/lib/promql-render.ts | 7 ++++--- apps/ai/src/mcp/tools/query-promql.test.ts | 12 ++++++++++++ 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index 0f25df1a51..a0ccc7051e 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -1,7 +1,7 @@ // query_promql's model-facing text: per series its labels, summary stats and a few points. import { Array as Arr, Option, Order, Record as Rec, String as Str } from "effect" import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" -import { formatNumber, tableCell } from "./format" +import { formatNumber, tableCell, truncate } from "./format" import { doc, type DocBlock, type NextCall, type ToolDoc } from "./tool-doc" import { MAX_POINTS } from "./promql-result" @@ -73,7 +73,7 @@ const matrixBlocks = (series: ReadonlyArray): ReadonlyArray => Arr.map(series, (s) => { const { min, avg, max } = stats(s) return [ - tableCell(seriesName(s.labels), 100), + truncate(seriesName(s.labels), 100), formatNumber(s.totalPoints), min, avg, @@ -85,6 +85,7 @@ const matrixBlocks = (series: ReadonlyArray): ReadonlyArray => 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)}`, ), ), @@ -101,7 +102,7 @@ const bodyOf = (output: Output): ReadonlyArray => { doc.table( ["Series", "Value"], Arr.map(output.series, (s) => [ - tableCell(seriesName(s.labels), 100), + truncate(seriesName(s.labels), 100), lastValue(s), ]), ), diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 0053c45924..dde06e8bc0 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -260,3 +260,15 @@ describe("query_promql steps", () => { expect(capSeries(result).some((s) => s.labels.id === "0")).toBe(true) }) }) + +describe("query_promql rendering", () => { + it.effect("escapes a | in a label once in the table", () => + Effect.gen(function* () { + const { text } = yield* run({ query: QUERY, ...WINDOW, step: "1m" }, () => + Effect.succeed({ resultType: "matrix" as const, result: [series("a|b", [1])] }), + ) + expect(text).toContain("a\\|b") + expect(text).not.toContain("a\\\\\\|b") + }), + ) +}) From eadf875e1c767dbf80ad056820116cbf01cd1951 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 16:38:54 +0100 Subject: [PATCH 05/14] fix(promql): an empty instant result points at end_time, not start_time query_promql's empty-result hint said to widen start_time, which an instant query never reads; it now says to move end_time. --- apps/ai/src/mcp/lib/promql-render.ts | 5 ++++- apps/ai/src/mcp/tools/query-promql.test.ts | 12 ++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index a0ccc7051e..29f252f543 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -161,7 +161,10 @@ export const renderPromqlOutput = (output: Output): ToolDoc => { 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`.", - "Labels use underscores (`host_name`); `job` is the service name. Widen start_time, or check names with list_metrics.", + // 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.", ], }, } diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index dde06e8bc0..9875e36d54 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -272,3 +272,15 @@ describe("query_promql rendering", () => { }), ) }) + +describe("query_promql empty results", () => { + it.effect("tells an instant query to move end_time, not widen start_time", () => + Effect.gen(function* () { + const { text } = yield* run({ query: QUERY, ...WINDOW, instant: true }, () => + Effect.succeed({ resultType: "vector" as const, result: [] }), + ) + expect(text).toContain("move end_time") + expect(text).not.toContain("Widen start_time") + }), + ) +}) From 4583d2039dbb5a67b215e577e14b40339c8a9e48 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 16:49:19 +0100 Subject: [PATCH 06/14] fix(promql): seconds in sampled times, infinities in the statistics query_promql printed sampled times to the minute, so points 15 or 30 s apart read as the same time; they now carry seconds, and milliseconds below a second. Min, Avg and Max skipped +Inf and -Inf points, so a 1 / 0 series showed no statistics; they are now counted, NaN still skipped. --- apps/ai/src/mcp/lib/promql-render.ts | 30 ++++++++++++++-------- apps/ai/src/mcp/tools/query-promql.test.ts | 17 +++++++++++- 2 files changed, 36 insertions(+), 11 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index 29f252f543..c12b39eec0 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -19,8 +19,9 @@ export const formatSample = (value: typeof PromqlSampleValue.Type): string => { return abs >= 1000 ? formatNumber(Math.round(value * 100) / 100) : String(Number(value.toPrecision(4))) } -/** `MM-DD HH:MM`, UTC. */ -const formatTime = (ms: number): string => Str.replace("T", " ")(Str.slice(5, 16)(new Date(ms).toISOString())) +/** `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())) /** `name{k="v", ...}`, the way Prometheus prints a series. */ export const seriesName = (labels: Series["labels"]): string => { @@ -36,20 +37,29 @@ export const seriesName = (labels: Series["labels"]): string => { return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` } -const finiteValues = (series: Series): ReadonlyArray => - Arr.filter( - Arr.map(series.points, (p) => p.v), - (v): v is number => typeof v === "number", +/** Every value but NaN, infinities included: a `1 / 0` point is the series' max. */ +const orderedValues = (series: Series): ReadonlyArray => + Arr.flatMap(series.points, ({ v }) => + typeof v === "number" ? [v] : v === "+Inf" ? [Infinity] : v === "-Inf" ? [-Infinity] : [], ) +const formatStat = (value: number): string => + Number.isNaN(value) + ? "NaN" + : value === Infinity + ? "+Inf" + : value === -Infinity + ? "-Inf" + : formatSample(value) + const stats = (series: Series) => { - const values = finiteValues(series) + const values = orderedValues(series) if (values.length === 0) return { min: "-", avg: "-", max: "-" } const sum = Arr.reduce(values, 0, (a, b) => a + b) return { - min: formatSample(Math.min(...values)), - avg: formatSample(sum / values.length), - max: formatSample(Math.max(...values)), + min: formatStat(Math.min(...values)), + avg: formatStat(sum / values.length), + max: formatStat(Math.max(...values)), } } diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 9875e36d54..3a528a6db9 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -125,7 +125,7 @@ describe("query_promql", () => { expect(text).toContain('| {http_route="/checkout", job="api"} | 3 | 2 | 4 | 6 | 6 |') expect(text).toContain('| {http_route="/checkout", job="web"} | 3 | 0.5 | 0.75 | 1 | 0.5 |') expect(text).toContain( - '{http_route="/checkout", job="web"}: 11-15 10:59 1, 11-15 10:59 NaN, 11-15 11:00 0.5', + '{http_route="/checkout", job="web"}: 11-15 10:59:00 1, 11-15 10:59:30 NaN, 11-15 11:00:00 0.5', ) }), ) @@ -284,3 +284,18 @@ describe("query_promql empty results", () => { }), ) }) + +describe("query_promql statistics", () => { + it.effect("counts infinite points in the statistics and shows seconds in sampled times", () => + Effect.gen(function* () { + const { text } = yield* run({ query: QUERY, ...WINDOW, step: "15s" }, () => + Effect.succeed({ + resultType: "matrix" as const, + result: [series("svc", [1, Number.POSITIVE_INFINITY])], + }), + ) + expect(text).toContain("| +Inf |") + expect(text).toMatch(/\d{2}:\d{2}:\d{2}/) + }), + ) +}) From 721a0b45f73ede286e58cf67fdeede5be964455b Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 19:03:23 +0100 Subject: [PATCH 07/14] fix(ai): MCP request writes pick the live server when they run, not when they are built effect's withRun buffers writes until the server's run loop starts and picks buffer or server when the write effect is built. A request fiber that yielded between building and running its Eof write buffered it after the drain, so the server never saw the request end and tools/list hung. The 133rd tool moved the yield into that window; the first tools/* request on a fresh isolate can hit it. --- apps/ai/src/mcp/transport/stateless-http.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/apps/ai/src/mcp/transport/stateless-http.ts b/apps/ai/src/mcp/transport/stateless-http.ts index 81d66a8ed5..66033877cc 100644 --- a/apps/ai/src/mcp/transport/stateless-http.ts +++ b/apps/ai/src/mcp/transport/stateless-http.ts @@ -494,7 +494,9 @@ export const layerStatelessMcpHttp = (options: { ) return yield* RpcServer.Protocol.make((writeRequest_) => { - writeRequest = writeRequest_ + // effect's `withRun` buffers writes until the server runs and picks buffer or server when the + // effect is built: a fiber that yields between build and run would buffer after the drain and hang. + writeRequest = (clientId, message) => Effect.suspend(() => writeRequest_(clientId, message)) return Effect.succeed({ disconnects, send: (targetClientId: number, response: FromServerEncoded) => { From 1766b66cc2a6794d0fe735ac8a6a36e0d1fd5e16 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 19:13:19 +0100 Subject: [PATCH 08/14] fix(promql): query_promql quotes label values in series names --- apps/ai/src/mcp/lib/promql-render.ts | 8 ++++++-- apps/ai/src/mcp/tools/query-promql.test.ts | 11 +++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index c12b39eec0..06306104eb 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -1,5 +1,5 @@ // query_promql's model-facing text: per series its labels, summary stats and a few points. -import { Array as Arr, Option, Order, Record as Rec, String as Str } from "effect" +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" @@ -23,6 +23,10 @@ export const formatSample = (value: typeof PromqlSampleValue.Type): string => { 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(/"/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__ ?? "" @@ -31,7 +35,7 @@ export const seriesName = (labels: Series["labels"]): string => { Order.mapInput(Order.String, ([key]: readonly [string, string]) => key), ) const inner = Arr.join( - Arr.map(rest, ([key, value]) => `${key}="${value}"`), + Arr.map(rest, ([key, value]) => `${key}="${escapeLabelValue(value)}"`), ", ", ) return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 3a528a6db9..3e5d8cb0be 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -271,6 +271,17 @@ describe("query_promql rendering", () => { expect(text).not.toContain("a\\\\\\|b") }), ) + + it.effect("quotes label values, so a value holding a quote is not another label", () => + Effect.gen(function* () { + const { text } = yield* run({ query: QUERY, ...WINDOW, step: "1m" }, () => + Effect.succeed({ resultType: "matrix" as const, result: [series('a", y="b', [1])] }), + ) + // The table cell escapes the backslash again; the ambiguous unquoted form never appears. + expect(text).toContain('job="a\\\\", y=\\\\"b"') + expect(text).not.toContain('job="a", y="b"') + }), + ) }) describe("query_promql empty results", () => { From 913e1987319622c6861deeaafbe172fb988a7a6f Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 19:19:47 +0100 Subject: [PATCH 09/14] fix(promql): query_promql blames a too-fine step on step, prints steps it accepts, ranks peaks once --- apps/ai/src/mcp/lib/promql-render.ts | 2 +- apps/ai/src/mcp/lib/promql-result.ts | 20 ++++++++++++++++++-- apps/ai/src/mcp/tools/query-promql.test.ts | 19 +++++++++++++++++++ apps/ai/src/mcp/tools/query-promql.ts | 9 ++++++++- 4 files changed, 46 insertions(+), 4 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index 06306104eb..a9ff742947 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -166,7 +166,7 @@ export const renderPromqlOutput = (output: Output): ToolDoc => { output.instant ? ["At", output.timeRange.end] : ["Window", `${output.timeRange.start} to ${output.timeRange.end}`], - ["Step", output.instant ? undefined : `${output.stepSeconds}s`], + ["Step", output.instant ? undefined : stepText(output.stepSeconds)], ], blocks: bodyOf(output), ...(empty diff --git a/apps/ai/src/mcp/lib/promql-result.ts b/apps/ai/src/mcp/lib/promql-result.ts index 90a0a61a7e..66ab86452f 100644 --- a/apps/ai/src/mcp/lib/promql-result.ts +++ b/apps/ai/src/mcp/lib/promql-result.ts @@ -82,12 +82,28 @@ const peak = (series: RawSeries): number => !Number.isNaN(p.v) && p.v > max ? p.v : max, ) -const byPeakDescending = Order.mapInput(Order.flip(Order.Number), peak) +// 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 => { const all = rawSeries(result) - const kept = all.length > MAX_SERIES ? Arr.take(Arr.sort(all, byPeakDescending), MAX_SERIES) : all + 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) => ({ labels: series.labels, points: Arr.map(Arr.takeRight(series.points, MAX_POINTS), (p) => ({ t: p.t, v: encodeSample(p.v) })), diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 3e5d8cb0be..c8728b6c16 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -181,6 +181,25 @@ describe("query_promql", () => { }), ) + it.effect("refuses a step too fine for the window as a step error, before querying", () => + Effect.gen(function* () { + const error = yield* Effect.flip( + run({ query: "up", ...WINDOW, step: "100ms" }, () => Effect.die("not reached")), + ) + expect(error).toMatchObject({ _tag: "@maple/mcp/errors/McpInvalidInputError", parameter: "step" }) + }), + ) + + it.effect("prints a sub-second step the way the step parameter accepts it", () => + Effect.gen(function* () { + const { text } = yield* run({ query: "up", ...WINDOW, step: "500ms" }, () => + Effect.succeed({ resultType: "matrix" as const, result: [series("api", [1])] }), + ) + expect(text).toContain("500ms") + expect(text).not.toContain("0.5s") + }), + ) + it.effect("keeps the 20 highest series and the last 200 points, and suggests summing by service", () => Effect.gen(function* () { const many = Arr.makeBy(25, (i) => diff --git a/apps/ai/src/mcp/tools/query-promql.ts b/apps/ai/src/mcp/tools/query-promql.ts index b519ae1932..e16920880e 100644 --- a/apps/ai/src/mcp/tools/query-promql.ts +++ b/apps/ai/src/mcp/tools/query-promql.ts @@ -7,7 +7,7 @@ import { renderPromqlOutput } from "../lib/promql-render" import * as P from "../lib/params" import { Effect, Schema } from "effect" import { parseWarehouseDateTime } from "@maple/query-engine" -import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" +import { MAX_STEPS, PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" const WINDOW = P.timeWindow({ defaultHours: 1, maxHours: 7 * 24 }) @@ -51,6 +51,13 @@ export function registerQueryPromqlTool(server: McpToolRegistrar) { }) } const stepSeconds = instant ? 0 : (requested ?? defaultStepSeconds((endMs - startMs) / 1000)) + if (!instant && (endMs - startMs) / (stepSeconds * 1000) > MAX_STEPS) { + return yield* new McpInvalidInputError({ + message: `step "${params.step ?? `${stepSeconds}s`}" gives more than ${MAX_STEPS} points over this window; use at least ${Math.ceil((endMs - startMs) / 1000 / MAX_STEPS)}s.`, + parameter: "step", + example: `${defaultStepSeconds((endMs - startMs) / 1000)}s`, + }) + } yield* Effect.annotateCurrentSpan({ orgId: tenant.orgId, "maple.ai.promql.instant": instant, From 41309d62bbf1a531a8f0c77e9e9408ee8e9166e8 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 19:42:25 +0100 Subject: [PATCH 10/14] chore(promql): escape label values with one character class --- apps/ai/src/mcp/lib/promql-render.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index a9ff742947..c3582e3e79 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -25,7 +25,7 @@ const formatTime = (ms: number): string => /** 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(/"/g, '\\"'), Str.replace(/\n/g, "\\n")) + 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 => { From 3e8a0513c5e2d878bfb4e60681fbc54415f5a6d0 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 19:16:05 +0100 Subject: [PATCH 11/14] test(promql): assert sampled times keep their seconds in the point list --- apps/ai/src/mcp/tools/query-promql.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index c8728b6c16..b83b47f961 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -325,7 +325,7 @@ describe("query_promql statistics", () => { }), ) expect(text).toContain("| +Inf |") - expect(text).toMatch(/\d{2}:\d{2}:\d{2}/) + expect(text).toContain("11-15 10:59:30 1, 11-15 11:00:00 +Inf") }), ) }) From c485dee03388c8d865d683c8ea0715623277a908 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 19:34:33 +0100 Subject: [PATCH 12/14] fix(promql): query_promql's step gate counts the window's end point, as the engine does --- apps/ai/src/mcp/tools/query-promql.test.ts | 18 ++++++++++++++++++ apps/ai/src/mcp/tools/query-promql.ts | 5 +++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index b83b47f961..39bdb79f93 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -190,6 +190,24 @@ describe("query_promql", () => { }), ) + it.effect("counts the window's end point, as the engine does, when refusing a step", () => + Effect.gen(function* () { + // 1 100 s at 100ms is exactly 11 000 steps, which the engine evaluates as 11 001 points. + const error = yield* Effect.flip( + run( + { + query: "up", + start_time: "2026-11-15 10:00:00", + end_time: "2026-11-15 10:18:20", + step: "100ms", + }, + () => Effect.die("not reached"), + ), + ) + expect(error).toMatchObject({ _tag: "@maple/mcp/errors/McpInvalidInputError", parameter: "step" }) + }), + ) + it.effect("prints a sub-second step the way the step parameter accepts it", () => Effect.gen(function* () { const { text } = yield* run({ query: "up", ...WINDOW, step: "500ms" }, () => diff --git a/apps/ai/src/mcp/tools/query-promql.ts b/apps/ai/src/mcp/tools/query-promql.ts index e16920880e..2945276eef 100644 --- a/apps/ai/src/mcp/tools/query-promql.ts +++ b/apps/ai/src/mcp/tools/query-promql.ts @@ -51,9 +51,10 @@ export function registerQueryPromqlTool(server: McpToolRegistrar) { }) } const stepSeconds = instant ? 0 : (requested ?? defaultStepSeconds((endMs - startMs) / 1000)) - if (!instant && (endMs - startMs) / (stepSeconds * 1000) > MAX_STEPS) { + // The engine evaluates floor(range / step) + 1 points, the end included. + if (!instant && Math.floor((endMs - startMs) / (stepSeconds * 1000)) + 1 > MAX_STEPS) { return yield* new McpInvalidInputError({ - message: `step "${params.step ?? `${stepSeconds}s`}" gives more than ${MAX_STEPS} points over this window; use at least ${Math.ceil((endMs - startMs) / 1000 / MAX_STEPS)}s.`, + message: `step "${params.step ?? `${stepSeconds}s`}" gives more than ${MAX_STEPS} points over this window; use at least ${Math.ceil((endMs - startMs) / 1000 / (MAX_STEPS - 1))}s.`, parameter: "step", example: `${defaultStepSeconds((endMs - startMs) / 1000)}s`, }) From bb15f5fb580515f9c2c279eb3962d465184faea3 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 19:41:18 +0100 Subject: [PATCH 13/14] fix(promql): query_promql's min/avg/max cover every point, not only the listed ones --- apps/ai/src/mcp/lib/promql-render.ts | 33 +++++-------------- apps/ai/src/mcp/lib/promql-result.ts | 32 +++++++++++++++--- apps/ai/src/mcp/tool-descriptors.generated.ts | 2 +- apps/ai/src/mcp/tools/query-promql.test.ts | 11 +++++++ packages/domain/src/mcp-outputs/promql.ts | 4 +++ 5 files changed, 51 insertions(+), 31 deletions(-) diff --git a/apps/ai/src/mcp/lib/promql-render.ts b/apps/ai/src/mcp/lib/promql-render.ts index c3582e3e79..f3e10ad315 100644 --- a/apps/ai/src/mcp/lib/promql-render.ts +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -41,31 +41,14 @@ export const seriesName = (labels: Series["labels"]): string => { return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` } -/** Every value but NaN, infinities included: a `1 / 0` point is the series' max. */ -const orderedValues = (series: Series): ReadonlyArray => - Arr.flatMap(series.points, ({ v }) => - typeof v === "number" ? [v] : v === "+Inf" ? [Infinity] : v === "-Inf" ? [-Infinity] : [], - ) - -const formatStat = (value: number): string => - Number.isNaN(value) - ? "NaN" - : value === Infinity - ? "+Inf" - : value === -Infinity - ? "-Inf" - : formatSample(value) - -const stats = (series: Series) => { - const values = orderedValues(series) - if (values.length === 0) return { min: "-", avg: "-", max: "-" } - const sum = Arr.reduce(values, 0, (a, b) => a + b) - return { - min: formatStat(Math.min(...values)), - avg: formatStat(sum / values.length), - max: formatStat(Math.max(...values)), - } -} +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) }) diff --git a/apps/ai/src/mcp/lib/promql-result.ts b/apps/ai/src/mcp/lib/promql-result.ts index 66ab86452f..fc34241b1e 100644 --- a/apps/ai/src/mcp/lib/promql-result.ts +++ b/apps/ai/src/mcp/lib/promql-result.ts @@ -104,11 +104,33 @@ export const capSeries = (result: PromqlResult): ReadonlyArray series, ) : all - return Arr.map(kept, (series) => ({ - labels: series.labels, - points: Arr.map(Arr.takeRight(series.points, MAX_POINTS), (p) => ({ t: p.t, v: encodeSample(p.v) })), - totalPoints: series.points.length, - })) + 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: { diff --git a/apps/ai/src/mcp/tool-descriptors.generated.ts b/apps/ai/src/mcp/tool-descriptors.generated.ts index 06eb7e6a6a..e67eed36ed 100644 --- a/apps/ai/src/mcp/tool-descriptors.generated.ts +++ b/apps/ai/src/mcp/tool-descriptors.generated.ts @@ -26,7 +26,7 @@ export const MCP_TOOL_DESCRIPTORS: ReadonlyArray = [ {"name":"error_detail","title":"Error Detail","description":"Sample traces (failing span, correlated logs) and a summary for one error, by `fingerprint` (decimal UInt64 from find_errors) or `issue_id` (UUID from list_error_issues). Without start_time/end_time it counts the last 30 days and samples the 6 hours before the last occurrence. Use inspect_trace on a trace_id for the full span tree.","inputSchema":{"type":"object","properties":{"fingerprint":{"type":"string","description":"The error FingerprintHash from find_errors or list_error_issues: a decimal UInt64 string, e.g. \"11640295108927840024\"."},"issue_id":{"type":"string","description":"An error issue id from list_error_issues (its UUID or its REST id, iss_\u2026), instead of fingerprint."},"start_time":{"type":"string","description":"Start of the window, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Omit both bounds to anchor on the error's last occurrence in the past 30 days."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"include_timeseries":{"type":"boolean","description":"Include error count over time to see if the error is trending up or down"},"limit":{"type":"number","description":"Max sample traces to return (default 5, max 20)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"fingerprintHash":{"type":"string"},"error":{"type":"object","properties":{"label":{"type":"string"},"exceptionType":{"type":"string"},"message":{"type":"string"},"serviceName":{"type":"string"}},"required":["label","exceptionType","message","serviceName"],"additionalProperties":true},"issueId":{"type":"string"},"otherFingerprints":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"occurrences":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"firstSeen":{"type":"string"},"lastSeen":{"type":"string"},"services":{"type":"array","items":{"type":"string"}},"serviceCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"noExceptionCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["timeRange","occurrences","firstSeen","lastSeen","services","serviceCount","noExceptionCount"],"additionalProperties":true},"anchored":{"type":"boolean"},"related":{"type":"array","items":{"type":"object","properties":{"fingerprintHash":{"type":"string"},"label":{"type":"string"},"serviceName":{"type":"string"},"traces":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["fingerprintHash","label","serviceName","traces"],"additionalProperties":true}},"traces":{"type":"array","items":{"type":"object","properties":{"traceId":{"type":"string"},"rootSpanName":{"type":"string"},"durationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"spanCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"services":{"type":"array","items":{"type":"string"}},"startTime":{"type":"string"},"errorMessage":{"type":"string"},"errorSpan":{"type":"object","properties":{"spanId":{"type":"string"},"name":{"type":"string"},"serviceName":{"type":"string"},"statusMessage":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["spanId","name","serviceName","statusMessage","attributes"],"additionalProperties":true},"logs":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"severityText":{"type":"string"},"body":{"type":"string"}},"required":["timestamp","severityText","body"],"additionalProperties":true}}},"required":["traceId","rootSpanName","durationMs","spanCount","services","startTime","logs"],"additionalProperties":true}},"timeseries":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"count":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["bucket","count"],"additionalProperties":true}},"service":{"type":"string"}},"required":["timeRange","fingerprintHash","traces"],"additionalProperties":true},"annotations":{"title":"Error Detail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"list_metrics","title":"List Metrics","description":"Discover custom metrics with their type, unit, monotonicity and data volume. Pass a discovered `metric_name` and `metric_type` to query_data source=metrics.","inputSchema":{"type":"object","properties":{"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time. Covers at most 30 days; a wider window is narrowed to the 30 days before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"search":{"type":"string","description":"Substring of the metric name"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"],"description":"Only metrics of this type"},"offset":{"type":"number","description":"Rows to skip, for paging (default 0). Use the `next` call a truncated result gives."},"limit":{"type":"number","description":"Max metrics to return (default 50, max 500)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"pagination":{"type":"object","properties":{"offset":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"hasMore":{"type":"boolean"},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"nextOffset":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["offset","limit","hasMore"],"additionalProperties":true},"summary":{"type":"array","items":{"type":"object","properties":{"metricType":{"type":"string"},"metricCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"dataPointCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["metricType","metricCount","dataPointCount"],"additionalProperties":true}},"metrics":{"type":"array","items":{"type":"object","properties":{"metricName":{"type":"string"},"metricType":{"type":"string"},"serviceName":{"type":"string"},"metricUnit":{"type":"string"},"isMonotonic":{"type":"boolean"},"dataPointCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["metricName","metricType","serviceName","metricUnit","isMonotonic","dataPointCount"],"additionalProperties":true}},"filters":{"type":"object","properties":{"service":{"type":"string"},"search":{"type":"string"},"metricType":{"type":"string"}},"additionalProperties":true}},"required":["timeRange","summary","metrics"],"additionalProperties":true},"annotations":{"title":"List Metrics","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"query_data","title":"Query Data","description":"Aggregate traces, logs, metrics or product events into a timeseries or a top-N breakdown. Start here for trends, comparisons and top-N; for errors prefer find_errors and error_detail; for a shape this tool cannot express, run_sql. Applied defaults are listed in the result. A traces breakdown by span_name or attribute reads raw spans: set `service` and keep the window short (a window too large is narrowed, with a note). For endpoint volume over days use route_usage.","inputSchema":{"type":"object","properties":{"source":{"type":"string","enum":["traces","logs","metrics","product_events"],"description":"'traces' for request/span analysis (latency, errors, throughput); 'logs' for log volume; 'metrics' for a custom metric (needs metric_name and metric_type from list_metrics); 'product_events' for track() events, page views and server events (names from list_product_events). Signups and accounts in a connected system (Clerk, a database) are data sources: search_data_sources."},"kind":{"type":"string","enum":["timeseries","breakdown"],"description":"'timeseries' for how a value changed over time; 'breakdown' for top-N or distribution. Pick the right one first rather than calling twice."},"metric":{"type":"string","description":"Traces: count, avg_duration, p50_duration, p95_duration, p99_duration, error_rate (0-1 ratio; for a count of errors use count with status Error, which error_count is read as), apdex (needs apdex_threshold_ms). Logs: count. Product events: count, sessions, persons, users, visitors. Metrics: avg, sum, min, max, count, rate, increase. For counters (sum metrics, Prometheus *_total gauges) use increase (total over the window) or rate (per second); both are per-series and reset-aware. sum adds raw samples. Default: count, or avg for metrics."},"group_by":{"type":"string","description":"Traces: service, span_name, status_code, http_method, attribute, resource_attribute. Logs: service, severity; breakdowns also attribute, resource_attribute. Metrics: service, attribute, resource_attribute. Product events: event_name, kind, source, host, page_path, service, group, attribute. 'attribute' and 'resource_attribute' need attribute_key (resource_attribute reads resource keys such as k8s.pod.name or deployment.environment; per commit is resource_attribute with attribute_key=vcs.ref.head.revision). Timeseries also take 'none' (the default); breakdown defaults to service."},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only this service (exact `service.name`)"},"span_name":{"type":"string","description":"Filter by span name (traces only). Exact match first; when nothing matches exactly it is matched as a case-insensitive substring"},"root_spans_only":{"type":"boolean","description":"Only include root spans (traces only)"},"environments":{"type":"array","items":{"type":"string"},"description":"Only these deployment environments (traces, logs, metrics; explore_attributes source=services lists them)"},"commit_shas":{"type":"array","items":{"type":"string"},"description":"Commit SHAs to filter (traces only)"},"apdex_threshold_ms":{"type":"number","description":"Apdex threshold in ms (traces only; needed for metric=apdex)"},"severity":{"type":"string","enum":["TRACE","DEBUG","INFO","WARN","ERROR","FATAL"],"description":"Only this log severity (logs only)"},"event_name":{"type":"array","items":{"type":"string"},"description":"Only these event names (product_events only)"},"event_kind":{"type":"array","items":{"type":"string","enum":["navigation","custom","screen"]},"description":"Only these event kinds (product_events only)"},"host":{"type":"string","description":"Only events fired on this site host (product_events only)"},"page_path":{"type":"string","description":"Only events fired on this page path (product_events only)"},"metric_name":{"type":"string","description":"The metric, from list_metrics (source=metrics only)"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"],"description":"Type of `metric_name`, as list_metrics reports it"},"attribute_key":{"type":"string","description":"Attribute to filter on, or to group by with group_by=attribute. Span (or log/metric label) and resource attributes both work; the scope is resolved automatically"},"attribute_value":{"type":"string","description":"Exact value for attribute_key. Also applies when grouping by the same key"},"attribute_scope":{"type":"string","enum":["span","resource"],"description":"Where attribute_key lives: 'span' (span, log or metric-datapoint attributes) or 'resource' (deployment.environment, k8s.pod.name...). Resolved from the known keys when omitted"},"bucket_seconds":{"type":"number","description":"Bucket width in seconds (timeseries only; auto-computed when omitted)"},"limit":{"type":"number","description":"Max rows of a breakdown (default 10, max 100)"}},"required":["source","kind"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"kind":{"type":"string"},"metric":{"type":"string"},"groupBy":{"type":"string"},"decisions":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"queryContext":{"type":"object","properties":{"source":{"type":"string","enum":["traces","logs","metrics","product_events"]},"serviceName":{"type":"string"},"eventName":{"type":"string"},"eventKind":{"type":"string"},"host":{"type":"string"},"pagePath":{"type":"string"},"spanName":{"type":"string"},"rootSpansOnly":{"type":"boolean"},"environments":{"type":"array","items":{"type":"string"}},"commitShas":{"type":"array","items":{"type":"string"}},"severity":{"type":"string"},"metricName":{"type":"string"},"metricType":{"type":"string"},"attributeFilters":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"mode":{"type":"string"}},"required":["key","mode"],"additionalProperties":true}},"apdexThresholdMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"bucketSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["source"],"additionalProperties":true},"unit":{"type":"string","enum":["duration_ms","duration_us","duration_s","duration_ns","percent","number","bytes","requests_per_sec"]},"result":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["timeseries"]},"data":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string"},"series":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}}},"required":["bucket","series"],"additionalProperties":true}}},"required":["kind","data"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["breakdown"]},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["name","value"],"additionalProperties":true}}},"required":["kind","data"],"additionalProperties":true}]},"emptyHints":{"type":"array","items":{"type":"string"}}},"required":["timeRange","kind","metric","queryContext","unit","result"],"additionalProperties":true},"annotations":{"title":"Query Data","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, - {"name":"query_promql","title":"Query PromQL","description":"Run a PromQL query over the org's metrics, Prometheus-exact. Range evaluation over start_time..end_time by default; instant=true evaluates once at end_time. Metric names are Prometheus-style, translated from OTel: dots become underscores and the unit is a suffix (`http.server.request.duration` in s is `http_server_request_duration_seconds`), monotonic sums end in `_total`, histograms read as `_bucket` (with `le`), `_count` and `_sum`. Labels are attribute keys with underscores (`host.name` is `host_name`); `job` is the service name, `instance` the service instance id. Examples: `sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`; `histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket[5m])))`; `sum by (job) (rate(http_server_request_duration_seconds_count{http_response_status_code=~\"5..\"}[5m])) / sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`. Use list_metrics to find the OTel names. Returns at most 20 series (highest peaks) and the last 200 points of each.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"PromQL expression, e.g. sum by (job) (rate(http_server_request_duration_seconds_count[5m]))"},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 1 hour before end_time. Covers at most 7 days; a wider window is narrowed to the 7 days before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"step":{"type":"string","description":"Range resolution as a Prometheus duration (`30s`, `1m`, `1h`) or seconds. Default: a round step giving about 60 to 120 points."},"instant":{"type":"boolean","description":"Evaluate once at end_time instead of over the window (default false)"}},"required":["query"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"query":{"type":"string"},"resultType":{"type":"string","enum":["matrix","vector","scalar","string"]},"instant":{"type":"boolean"},"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"stepSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"series":{"type":"array","items":{"type":"object","properties":{"labels":{"type":"object","additionalProperties":{"type":"string"}},"points":{"type":"array","items":{"type":"object","properties":{"t":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"v":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]}},"required":["t","v"],"additionalProperties":true}},"totalPoints":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["labels","points","totalPoints"],"additionalProperties":true}},"totalSeries":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"stringValue":{"type":"string"}},"required":["query","resultType","instant","timeRange","stepSeconds","series","totalSeries"],"additionalProperties":true},"annotations":{"title":"Query PromQL","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, + {"name":"query_promql","title":"Query PromQL","description":"Run a PromQL query over the org's metrics, Prometheus-exact. Range evaluation over start_time..end_time by default; instant=true evaluates once at end_time. Metric names are Prometheus-style, translated from OTel: dots become underscores and the unit is a suffix (`http.server.request.duration` in s is `http_server_request_duration_seconds`), monotonic sums end in `_total`, histograms read as `_bucket` (with `le`), `_count` and `_sum`. Labels are attribute keys with underscores (`host.name` is `host_name`); `job` is the service name, `instance` the service instance id. Examples: `sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`; `histogram_quantile(0.95, sum by (le) (rate(http_server_request_duration_seconds_bucket[5m])))`; `sum by (job) (rate(http_server_request_duration_seconds_count{http_response_status_code=~\"5..\"}[5m])) / sum by (job) (rate(http_server_request_duration_seconds_count[5m]))`. Use list_metrics to find the OTel names. Returns at most 20 series (highest peaks) and the last 200 points of each.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"PromQL expression, e.g. sum by (job) (rate(http_server_request_duration_seconds_count[5m]))"},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 1 hour before end_time. Covers at most 7 days; a wider window is narrowed to the 7 days before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"step":{"type":"string","description":"Range resolution as a Prometheus duration (`30s`, `1m`, `1h`) or seconds. Default: a round step giving about 60 to 120 points."},"instant":{"type":"boolean","description":"Evaluate once at end_time instead of over the window (default false)"}},"required":["query"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"query":{"type":"string"},"resultType":{"type":"string","enum":["matrix","vector","scalar","string"]},"instant":{"type":"boolean"},"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"stepSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"series":{"type":"array","items":{"type":"object","properties":{"labels":{"type":"object","additionalProperties":{"type":"string"}},"points":{"type":"array","items":{"type":"object","properties":{"t":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"v":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]}},"required":["t","v"],"additionalProperties":true}},"totalPoints":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"stats":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]},"avg":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]},"max":{"anyOf":[{"type":"number"},{"type":"string","enum":["NaN","+Inf","-Inf"]}]}},"required":["min","avg","max"],"additionalProperties":true}},"required":["labels","points","totalPoints"],"additionalProperties":true}},"totalSeries":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"stringValue":{"type":"string"}},"required":["query","resultType","instant","timeRange","stepSeconds","series","totalSeries"],"additionalProperties":true},"annotations":{"title":"Query PromQL","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"run_sql","title":"Run SQL","description":"Run one read-only ClickHouse SELECT against Maple's own telemetry warehouse (this org's traces, logs, metrics) and return its rows: at most 1000 are fetched and the first 100 rendered, with the count reported. Use it for what query_data cannot express, to spot-check data, or to test SQL for a raw_sql widget. For trends and top-N prefer query_data. The SQL must AND in `$__orgFilter`; macros are listed on `sql`. Spans are in `traces` (no otel_spans/spans table), log lines in `logs`; also metrics_sum/metrics_gauge/metrics_histogram, error_events, session_replays, product_events and *_hourly/*_minutely rollups. Select 64-bit IDs and hashes as toString(col). Attribute columns are Map(String, String): SpanAttributes['http.route'], never JSON* functions. In traces the name is SpanName, StatusCode is 'Ok'/'Error' and Duration is nanoseconds. trace_list_mv is one root span per trace with HttpRoute/HttpMethod/HttpStatusCode (a String) columns and no attribute maps or ParentSpanId. Rollups (*_hourly/*_minutely) keep time in Hour/Minute and counts in SpanCount; merge their AggregateFunction columns. Compare timestamps to 'YYYY-MM-DD HH:MM:SS', not ISO T/Z strings; bucket with toStartOfInterval. Call describe_warehouse_tables for a table's columns, units and enum casing before guessing names. It cannot reach databases or APIs the org connected as data sources: query those with query_data_source.","inputSchema":{"type":"object","properties":{"sql":{"type":"string","description":"The SELECT. It MUST contain `$__orgFilter` (expands to `(OrgId = '')`) as a top-level AND condition; a query without it, or with it OR-ed against another condition, is rejected. In joins use `$__orgFilter(alias)` (`(alias.OrgId = '')`) once per joined table. Other macros: `$__timeFilter(Column)` (`Column >= AND Column <= `), `$__startTime`, `$__endTime`, `$__interval_s` (bucket width for toStartOfInterval). Only one statement; DDL/DML, SETTINGS and system tables are rejected."},"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"granularity_seconds":{"type":"number","description":"Value of `$__interval_s`. Auto-computed from the window when omitted."},"max_cell_chars":{"type":"number","description":"Clip each rendered cell to this many characters (default 120, max 2000). Raise it to read long values such as log bodies or stack traces."},"show_sql":{"type":"boolean","description":"Also return the macro-expanded SQL that ran (default false)."},"reason":{"type":"string","description":"Why you are running this query, in a sentence. Optional; does not change the query."}},"required":["sql"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"rowCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object"}},"truncated":{"type":"boolean"},"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"maxCellChars":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"windowApplied":{"type":"boolean"},"expandedSql":{"type":"string"},"atRowCap":{"type":"boolean"},"rewrites":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"reason":{"type":"string"}},"required":["from","to"],"additionalProperties":true}},"managedOnlyTables":{"type":"array","items":{"type":"string"}}},"required":["rowCount","columns","rows","truncated","timeRange"],"additionalProperties":true},"annotations":{"title":"Run SQL","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"service_map","title":"Service Map","description":"Show service-to-service dependencies with call counts, error rates, and latency per edge. Use to understand system architecture and identify problematic inter-service calls.","inputSchema":{"type":"object","properties":{"start_time":{"type":"string","description":"Window start, UTC (YYYY-MM-DD HH:mm:ss or ISO 8601). Default: 6 hours before end_time."},"end_time":{"type":"string","description":"Window end, UTC, same format. Default: now."},"service":{"type":"string","description":"Only edges involving this service, as source or target (exact `service.name`)"},"environment":{"type":"string","description":"Only this deployment environment (e.g. production, staging)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"timeRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":true},"edges":{"type":"array","items":{"type":"object","properties":{"sourceService":{"type":"string"},"targetService":{"type":"string"},"callCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"errorCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"avgDurationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"maxDurationMs":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["sourceService","targetService","callCount","errorCount","avgDurationMs","maxDurationMs"],"additionalProperties":true}},"serviceCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"service":{"type":"string"},"environment":{"type":"string"}},"required":["timeRange","edges","serviceCount"],"additionalProperties":true},"annotations":{"title":"Service Map","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"list_alert_rules","title":"List Alert Rules","description":"List configured alert rules with severity, signal type and condition. Use list_alert_incidents for what has fired.","inputSchema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"string"},"description":"Only rules covering any of these services: scoped to them, scoped to every service, or raw_query rules whose SQL or name mentions them"},"signal_type":{"type":"string","enum":["error_rate","p95_latency","p99_latency","apdex","throughput","builder_query","raw_query","anomaly"],"description":"Only rules on this signal type"},"severity":{"type":"string","enum":["warning","critical"],"description":"Only rules with this severity"},"enabled_only":{"type":"boolean","description":"Only enabled rules"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"severity":{"type":"string"},"serviceNames":{"type":"array","items":{"type":"string"}},"environments":{"type":"array","items":{"type":"string"}},"anomalySignals":{"type":"array","items":{"type":"string"}},"signalType":{"type":"string"},"comparator":{"type":"string"},"threshold":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"windowMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"evaluationIntervalMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"slowedIntervalMinutes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"destinationIds":{"type":"array","items":{"type":"string"}},"escalationChains":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"chainId":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["severity","chainId"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","enabled","severity","serviceNames","environments","signalType","comparator","threshold","windowMinutes","evaluationIntervalMinutes","slowedIntervalMinutes","destinationIds","createdAt","updatedAt"],"additionalProperties":true}},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"services":{"type":"array","items":{"type":"string"}},"signalType":{"type":"string"},"severity":{"type":"string"},"enabledOnly":{"type":"boolean"}},"required":["rules","total"],"additionalProperties":true},"annotations":{"title":"List Alert Rules","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 39bdb79f93..6260cdeeef 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -334,6 +334,17 @@ describe("query_promql empty results", () => { }) describe("query_promql statistics", () => { + it.effect("summarises every point, not only the listed ones", () => + Effect.gen(function* () { + // The peak sits before the last 200 points, which are all that get listed. + const values = Arr.map(Arr.range(1, 241), (i) => (i === 10 ? 99 : 1)) + const { text } = yield* run({ query: QUERY, ...WINDOW, step: "15s" }, () => + Effect.succeed({ resultType: "matrix" as const, result: [series("svc", values, 15_000)] }), + ) + expect(text).toContain("| 241 | 1 | 1.407 | 99 | 1 |") + }), + ) + it.effect("counts infinite points in the statistics and shows seconds in sampled times", () => Effect.gen(function* () { const { text } = yield* run({ query: QUERY, ...WINDOW, step: "15s" }, () => diff --git a/packages/domain/src/mcp-outputs/promql.ts b/packages/domain/src/mcp-outputs/promql.ts index db3ab5114f..fdca568f9e 100644 --- a/packages/domain/src/mcp-outputs/promql.ts +++ b/packages/domain/src/mcp-outputs/promql.ts @@ -13,6 +13,10 @@ export const PromqlSeries = Schema.Struct({ /** The last `points` samples of the series; `totalPoints` counts them all. */ points: Schema.Array(PromqlPoint), totalPoints: Schema.Number, + /** Min, average and max over every point, not only the listed ones; absent when all are NaN. */ + stats: Schema.optionalKey( + Schema.Struct({ min: PromqlSampleValue, avg: PromqlSampleValue, max: PromqlSampleValue }), + ), }) export const QueryPromqlOutput = Schema.Struct({ From 5f59816168f6cfc5c992d25268b764c33095fda4 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Mon, 16 Nov 2026 19:54:23 +0100 Subject: [PATCH 14/14] fix(promql): query_promql's step gate follows the engine's interval rule --- apps/ai/src/mcp/tools/query-promql.test.ts | 22 +++++++++++----------- apps/ai/src/mcp/tools/query-promql.ts | 6 +++--- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/apps/ai/src/mcp/tools/query-promql.test.ts b/apps/ai/src/mcp/tools/query-promql.test.ts index 6260cdeeef..b32f7f84bb 100644 --- a/apps/ai/src/mcp/tools/query-promql.test.ts +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -190,19 +190,19 @@ describe("query_promql", () => { }), ) - it.effect("counts the window's end point, as the engine does, when refusing a step", () => + it.effect("allows exactly the engine's step limit and refuses one step more", () => Effect.gen(function* () { - // 1 100 s at 100ms is exactly 11 000 steps, which the engine evaluates as 11 001 points. + // 1 100 s at 100ms is exactly 11 000 steps, which Prometheus and the engine accept. + const window = { start_time: "2026-11-15 10:00:00", end_time: "2026-11-15 10:18:20" } + const calls: Array = [] + yield* run( + { query: "up", ...window, step: "100ms" }, + () => Effect.succeed({ resultType: "matrix" as const, result: [] }), + calls, + ) + expect(calls).toHaveLength(1) const error = yield* Effect.flip( - run( - { - query: "up", - start_time: "2026-11-15 10:00:00", - end_time: "2026-11-15 10:18:20", - step: "100ms", - }, - () => Effect.die("not reached"), - ), + run({ query: "up", ...window, step: "99ms" }, () => Effect.die("not reached")), ) expect(error).toMatchObject({ _tag: "@maple/mcp/errors/McpInvalidInputError", parameter: "step" }) }), diff --git a/apps/ai/src/mcp/tools/query-promql.ts b/apps/ai/src/mcp/tools/query-promql.ts index 2945276eef..7db46e1b3c 100644 --- a/apps/ai/src/mcp/tools/query-promql.ts +++ b/apps/ai/src/mcp/tools/query-promql.ts @@ -51,10 +51,10 @@ export function registerQueryPromqlTool(server: McpToolRegistrar) { }) } const stepSeconds = instant ? 0 : (requested ?? defaultStepSeconds((endMs - startMs) / 1000)) - // The engine evaluates floor(range / step) + 1 points, the end included. - if (!instant && Math.floor((endMs - startMs) / (stepSeconds * 1000)) + 1 > MAX_STEPS) { + // The engine's rule, as Prometheus': at most MAX_STEPS whole steps across the window. + if (!instant && Math.floor((endMs - startMs) / (stepSeconds * 1000)) > MAX_STEPS) { return yield* new McpInvalidInputError({ - message: `step "${params.step ?? `${stepSeconds}s`}" gives more than ${MAX_STEPS} points over this window; use at least ${Math.ceil((endMs - startMs) / 1000 / (MAX_STEPS - 1))}s.`, + message: `step "${params.step ?? `${stepSeconds}s`}" gives more than ${MAX_STEPS} steps over this window; use at least ${Math.ceil((endMs - startMs) / 1000 / MAX_STEPS)}s.`, parameter: "step", example: `${defaultStepSeconds((endMs - startMs) / 1000)}s`, })