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..f3e10ad315 --- /dev/null +++ b/apps/ai/src/mcp/lib/promql-render.ts @@ -0,0 +1,197 @@ +// query_promql's model-facing text: per series its labels, summary stats and a few points. +import { Array as Arr, Option, Order, pipe, Record as Rec, String as Str } from "effect" +import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" +import { formatNumber, tableCell, truncate } from "./format" +import { doc, type DocBlock, type NextCall, type ToolDoc } from "./tool-doc" +import { MAX_POINTS } from "./promql-result" + +type Output = typeof QueryPromqlOutput.Type +type Series = typeof PromqlSeries.Type + +/** Series that also list sampled points, and how many points each. */ +const DETAILED_SERIES = 5 +const SAMPLED_POINTS = 6 + +export const formatSample = (value: typeof PromqlSampleValue.Type): string => { + if (typeof value === "string") return value + if (Number.isInteger(value)) return formatNumber(value) + const abs = Math.abs(value) + return abs >= 1000 ? formatNumber(Math.round(value * 100) / 100) : String(Number(value.toPrecision(4))) +} + +/** `MM-DD HH:MM:SS`, UTC, with milliseconds when a step is finer than a second. */ +const formatTime = (ms: number): string => + Str.replace("T", " ")(Str.slice(5, ms % 1000 === 0 ? 19 : 23)(new Date(ms).toISOString())) + +/** A label value as Prometheus quotes it: backslash, double quote and newline escaped. */ +const escapeLabelValue = (value: string): string => + pipe(value, Str.replace(/[\\"]/g, "\\$&"), Str.replace(/\n/g, "\\n")) + +/** `name{k="v", ...}`, the way Prometheus prints a series. */ +export const seriesName = (labels: Series["labels"]): string => { + const name = labels.__name__ ?? "" + const rest = Arr.sort( + Arr.filter(Rec.toEntries(labels), ([key]) => key !== "__name__"), + Order.mapInput(Order.String, ([key]: readonly [string, string]) => key), + ) + const inner = Arr.join( + Arr.map(rest, ([key, value]) => `${key}="${escapeLabelValue(value)}"`), + ", ", + ) + return rest.length === 0 && name !== "" ? name : `${name}{${inner}}` +} + +const stats = (series: Series) => + series.stats === undefined + ? { min: "-", avg: "-", max: "-" } + : { + min: formatSample(series.stats.min), + avg: formatSample(series.stats.avg), + max: formatSample(series.stats.max), + } + +const lastValue = (series: Series): string => + Option.match(Arr.last(series.points), { onNone: () => "-", onSome: (p) => formatSample(p.v) }) + +/** Evenly spaced points across the series, its last point included. */ +const sampled = (series: Series): string => { + const n = series.points.length + const stride = Math.max(1, Math.ceil(n / SAMPLED_POINTS)) + const picked = Arr.filter(series.points, (_, i) => (n - 1 - i) % stride === 0) + return Arr.join( + Arr.map(Arr.takeRight(picked, SAMPLED_POINTS), (p) => `${formatTime(p.t)} ${formatSample(p.v)}`), + ", ", + ) +} + +const matrixBlocks = (series: ReadonlyArray): ReadonlyArray => [ + doc.table( + ["Series", "Points", "Min", "Avg", "Max", "Last"], + Arr.map(series, (s) => { + const { min, avg, max } = stats(s) + return [ + truncate(seriesName(s.labels), 100), + formatNumber(s.totalPoints), + min, + avg, + max, + lastValue(s), + ] + }), + ), + doc.list( + Arr.map( + Arr.take(series, DETAILED_SERIES), + // Table cells are escaped by the renderer; list items are not. + (s) => `${tableCell(seriesName(s.labels), 100)}: ${sampled(s)}`, + ), + ), +] + +const bodyOf = (output: Output): ReadonlyArray => { + switch (output.resultType) { + case "matrix": + return output.series.length === 0 ? [] : matrixBlocks(output.series) + case "vector": + return output.series.length === 0 + ? [] + : [ + doc.table( + ["Series", "Value"], + Arr.map(output.series, (s) => [ + truncate(seriesName(s.labels), 100), + lastValue(s), + ]), + ), + ] + case "scalar": + return [ + doc.fields([ + [ + "Value", + Option.match(Arr.head(output.series), { onNone: () => "-", onSome: lastValue }), + ], + ]), + ] + case "string": + return [doc.fields([["Value", output.stringValue]])] + } +} + +/** Rerun with the series summed per service; only for expressions that yield instant vectors. */ +const aggregateNext = (output: Output): NextCall | undefined => + output.resultType === "vector" || (output.resultType === "matrix" && !output.instant) + ? doc.next( + "query_promql", + { + query: `sum by (job) (${output.query})`, + start_time: output.timeRange.start, + end_time: output.timeRange.end, + ...(output.instant ? { instant: true } : { step: stepText(output.stepSeconds) }), + }, + "fewer series: one per service", + ) + : undefined + +/** A step the tool's own `step` parameter accepts: whole seconds, or ms below a second. */ +const stepText = (seconds: number): string => + Number.isInteger(seconds) ? `${seconds}s` : `${Math.round(seconds * 1000)}ms` + +export const renderPromqlOutput = (output: Output): ToolDoc => { + const empty = output.resultType !== "string" && output.series.length === 0 + const clipped = Arr.some(output.series, (s) => s.totalPoints > s.points.length) + const aggregate = aggregateNext(output) + return { + title: "PromQL Result", + scope: [ + ["Query", output.query], + ["Type", output.resultType], + output.instant + ? ["At", output.timeRange.end] + : ["Window", `${output.timeRange.start} to ${output.timeRange.end}`], + ["Step", output.instant ? undefined : stepText(output.stepSeconds)], + ], + blocks: bodyOf(output), + ...(empty + ? { + empty: { + message: "No series matched this query in the window.", + hints: [ + "Names are Prometheus-style: `http.server.request.duration` (s) is `http_server_request_duration_seconds_bucket`/`_count`/`_sum`, a monotonic sum ends in `_total`.", + // An instant query reads only the 5 minutes before end_time; start_time cannot help it. + output.instant + ? "Labels use underscores (`host_name`); `job` is the service name. An instant query reads the 5 minutes before end_time: move end_time, or check names with list_metrics." + : "Labels use underscores (`host_name`); `job` is the service name. Widen start_time, or check names with list_metrics.", + ], + }, + } + : undefined), + ...(output.totalSeries > output.series.length + ? { + truncation: { + shown: output.series.length, + total: output.totalSeries, + noun: "series (highest peaks kept)", + }, + } + : undefined), + ...(clipped + ? { + notices: [ + `Each series shows its last ${MAX_POINTS} points; a coarser step covers the whole window.`, + ], + } + : undefined), + next: empty + ? [ + doc.next( + "list_metrics", + { start_time: output.timeRange.start, end_time: output.timeRange.end }, + "find the metric's OTel name", + ), + ] + : output.totalSeries > output.series.length && aggregate !== undefined + ? [aggregate] + : [], + } +} 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..fc34241b1e --- /dev/null +++ b/apps/ai/src/mcp/lib/promql-result.ts @@ -0,0 +1,151 @@ +// Turns a PromQL evaluation into query_promql's output: steps, capped series, encoded values. +import { Array as Arr, Option, Order, String as Str, type Context, type Effect } from "effect" +import type { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" +import type { PromqlSampleValue, PromqlSeries, QueryPromqlOutput } from "@maple/domain/mcp-outputs" + +export type PromqlResult = Effect.Success< + ReturnType["query"]> +> + +export const MAX_SERIES = 20 +export const MAX_POINTS = 200 + +const unitSeconds = (unit: string | undefined): number => { + switch (unit) { + case "ms": + return 0.001 + case "m": + return 60 + case "h": + return 3600 + case "d": + return 86_400 + case "w": + return 604_800 + case "y": + return 31_536_000 + default: + return 1 + } +} + +const DURATION = /^(?:\d+(?:ms|s|m|h|d|w|y))+$/ +const DURATION_PART = /(\d+)(ms|s|m|h|d|w|y)/g + +/** A Prometheus duration (`1m`, `1h30m`) or float seconds, in seconds; undefined when neither. */ +export const parseStepSeconds = (raw: string): number | undefined => { + const text = Str.trim(raw) + if (DURATION.test(text)) { + const seconds = Arr.reduce(Arr.fromIterable(Str.matchAll(DURATION_PART)(text)), 0, (total, part) => { + return total + Number(part[1]) * unitSeconds(part[2]) + }) + return seconds > 0 ? seconds : undefined + } + const seconds = Number(text) + return text !== "" && Number.isFinite(seconds) && seconds > 0 ? seconds : undefined +} + +const NICE_STEPS = [15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 10_800, 21_600, 43_200, 86_400] + +/** The smallest round step that keeps a range at no more than 120 points. */ +export const defaultStepSeconds = (rangeSeconds: number): number => + Option.getOrElse( + Arr.findFirst(NICE_STEPS, (step) => rangeSeconds / step <= 120), + () => Math.ceil(rangeSeconds / 120), + ) + +/** Prometheus' spelling of a non-finite sample, so the output survives JSON. */ +export const encodeSample = (value: number): typeof PromqlSampleValue.Type => + Number.isFinite(value) ? value : Number.isNaN(value) ? "NaN" : value > 0 ? "+Inf" : "-Inf" + +interface RawSeries { + readonly labels: Readonly> + 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) => + // NaN never ranks; +Inf (a division by zero) ranks highest, as the peak it is. + !Number.isNaN(p.v) && p.v > max ? p.v : max, + ) + +// Peaks are computed once per series, not once per comparison. +const byPeakDescending = Order.mapInput( + Order.flip(Order.Number), + ([max]: readonly [number, RawSeries]) => max, +) + +/** Over {@link MAX_SERIES}, the series with the highest peaks; each keeps its last {@link MAX_POINTS} points. */ +export const capSeries = (result: PromqlResult): ReadonlyArray => { + const all = rawSeries(result) + const kept = + all.length > MAX_SERIES + ? Arr.map( + Arr.take( + Arr.sort( + Arr.map(all, (series) => [peak(series), series] as const), + byPeakDescending, + ), + MAX_SERIES, + ), + ([, series]) => series, + ) + : all + return Arr.map(kept, (series) => { + const stats = seriesStats(series) + return { + labels: series.labels, + points: Arr.map(Arr.takeRight(series.points, MAX_POINTS), (p) => ({ + t: p.t, + v: encodeSample(p.v), + })), + totalPoints: series.points.length, + ...(stats === undefined ? undefined : { stats }), + } + }) +} + +/** Min, average and max over every point before the cap; infinities count, NaN does not. */ +const seriesStats = (series: RawSeries) => { + const values = Arr.filter( + Arr.map(series.points, (p) => p.v), + (v) => !Number.isNaN(v), + ) + if (values.length === 0) return undefined + const sum = Arr.reduce(values, 0, (a, b) => a + b) + return { + min: encodeSample(Arr.reduce(values, Infinity, (a, b) => Math.min(a, b))), + avg: encodeSample(sum / values.length), + max: encodeSample(Arr.reduce(values, -Infinity, (a, b) => Math.max(a, b))), + } +} + +export const toOutput = (input: { + readonly query: string + readonly instant: boolean + readonly timeRange: { readonly start: string; readonly end: string } + readonly stepSeconds: number + readonly result: PromqlResult +}): typeof QueryPromqlOutput.Type => ({ + query: input.query, + resultType: input.result.resultType, + instant: input.instant, + timeRange: input.timeRange, + stepSeconds: input.stepSeconds, + series: capSeries(input.result), + totalSeries: rawSeries(input.result).length, + ...(input.result.resultType === "string" ? { stringValue: input.result.result.v } : undefined), +}) diff --git a/apps/ai/src/mcp/tool-descriptors.generated.ts b/apps/ai/src/mcp/tool-descriptors.generated.ts index d0e090c2c9..e67eed36ed 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"]}]},"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/tool-modules.generated.ts b/apps/ai/src/mcp/tool-modules.generated.ts index c44b2fae7b..e0efb489d9 100644 --- a/apps/ai/src/mcp/tool-modules.generated.ts +++ b/apps/ai/src/mcp/tool-modules.generated.ts @@ -27,6 +27,7 @@ export const MCP_TOOL_MODULES: ReadonlyArray = [ { name: "error_detail", tool: "error_detail", title: "Error Detail", audience: "public", load: () => import("./tools/error-detail").then((module) => module.registerErrorDetailTool) }, { name: "list_metrics", tool: "list_metrics", title: "List Metrics", audience: "public", load: () => import("./tools/list-metrics").then((module) => module.registerListMetricsTool) }, { name: "query_data", tool: "query_data", title: "Query Data", audience: "public", load: () => import("./tools/query-data").then((module) => module.registerQueryDataTool) }, + { name: "query_promql", tool: "query_promql", title: "Query PromQL", audience: "public", load: () => import("./tools/query-promql").then((module) => module.registerQueryPromqlTool) }, { name: "run_sql", tool: "run_sql", title: "Run SQL", audience: "public", load: () => import("./tools/run-sql").then((module) => module.registerRunSqlTool) }, { name: "service_map", tool: "service_map", title: "Service Map", audience: "public", load: () => import("./tools/service-map").then((module) => module.registerServiceMapTool) }, { name: "list_alert_rules", tool: "list_alert_rules", title: "List Alert Rules", audience: "public", load: () => import("./tools/list-alert-rules").then((module) => module.registerListAlertRulesTool) }, 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..b32f7f84bb --- /dev/null +++ b/apps/ai/src/mcp/tools/query-promql.test.ts @@ -0,0 +1,360 @@ +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 { 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" +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:00 1, 11-15 10:59:30 NaN, 11-15 11:00: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("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("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 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", ...window, step: "99ms" }, () => 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) => + 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", + }, + ]) + }), + ) + + 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", () => { + 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("0s")).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) + }) + + 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) + }) +}) + +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") + }), + ) + + 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", () => { + 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") + }), + ) +}) + +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" }, () => + Effect.succeed({ + resultType: "matrix" as const, + result: [series("svc", [1, Number.POSITIVE_INFINITY])], + }), + ) + expect(text).toContain("| +Inf |") + expect(text).toContain("11-15 10:59:30 1, 11-15 11:00:00 +Inf") + }), + ) +}) 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..7db46e1b3c --- /dev/null +++ b/apps/ai/src/mcp/tools/query-promql.ts @@ -0,0 +1,102 @@ +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 { MAX_STEPS, 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)) + // 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} steps 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, + "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 ea791332ea..9acd650620 100644 --- a/apps/ai/src/mcp/tools/registry.ts +++ b/apps/ai/src/mcp/tools/registry.ts @@ -100,6 +100,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" @@ -166,6 +167,7 @@ const MAPLE_TOOL_REGISTERS: ReadonlyArray = [ registerErrorDetailTool, registerListMetricsTool, registerQueryDataTool, + registerQueryPromqlTool, registerRunSqlTool, registerServiceMapTool, registerListAlertRulesTool, 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/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) => { 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..fdca568f9e --- /dev/null +++ b/packages/domain/src/mcp-outputs/promql.ts @@ -0,0 +1,35 @@ +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, + /** 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({ + 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), +})