Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
c5663a1
feat(promql): a Prometheus-compatible query API for Grafana
Makisuo Nov 15, 2026
d401c99
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
4cbec4d
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
0fdedfa
fix(promql): range mode for query_range, query limits, and label limi…
Makisuo Nov 15, 2026
160d43d
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
eef4c4e
test(promql): selector rows name their metric with its unit
Makisuo Nov 15, 2026
edcdd9f
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
ffa8f2d
refactor(promql): floor rollup reads with utcHourFloor
Makisuo Nov 15, 2026
96bc99e
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
b15a292
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
b7e6608
fix(promql): cap match[] selectors in discovery calls
Makisuo Nov 15, 2026
f07a9c5
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
37c79eb
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
32dbb9b
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
33f18ff
test(promql): match[] on a GET's query string, one value and many
Makisuo Nov 15, 2026
b3b569e
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
534746e
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
a61bd55
fix(promql): label discovery lists instance and resource labels
Makisuo Nov 15, 2026
d741242
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
320e03c
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
f28129e
fix(api): redact PromQL query and match[] values in traced URLs
Makisuo Nov 15, 2026
89b9f9c
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
1310765
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
f074396
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
40416c1
fix(api): Prometheus timestamps past Date's range are a 400
Makisuo Nov 15, 2026
13008e8
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
2b131e4
fix(promql): label values from match[] read own labels only
Makisuo Nov 15, 2026
f9f786c
fix(promql): instance label values read the metric tables
Makisuo Nov 15, 2026
a87911e
fix(api): the default discovery start stays inside Date's range
Makisuo Nov 15, 2026
ee8cf98
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
55bb260
test(promql): the service tests refuse reads that are not single-tena…
Makisuo Nov 15, 2026
dad0f46
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
6eb9398
fix(promql): metadata keeps a metric's two units as two families
Makisuo Nov 15, 2026
28904d8
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
5cb9bfe
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
4e5c642
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 15, 2026
1dcf9e2
fix(promql): job label values carry the service namespace
Makisuo Nov 15, 2026
62d0f20
fix(promql): discovery matches series labels exactly
Makisuo Nov 15, 2026
da29622
fix(api): RFC3339 month lengths are computed, so year 0000 keeps its …
Makisuo Nov 15, 2026
9760205
test(api): GET /metadata answers family-keyed metadata the way Grafan…
Makisuo Nov 15, 2026
97585ae
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
c8ac70a
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
c037c44
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
d96c479
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
77a29d7
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
f4cc0ea
Merge branch 'promql/4-mcp' into promql/5-prometheus-api
Makisuo Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apps/api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
"@maple/domain": "workspace:*",
"@maple/infra": "workspace:*",
"@maple/primitives": "workspace:*",
"@maple/promql": "workspace:*",
"@maple/query-engine": "workspace:*",
"@maple/query-engine-integrations": "workspace:*",
"@maple/widgets": "workspace:*",
Expand Down
14 changes: 14 additions & 0 deletions apps/api/src/http/api-observability.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,20 @@ describe("ApiObservabilityLive", () => {
expect(recorded).not.toContain("abc")
})

it("keeps PromQL text out of the URL a server span records", () => {
const recorded = Effect.gen(function* () {
const names = yield* UrlParams.CurrentRedactedNames
return UrlParams.redactUrl(
"https://api.maple.dev/api/v2/prometheus/api/v1/series?match%5B%5D=up%7Buser%3D%22ada%22%7D&query=rate(x%7Bcustomer%3D%22acme%22%7D%5B5m%5D)&step=60",
names,
)
}).pipe(Effect.provide(ApiObservabilityLive), Effect.runSync)

expect(recorded).not.toContain("ada")
expect(recorded).not.toContain("acme")
expect(recorded).toContain("step=60")
})

it("still traces ordinary API routes", () => {
expect(tracedFor("/api/v2/uptime_monitors")).toBe(true)
expect(tracedFor("/hbx")).toBe(true)
Expand Down
3 changes: 3 additions & 0 deletions apps/api/src/http/api-observability.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,11 @@ export const ApiObservabilityLive = Layer.mergeAll(
// Query values the tracer writes as `<redacted>` in `url.full` and `url.query`. A custom
// list replaces Effect's, so its defaults are kept. `actor` is an audit filter: an admin
// types a member's email into it, and a span is read by more people than the audit log is.
// `query` and `match[]` are PromQL text, whose matcher values can name a user or customer.
Layer.succeed(UrlParams.CurrentRedactedNames, [
...UrlParams.CurrentRedactedNames.defaultValue(),
"actor",
"query",
"match[]",
]),
)
47 changes: 47 additions & 0 deletions apps/api/src/routes/v2/prometheus-wire.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
import { describe, expect, it } from "@effect/vitest"
import { Effect, String as Str } from "effect"
import { formatValue, parseStep, parseTime } from "./prometheus-wire"

describe("Prometheus wire format", () => {
it("formats floats as Go's FormatFloat(v, 'f', -1, 64)", () => {
expect(formatValue(1)).toBe("1")
expect(formatValue(-0)).toBe("-0")
expect(formatValue(1.5e-7)).toBe("0.00000015")
expect(formatValue(-2.5e22)).toBe("-25000000000000000000000")
expect(formatValue(1.7976931348623157e308)).toMatch(/^179769313486231570+$/)
expect(formatValue(5e-324)).toBe(`0.${Str.repeat(323)("0")}5`)
})

it.effect("parses Prometheus timestamps and steps to epoch ms", () =>
Effect.gen(function* () {
expect(yield* parseTime("time", "1752580800.123")).toBe(1752580800123)
expect(yield* parseTime("time", "2026-07-15T12:00:00.25+02:00")).toBe(
Date.UTC(2026, 6, 15, 10, 0, 0, 250),
)
expect(yield* parseStep("1m30s")).toBe(90_000)
expect(yield* parseStep("0.25")).toBe(250)
const invalid = yield* Effect.flip(parseTime("start", "2026-07-15"))
expect(invalid.message).toBe(
'invalid parameter "start": cannot parse "2026-07-15" to a valid timestamp',
)
// Past what a Date renders (nanoseconds sent as seconds): a 400, not a 500 downstream.
const huge = yield* Effect.flip(parseTime("time", "1752580800123456789"))
expect(huge.message).toMatch(/cannot parse/)
// A clock or calendar field Date would roll over is refused, as Go's time.Parse refuses it.
for (const text of [
"2026-07-15T24:00:00Z",
"2026-02-30T00:00:00Z",
"2026-07-15T12:60:00Z",
"2026-13-01T00:00:00Z",
]) {
expect((yield* Effect.flip(parseTime("time", text))).message).toMatch(/cannot parse/)
}
expect(yield* parseTime("time", "2028-02-29T23:59:59Z")).toBe(Date.UTC(2028, 1, 29, 23, 59, 59))
// Year 0000 is a leap year; Date.UTC would read it as 1900.
expect(Number.isFinite(yield* parseTime("time", "0000-02-29T00:00:00Z"))).toBe(true)
expect((yield* Effect.flip(parseTime("time", "1900-02-29T00:00:00Z"))).message).toMatch(
/cannot parse/,
)
}),
)
})
172 changes: 172 additions & 0 deletions apps/api/src/routes/v2/prometheus-wire.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
// Prometheus' HTTP API wire format: request parameter parsing and the exact JSON bodies
// (`[<unix seconds>, "<value>"]` samples, Go float formatting, the error envelope).

import { DateTime, Effect, Option, Array as Arr, String as Str } from "effect"
import { parseDurationMs, type QueryResult } from "@maple/promql"
import { PromqlBadQueryError } from "@maple/backend/services/promql/PromqlQueryService"

const FLOAT = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/
const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/

/**
* Whether an RFC3339 match names a real calendar date and clock time, as Go's `time.Parse`
* checks. JavaScript's Date would roll `24:00` or February 30 into another instant.
*/
const isRealTime = (match: RegExpExecArray): boolean => {
const [
,
year = 0,
month = 0,
day = 0,
hour = 0,
minute = 0,
second = 0,
,
offsetHour = 0,
offsetMinute = 0,
] = Arr.map(match, (part) => (part === undefined ? undefined : Number(part)))
// Arithmetic, not Date.UTC, which reads years 0 to 99 as 1900 to 1999.
const isLeap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
const daysInMonth = month === 2 ? (isLeap ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31
return (
month >= 1 &&
month <= 12 &&
day >= 1 &&
day <= daysInMonth &&
hour < 24 &&
minute < 60 &&
second < 60 &&
offsetHour < 24 &&
offsetMinute < 60
)
}

/** The largest epoch ms a JavaScript Date renders. */
export const MAX_DATE_MS = 8.64e15

/** A Prometheus timestamp: Unix seconds with an optional fraction, or RFC3339. Epoch ms. */
export const parseTime = (name: string, text: string): Effect.Effect<number, PromqlBadQueryError> => {
if (FLOAT.test(text)) {
const ms = Math.round(Number(text) * 1000)
if (Math.abs(ms) <= MAX_DATE_MS) return Effect.succeed(ms)
} else {
const match = RFC3339.exec(text)
const parsed = match !== null && isRealTime(match) ? DateTime.make(text) : Option.none()
if (Option.isSome(parsed)) return Effect.succeed(DateTime.toEpochMillis(parsed.value))
}
return Effect.fail(
new PromqlBadQueryError({
message: `invalid parameter "${name}": cannot parse "${text}" to a valid timestamp`,
}),
)
}

/** A Prometheus duration (`30s`, `1m30s`) or float seconds. Epoch ms. */
export const parseStep = (text: string): Effect.Effect<number, PromqlBadQueryError> => {
const ms = FLOAT.test(text) ? Math.round(Number(text) * 1000) : parseDurationMs(text)
return ms !== undefined && Number.isFinite(ms)
? Effect.succeed(ms)
: Effect.fail(
new PromqlBadQueryError({
message: `invalid parameter "step": cannot parse "${text}" to a valid duration`,
}),
)
}

/** Moves the decimal point of `digits` (a plain decimal, no sign) by `exponent` places. */
const shiftPoint = (digits: string, exponent: number): string => {
const [whole, fraction = ""] = Str.split(digits, ".")
const all = whole + fraction
const point = whole.length + exponent
if (point <= 0) return `0.${Str.repeat(-point)("0")}${all}`
if (point >= all.length) return all + Str.repeat(point - all.length)("0")
return `${Str.slice(0, point)(all)}.${Str.slice(point)(all)}`
}

/** Go `strconv.FormatFloat(v, 'f', -1, 64)`: shortest round-trip digits, never an exponent. */
export const formatValue = (value: number): string => {
if (Number.isNaN(value)) return "NaN"
if (value === Infinity) return "+Inf"
if (value === -Infinity) return "-Inf"
if (Object.is(value, -0)) return "-0"
const text = String(value)
const [mantissa, exponent] = Str.split(text, "e")
if (exponent === undefined) return text
const negative = Str.startsWith("-")(mantissa)
const shifted = shiftPoint(negative ? Str.slice(1)(mantissa) : mantissa, Number(exponent))
return negative ? `-${shifted}` : shifted
}

type WirePoint = readonly [number, string]

const point = (t: number, v: number): WirePoint => [t / 1000, formatValue(v)]

/** The `data` of a query response. */
export const encodeQueryResult = (result: QueryResult) => {
switch (result.resultType) {
case "matrix":
return {
resultType: result.resultType,
result: Arr.map(result.result, (series) => ({
metric: series.labels,
values: Arr.map(series.points, (p) => point(p.t, p.v)),
})),
}
case "vector":
return {
resultType: result.resultType,
result: Arr.map(result.result, (sample) => ({
metric: sample.labels,
value: point(sample.t, sample.value),
})),
}
case "scalar":
return { resultType: result.resultType, result: point(result.result.t, result.result.v) }
case "string":
return { resultType: result.resultType, result: [result.result.t / 1000, result.result.v] }
}
}

export type PrometheusErrorType = "bad_data" | "execution" | "timeout" | "unavailable"

const ERROR_STATUS = {
bad_data: 400,
execution: 422,
timeout: 503,
unavailable: 503,
} satisfies Record<PrometheusErrorType, number>

export const errorStatus = (type: PrometheusErrorType): number => ERROR_STATUS[type]

export const errorBody = (type: PrometheusErrorType, error: string) => ({
status: "error" as const,
errorType: type,
error,
})

export const successBody = <A>(data: A, warnings: ReadonlyArray<string> = []) =>
warnings.length === 0
? { status: "success" as const, data }
: { status: "success" as const, data, warnings }

/** Prometheus' `limit` on a query: at most that many series, with a warning when some were cut. */
export const limitQueryResult = (
result: QueryResult,
limit: number | undefined,
): { readonly result: QueryResult; readonly warnings: ReadonlyArray<string> } => {
if (limit === undefined) return { result, warnings: [] }
const cut = [`results truncated due to limit`]
switch (result.resultType) {
case "matrix":
return result.result.length > limit
? { result: { ...result, result: Arr.take(result.result, limit) }, warnings: cut }
: { result, warnings: [] }
case "vector":
return result.result.length > limit
? { result: { ...result, result: Arr.take(result.result, limit) }, warnings: cut }
: { result, warnings: [] }
case "scalar":
case "string":
return { result, warnings: [] }
}
}
Loading
Loading