From 94216cbd233960ea2a07e40f574499f56f11c4cd Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 15:12:05 +0100 Subject: [PATCH 1/7] feat(promql): run PromQL on the metric tables The Maple source behind @maple/promql. A selector's metric name resolves through metric_catalog to stored metrics the way Prometheus' OTLP translation names them (`http.server.request.duration` answers to `http_server_request_duration_seconds_bucket`, a monotonic sum to `..._total`, scraped names match as stored), and each (table, component) it resolves to becomes one warehouse query. That query pushes the label matchers into WHERE, rebuilds counters (delta sums become running sums, explicit histograms expand into cumulative `le` series) and returns one row per series with every bucket's statistics, so the evaluator recombines whole buckets instead of reading raw samples. Series labels follow the OTLP mapping: datapoint attributes, promoted resource attributes, and job/instance from service.name and service.instance.id. PromqlQueryService runs a query: validate, plan, one catalog read, the selector queries concurrently, evaluate. apps/cli/test/promql-engine stores the compliance dataset in chDB the way Maple stores it and every corpus query must equal the in-memory reference, which matches Prometheus 3.5. --- .github/workflows/ci.yml | 2 +- apps/cli/package.json | 1 + apps/cli/test/promql-engine.test.ts | 230 ++++++++ apps/cli/test/promql-source.test.ts | 530 ++++++++++++++++++ bun.lock | 3 + lib/promql/package.json | 3 +- lib/promql/scripts/compliance/index.ts | 2 + packages/backend/package.json | 1 + .../promql/PromqlQueryService.test.ts | 71 +++ .../src/services/promql/PromqlQueryService.ts | 182 ++++++ packages/query-engine/package.json | 4 +- packages/query-engine/src/ch/index.ts | 1 + .../query-engine/src/ch/queries/promql.ts | 364 ++++++++++++ packages/query-engine/src/promql/index.ts | 9 + .../query-engine/src/promql/labels.test.ts | 91 +++ packages/query-engine/src/promql/labels.ts | 169 ++++++ .../query-engine/src/promql/names.test.ts | 131 +++++ packages/query-engine/src/promql/names.ts | 210 +++++++ packages/query-engine/src/promql/source.ts | 199 +++++++ 19 files changed, 2200 insertions(+), 3 deletions(-) create mode 100644 apps/cli/test/promql-engine.test.ts create mode 100644 apps/cli/test/promql-source.test.ts create mode 100644 lib/promql/scripts/compliance/index.ts create mode 100644 packages/backend/src/services/promql/PromqlQueryService.test.ts create mode 100644 packages/backend/src/services/promql/PromqlQueryService.ts create mode 100644 packages/query-engine/src/ch/queries/promql.ts create mode 100644 packages/query-engine/src/promql/index.ts create mode 100644 packages/query-engine/src/promql/labels.test.ts create mode 100644 packages/query-engine/src/promql/labels.ts create mode 100644 packages/query-engine/src/promql/names.test.ts create mode 100644 packages/query-engine/src/promql/names.ts create mode 100644 packages/query-engine/src/promql/source.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23335ce945..208563ea43 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -542,7 +542,7 @@ jobs: MAPLE_REQUIRE_LIBCHDB: "1" MAPLE_TELEMETRY: off run: | - for file in tenant-isolation scoped-delete local-service-map-rollup checkpoint-merge-freeze local-store-traces-rekey local-query-guard local-query-guard.fuzz funnel-scenarios users-identity histogram-metrics; do + for file in tenant-isolation scoped-delete local-service-map-rollup checkpoint-merge-freeze local-store-traces-rekey local-query-guard local-query-guard.fuzz funnel-scenarios users-identity histogram-metrics promql-source promql-engine; do bun test --timeout 30000 "test/$file.test.ts" done diff --git a/apps/cli/package.json b/apps/cli/package.json index 7845a1c131..4f76cc7aee 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -24,6 +24,7 @@ }, "devDependencies": { "@effect/vitest": "catalog:effect", + "@maple/promql": "workspace:*", "@types/bun": "^1.4.4", "@types/node": "catalog:tooling", "fast-check": "^4.10.2", diff --git a/apps/cli/test/promql-engine.test.ts b/apps/cli/test/promql-engine.test.ts new file mode 100644 index 0000000000..5066c0fb24 --- /dev/null +++ b/apps/cli/test/promql-engine.test.ts @@ -0,0 +1,230 @@ +// The whole PromQL path on a real ClickHouse engine (chDB): the compliance dataset is stored the +// way Maple stores it (counters in metrics_sum, gauges in metrics_gauge, the classic histogram as +// one metrics_histogram metric), every corpus query runs through the warehouse source and the +// evaluator, and the answer must equal the in-memory reference, which matches Prometheus 3.5 +// (lib/promql/scripts/compliance). + +import { afterAll, beforeAll, expect, test } from "bun:test" +import { mkdtempSync, rmSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { Array as Arr, Effect, Record as Rec, Result, String as Str } from "effect" +import schemaSql from "@maple/local-server/schema/local-schema.sql" with { type: "text" } +import { Chdb } from "@maple/local-server/chdb" +import { decodeJsonEachRow } from "@maple/local-server/chdb-rows" +import { normalizeSqlForClickHouseClient } from "@maple/query-engine/execution" +import * as CH from "@maple/query-engine/ch" +import { + buildSelectorQueries, + catalogFromRows, + catalogQuery, + promqlCatalogRowSchema, + promqlSelectorRowSchema, + toSelectorData, + type CatalogMetric, +} from "@maple/query-engine/promql" +import { + evaluate, + memorySource, + parse, + planRequests, + type QueryParams, + type QueryResult, + type RawSeries, + runQuery, + type SelectorData, + type VectorSelector, +} from "@maple/promql" +import { buildDataset, DATA_END_MS, DATA_START_MS, QUERIES } from "@maple/promql/compliance" +import { OrgId } from "@maple/domain" +import { describeWithChdb } from "./libchdb-test-support" + +const ORG = "org_promql_engine" +const HOUR_MS = 3_600_000 +/** The dataset moved to end on the hour two hours ago, inside every table's TTL. */ +const SHIFT_MS = Math.floor(Date.now() / HOUR_MS) * HOUR_MS - 2 * HOUR_MS - DATA_END_MS +const START = DATA_START_MS + SHIFT_MS +const END = DATA_END_MS + SHIFT_MS + +/** Prometheus 3 spells bucket bounds as floats; the source does too. */ +const leOf = (le: string): string => (le === "1" ? "1.0" : le) + +const dataset: ReadonlyArray = Arr.map(buildDataset(), (s) => ({ + labels: s.labels.le === undefined ? s.labels : { ...s.labels, le: leOf(s.labels.le) }, + samples: Arr.map(s.samples, ([t, v]): readonly [number, number] => [t + SHIFT_MS, v]), +})) + +const chTime = (ms: number): string => Str.replace("T", " ")(Str.slice(0, 23)(new Date(ms).toISOString())) + +const quote = (value: string): string => + `'${Str.replaceAll("'", "\\'")(Str.replaceAll("\\", "\\\\")(value))}'` + +const mapLiteral = (attributes: Readonly>): string => + `map(${Arr.join( + Arr.flatMap(Rec.toEntries(attributes), ([key, value]) => [quote(key), quote(value)]), + ", ", + )})` + +const attributesOf = (labels: Readonly>): Readonly> => + Rec.filter(labels, (_v, k) => k !== "__name__" && k !== "le") + +const rowPrefix = (name: string, labels: Readonly>): string => { + const job = labels.job ?? "unknown" + return `${quote(ORG)}, ${mapLiteral({ "service.name": job })}, ${quote(job)}, ${quote(name)}, ${mapLiteral(attributesOf(labels))}, ${quote(chTime(START - HOUR_MS))}` +} + +const insertNumbers = (db: Chdb, series: RawSeries, table: "metrics_sum" | "metrics_gauge"): void => { + const name = series.labels.__name__ ?? "" + const extra = table === "metrics_sum" ? ", 2, true" : "" + const rows = Arr.map( + series.samples, + ([t, v]) => `(${rowPrefix(name, series.labels)}, ${quote(chTime(t))}, ${v}${extra})`, + ) + db.exec( + `INSERT INTO ${table} (OrgId, ResourceAttributes, ServiceName, MetricName, Attributes, StartTimeUnix, TimeUnix, Value${ + table === "metrics_sum" ? ", AggregationTemporality, IsMonotonic" : "" + }) VALUES ${Arr.join(rows, ", ")}`, + ) +} + +const BOUNDS = ["0.1", "0.5", "1.0"] + +/** The `_bucket`/`_count`/`_sum` series of one service folded back into OTel histogram exports. */ +const insertHistogram = (db: Chdb, service: string): void => { + const of = (name: string, le?: string) => + Arr.findFirst( + dataset, + (s) => s.labels.__name__ === name && s.labels.service === service && s.labels.le === le, + ) + const buckets = Arr.map([...BOUNDS, "+Inf"], (le) => of("http_request_duration_seconds_bucket", le)) + const sums = of("http_request_duration_seconds_sum") + const labels = { job: "web", service } + const rows = Arr.map(sums._tag === "Some" ? sums.value.samples : [], ([t, sum], i) => { + const cumulative = Arr.map(buckets, (b) => (b._tag === "Some" ? (b.value.samples[i]?.[1] ?? 0) : 0)) + const counts = Arr.map(cumulative, (c, j) => c - (j === 0 ? 0 : (cumulative[j - 1] ?? 0))) + return `(${rowPrefix("http_request_duration_seconds", labels)}, ${quote(chTime(t))}, ${cumulative[3] ?? 0}, ${sum}, [${Arr.join(Arr.map(counts, String), ", ")}], [${Arr.join(BOUNDS, ", ")}], 2)` + }) + db.exec( + `INSERT INTO metrics_histogram (OrgId, ResourceAttributes, ServiceName, MetricName, Attributes, StartTimeUnix, TimeUnix, Count, Sum, BucketCounts, ExplicitBounds, AggregationTemporality) VALUES ${Arr.join(rows, ", ")}`, + ) +} + +const decodeRows = decodeJsonEachRow(promqlSelectorRowSchema) +const decodeCatalog = decodeJsonEachRow(promqlCatalogRowSchema) + +const sqlRun = (db: Chdb, catalog: ReadonlyArray, query: string, params: QueryParams) => { + const parsed = parse(query) + if (Result.isFailure(parsed)) return Result.fail(parsed.failure.message) + const data = new Map() + for (const [selector, request] of planRequests(parsed.success, params)) { + const results = Arr.map( + buildSelectorQueries(request, catalog, { orgId: OrgId.make(ORG), maxSeries: 10_000 }), + (plan) => ({ + plan, + rows: decodeRows( + db.query(normalizeSqlForClickHouseClient(Effect.runSync(plan.compiled).sql)), + ), + }), + ) + data.set(selector, toSelectorData(request, results)) + } + return Result.mapError(evaluate({ expr: parsed.success, params, data }), (e) => e.message) +} + +const flatten = (result: QueryResult): ReadonlyArray => { + const key = (labels: Readonly>) => JSON.stringify(Rec.toEntries(labels).sort()) + switch (result.resultType) { + case "scalar": + return [["", result.result.t, result.result.v]] + case "string": + return [] + case "vector": + return Arr.map(result.result, (s) => [key(s.labels), s.t, s.value] as const) + case "matrix": + return Arr.flatMap(result.result, (s) => + Arr.map(s.points, (p) => [key(s.labels), p.t, p.v] as const), + ) + } +} + +/** The first point where the SQL path disagrees with the reference, or undefined. */ +const mismatch = (got: QueryResult, want: QueryResult): string | undefined => { + const sort = (rows: ReadonlyArray) => + [...rows].sort((a, b) => (a[0] === b[0] ? a[1] - b[1] : a[0] < b[0] ? -1 : 1)) + const a = sort(flatten(got)) + const b = sort(flatten(want)) + if (a.length !== b.length) return `${a.length} points, want ${b.length}` + for (const [i, [k, t, v]] of a.entries()) { + const other = b[i] + if (other === undefined || other[0] !== k || other[1] !== t) + return `point ${i}: ${k}@${t}, want ${other?.[0]}@${other?.[1]}` + const w = other[2] + const same = + (Number.isNaN(v) && Number.isNaN(w)) || + v === w || + Math.abs(v - w) <= 1e-9 * Math.max(1, Math.abs(v), Math.abs(w)) + if (!same) return `${k}@${t}: ${v}, want ${w}` + } + return undefined +} + +describeWithChdb("PromQL on the warehouse matches the reference", () => { + let root = "" + let db: Chdb + let catalog: ReadonlyArray = [] + const reference = memorySource(dataset) + + beforeAll(() => { + root = mkdtempSync(join(tmpdir(), "maple-promql-engine-")) + db = Chdb.open({ dataDir: join(root, "data"), schemaSql }) + for (const series of dataset) { + const name = series.labels.__name__ ?? "" + if (name === "http_requests_total") insertNumbers(db, series, "metrics_sum") + else if (Str.startsWith("node_")(name) || Str.startsWith("room_")(name)) + insertNumbers(db, series, "metrics_gauge") + } + insertHistogram(db, "checkout") + insertHistogram(db, "search") + const compiled = CH.compileUnsafe(catalogQuery(), { + orgId: OrgId.make(ORG), + startTime: Str.slice(0, 19)(chTime(START - HOUR_MS)), + endTime: Str.slice(0, 19)(chTime(END + HOUR_MS)), + }) + catalog = catalogFromRows(decodeCatalog(db.query(normalizeSqlForClickHouseClient(compiled.sql)))) + }) + + afterAll(() => { + db.close() + rmSync(root, { recursive: true, force: true }) + }) + + const cases: ReadonlyArray<{ readonly name: string; readonly params: QueryParams }> = [ + { name: "range 60s", params: { startMs: START + 1_800_000, endMs: END - 600_000, stepMs: 60_000 } }, + { + name: "range 37s", + params: { startMs: START + 1_800_000, endMs: START + 5_400_000, stepMs: 37_000 }, + }, + { name: "instant", params: { startMs: START + 3_600_000, endMs: START + 3_600_000, stepMs: 0 } }, + { + name: "instant off-grid", + params: { startMs: START + 3_607_000, endMs: START + 3_607_000, stepMs: 0 }, + }, + ] + + for (const query of QUERIES) { + // `@` pins absolute times, which the shifted dataset does not keep. + if (Str.includes("@ ")(query)) continue + test(query, () => { + for (const { name, params } of cases) { + const want = runQuery(query, params, reference) + const got = sqlRun(db, catalog, query, params) + if (Result.isFailure(want)) { + expect(Result.isFailure(got)).toBe(true) + continue + } + if (Result.isFailure(got)) throw new Error(`${name}: ${got.failure}`) + expect(`${name}: ${mismatch(got.success, want.success) ?? "ok"}`).toBe(`${name}: ok`) + } + }) + } +}) diff --git a/apps/cli/test/promql-source.test.ts b/apps/cli/test/promql-source.test.ts new file mode 100644 index 0000000000..47beafad72 --- /dev/null +++ b/apps/cli/test/promql-source.test.ts @@ -0,0 +1,530 @@ +// The PromQL selector source against a real ClickHouse engine (chDB). +// +// Each stored series is also kept as plain (time, value) samples, the way Prometheus would read +// it: delta sums accumulated, histogram buckets cumulative per bound. A small reference buckets +// those samples, and the query has to return the same bucket statistics, in bucketed and raw mode. + +import { afterAll, beforeAll, expect, test } from "bun:test" +import { mkdtempSync, rmSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { Array as Arr, Effect, Order, Record as Rec, String as Str } from "effect" +import schemaSql from "@maple/local-server/schema/local-schema.sql" with { type: "text" } +import { Chdb } from "@maple/local-server/chdb" +import { decodeJsonEachRow } from "@maple/local-server/chdb-rows" +import { normalizeSqlForClickHouseClient } from "@maple/query-engine/execution" +import * as CH from "@maple/query-engine/ch" +import { + buildSelectorQueries, + catalogFromRows, + catalogQuery, + promqlCatalogRowSchema, + promqlSelectorRowSchema, + toSelectorData, + type CatalogMetric, +} from "@maple/query-engine/promql" +import type { SampleBucket, SeriesData } from "@maple/promql" +import { OrgId } from "@maple/domain" +import { describeWithChdb } from "./libchdb-test-support" + +const SECOND_MS = 1_000 +const MINUTE_MS = 60_000 +/** On the hour, six hours ago, so every row lands in one catalog hour and inside the TTL. */ +const BASE_MS = Math.floor(Date.now() / 3_600_000) * 3_600_000 - 6 * 3_600_000 + +const ORG_A = "org_promql_a" +const ORG_B = "org_promql_b" + +type Sample = readonly [atMs: number, value: number] + +/** `YYYY-MM-DD HH:MM:SS.fff` in UTC. */ +const chTime = (offsetMs: number): string => + Str.replace("T", " ")(Str.slice(0, 23)(new Date(BASE_MS + offsetMs).toISOString())) + +const quote = (value: string): string => + `'${Str.replaceAll("'", "\\'")(Str.replaceAll("\\", "\\\\")(value))}'` + +const mapLiteral = (attributes: Readonly>): string => + `map(${Arr.join( + Arr.flatMap(Rec.toEntries(attributes), ([key, value]) => [quote(key), quote(value)]), + ", ", + )})` + +const every = (fromMs: number, toMs: number, stepMs: number): ReadonlyArray => + Arr.makeBy(Math.floor((toMs - fromMs) / stepMs) + 1, (i) => fromMs + i * stepMs) + +interface SumSeries { + readonly org: string + readonly table: "metrics_sum" | "metrics_gauge" + readonly metric: string + readonly unit: string + readonly attributes: Readonly> + readonly resource: Readonly> + readonly temporality: 1 | 2 + readonly samples: ReadonlyArray +} + +const insertValues = (db: Chdb, series: SumSeries): void => { + const rows = Arr.map( + series.samples, + ([atMs, value]) => + `(${quote(series.org)}, ${mapLiteral(series.resource)}, ${quote(series.resource["service.name"] ?? "unknown")}, ${quote(series.metric)}, ${quote(series.unit)}, ${mapLiteral(series.attributes)}, ${quote(chTime(START_MS))}, ${quote(chTime(atMs))}, ${value}${series.table === "metrics_sum" ? `, ${series.temporality}, true` : ""})`, + ) + const extra = series.table === "metrics_sum" ? ", AggregationTemporality, IsMonotonic" : "" + db.exec( + `INSERT INTO ${series.table} (OrgId, ResourceAttributes, ServiceName, MetricName, MetricUnit, Attributes, StartTimeUnix, TimeUnix, Value${extra}) VALUES ${Arr.join(rows, ", ")}`, + ) +} + +/** Every sample's StartTimeUnix: when the process began counting. */ +const START_MS = -10 * MINUTE_MS + +interface HistogramSeries { + readonly org: string + readonly metric: string + readonly unit: string + readonly attributes: Readonly> + readonly resource: Readonly> + readonly bounds: ReadonlyArray + /** Per export: bucket counts (one more than the bounds) and the sum, cumulative since START_MS. */ + readonly exports: ReadonlyArray<{ + readonly atMs: number + readonly counts: ReadonlyArray + readonly sum: number + }> +} + +const insertHistogram = (db: Chdb, series: HistogramSeries): void => { + const rows = Arr.map( + series.exports, + ({ atMs, counts, sum }) => + `(${quote(series.org)}, ${mapLiteral(series.resource)}, ${quote(series.resource["service.name"] ?? "unknown")}, ${quote(series.metric)}, ${quote(series.unit)}, ${mapLiteral(series.attributes)}, ${quote(chTime(START_MS))}, ${quote(chTime(atMs))}, ${total(counts)}, ${sum}, [${Arr.join(Arr.map(counts, String), ", ")}], [${Arr.join(Arr.map(series.bounds, String), ", ")}], 2)`, + ) + db.exec( + `INSERT INTO metrics_histogram (OrgId, ResourceAttributes, ServiceName, MetricName, MetricUnit, Attributes, StartTimeUnix, TimeUnix, Count, Sum, BucketCounts, ExplicitBounds, AggregationTemporality) VALUES ${Arr.join(rows, ", ")}`, + ) +} + +const RESOURCE = { "service.name": "api", "service.instance.id": "i1", "telemetry.sdk.name": "opentelemetry" } + +// A counter that resets after its ninth export, a second route, a delta sum with gaps and a +// zero, a gauge with gaps, and a histogram; org B has the same counter with other values. +const counterA: SumSeries = { + org: ORG_A, + table: "metrics_sum", + metric: "requests", + unit: "{request}", + attributes: { route: "/a" }, + resource: RESOURCE, + temporality: 2, + samples: Arr.map(every(-30 * SECOND_MS, 5 * MINUTE_MS, 15 * SECOND_MS), (t, k) => [ + t, + k < 9 ? 10 * k : 4 * (k - 9) + 1, + ]), +} +const counterB: SumSeries = { + ...counterA, + attributes: { route: "/b" }, + samples: Arr.map(every(-30 * SECOND_MS, 5 * MINUTE_MS, 15 * SECOND_MS), (t, k) => [t, 2 * k]), +} +const counterOrgB: SumSeries = { + ...counterA, + org: ORG_B, + samples: Arr.map(every(-30 * SECOND_MS, 5 * MINUTE_MS, 15 * SECOND_MS), (t, k) => [t, 1_000 + k]), +} +const DELTAS = [3, 0, 5, 2, 0, 7, 1, 4, 6, 2, 9, 3] +const deltaSum: SumSeries = { + org: ORG_A, + table: "metrics_sum", + metric: "jobs.processed", + unit: "", + attributes: { queue: "emails" }, + resource: RESOURCE, + temporality: 1, + // Exports every 20 s, skipping 1:00-1:40. + samples: Arr.map( + Arr.filter( + every(20 * SECOND_MS, 5 * MINUTE_MS, 20 * SECOND_MS), + (t) => t < MINUTE_MS || t > 100 * SECOND_MS, + ), + (t, i) => [t, DELTAS[i % DELTAS.length] ?? 0], + ), +} +const gauge: SumSeries = { + org: ORG_A, + table: "metrics_gauge", + metric: "queue.depth", + unit: "", + attributes: { "queue.name": "emails" }, + resource: RESOURCE, + temporality: 2, + // Every 10 s with two gaps; the last reading lands exactly on the end of the range. + samples: Arr.map( + Arr.filter( + every(0, 5 * MINUTE_MS, 10 * SECOND_MS), + (t) => !(t > 50 * SECOND_MS && t < 2 * MINUTE_MS) && t !== 4 * MINUTE_MS, + ), + (t, i) => [t, ((i * 7) % 11) - 3], + ), +} +const histogram: HistogramSeries = { + org: ORG_A, + metric: "http.server.request.duration", + unit: "s", + attributes: { "http.route": "/checkout" }, + resource: RESOURCE, + bounds: [0.1, 0.5, 1], + exports: Arr.map(every(-30 * SECOND_MS, 5 * MINUTE_MS, 30 * SECOND_MS), (atMs, i) => ({ + atMs, + counts: [i, 2 * i, 3 * i, i + (i > 4 ? 1 : 0)], + sum: 7 * i, + })), +} + +interface Request { + readonly metricName: string | undefined + readonly matchers: ReadonlyArray<{ + readonly name: string + readonly op: "=" | "!=" | "=~" | "!~" + readonly value: string + }> + readonly startMs: number + readonly endMs: number + readonly originMs: number + readonly widthMs: number + readonly needsValues: boolean +} + +type Matcher = Request["matchers"][number] + +const request = ( + name: string, + matchers: ReadonlyArray = [], + overrides: Partial = {}, +): Request => ({ + metricName: name, + matchers: [{ name: "__name__", op: "=", value: name }, ...matchers], + startMs: BASE_MS, + endMs: BASE_MS + 5 * MINUTE_MS, + originMs: BASE_MS, + widthMs: MINUTE_MS, + needsValues: false, + ...overrides, +}) + +const total = (values: ReadonlyArray): number => Arr.reduce(values, 0, (a, b) => a + b) + +type BucketStats = Readonly | undefined>> + +/** The documented bucket statistics of one series' samples (offsets from BASE_MS). */ +const reference = (samples: ReadonlyArray, req: Request): ReadonlyArray => { + const inRange = Arr.filter( + Arr.map(samples, ([t, v]) => [BASE_MS + t, v] as const), + ([t]) => t > req.startMs && t <= req.endMs, + ) + const endOf = (t: number) => + req.widthMs === 0 ? t : req.originMs + Math.ceil((t - req.originMs) / req.widthMs) * req.widthMs + const groups = Arr.groupBy(inRange, ([t]) => String(endOf(t))) + return Arr.map(Rec.toEntries(groups), ([end, group]) => { + const values = Arr.map(group, ([, v]) => v) + const pairs = Arr.zip(Arr.dropRight(values, 1), Arr.drop(values, 1)) + const xs = Arr.map(group, ([t]) => (t - req.startMs) / 1000) + const first = Arr.headNonEmpty(group) + const last = Arr.lastNonEmpty(group) + const prev = group[group.length - 2] ?? last + const stats = { + end: Number(end), + firstT: first[0], + firstV: first[1], + lastT: last[0], + lastV: last[1], + prevT: prev[0], + prevV: prev[1], + count: group.length, + sum: total(values), + min: Math.min(...values), + max: Math.max(...values), + sumSquares: total(Arr.map(values, (v) => v * v)), + increase: total(Arr.map(pairs, ([p, v]) => (v < p ? v : v - p))), + resets: Arr.filter(pairs, ([p, v]) => v < p).length, + changes: Arr.filter(pairs, ([p, v]) => v !== p).length, + sumT: total(xs), + sumTT: total(Arr.map(xs, (x) => x * x)), + sumTV: total(Arr.map(Arr.zip(xs, values), ([x, v]) => x * v)), + } + return req.needsValues ? { ...stats, values } : stats + }) +} + +/** Running totals of delta samples, from the first one in the range. */ +const accumulate = (samples: ReadonlyArray, startMs: number): ReadonlyArray => { + const inRange = Arr.filter(samples, ([t]) => BASE_MS + t > startMs) + const totals = Arr.scan( + Arr.map(inRange, ([, v]) => v), + 0, + (a, b) => a + b, + ) + return Arr.zipWith(inRange, Arr.drop(totals, 1), ([t], sum) => [t, sum] as const) +} + +/** Rounded so sums taken in another order compare equal. */ +const roundNumber = (value: number): number => Number(value.toPrecision(12)) + +const roundStats = (stats: BucketStats): BucketStats => + Rec.map(stats, (value) => + typeof value === "number" + ? roundNumber(value) + : value === undefined + ? value + : Arr.map(value, roundNumber), + ) + +interface SeriesStats { + readonly labels: Readonly> + readonly buckets: ReadonlyArray +} + +/** A source bucket as the plain record the reference produces. */ +const statsOf = (b: SampleBucket): BucketStats => ({ + end: b.end, + firstT: b.firstT, + firstV: b.firstV, + lastT: b.lastT, + lastV: b.lastV, + prevT: b.prevT, + prevV: b.prevV, + count: b.count, + sum: b.sum, + min: b.min, + max: b.max, + sumSquares: b.sumSquares, + increase: b.increase, + resets: b.resets, + changes: b.changes, + sumT: b.sumT, + sumTT: b.sumTT, + sumTV: b.sumTV, + values: b.values, +}) + +/** The source's series in the reference's shape. */ +const asStats = (series: ReadonlyArray): ReadonlyArray => + Arr.map(series, (s) => ({ labels: s.labels, buckets: Arr.map(s.buckets, statsOf) })) + +const normalized = (series: ReadonlyArray): ReadonlyArray => + Arr.sort( + Arr.map(series, (s) => ({ labels: s.labels, buckets: Arr.map(s.buckets, roundStats) })), + Order.mapInput(Order.String, (s: SeriesStats) => JSON.stringify(s.labels)), + ) + +interface ExpectedSeries { + readonly labels: Readonly> + readonly samples: ReadonlyArray +} + +const expected = (req: Request, series: ReadonlyArray) => + normalized( + Arr.filter( + Arr.map(series, (s) => ({ labels: s.labels, buckets: reference(s.samples, req) })), + (s) => s.buckets.length > 0, + ), + ) + +const decodeRows = decodeJsonEachRow(promqlSelectorRowSchema) +const decodeCatalog = decodeJsonEachRow(promqlCatalogRowSchema) + +const catalogOf = (db: Chdb, org: string): ReadonlyArray => { + const compiled = CH.compileUnsafe(catalogQuery(), { + orgId: OrgId.make(org), + startTime: Str.slice(0, 19)(chTime(-HOUR_MS)), + endTime: Str.slice(0, 19)(chTime(HOUR_MS)), + }) + return catalogFromRows(decodeCatalog(db.query(normalizeSqlForClickHouseClient(compiled.sql)))) +} + +const fetchRows = (db: Chdb, org: string, req: Request, maxSeries = 100) => + Arr.map(buildSelectorQueries(req, catalogOf(db, org), { orgId: OrgId.make(org), maxSeries }), (plan) => ({ + plan, + rows: decodeRows(db.query(normalizeSqlForClickHouseClient(Effect.runSync(plan.compiled).sql))), + })) + +const select = (db: Chdb, org: string, req: Request, maxSeries = 100) => + toSelectorData(req, fetchRows(db, org, req, maxSeries)) + +/** Series the SQL itself returned, before the final matcher check. */ +const sqlSeriesCount = (db: Chdb, org: string, req: Request) => + total(Arr.map(fetchRows(db, org, req), ({ rows }) => rows.length)) + +const selected = (db: Chdb, org: string, req: Request) => normalized(asStats(select(db, org, req).series)) + +const HOUR_MS = 60 * MINUTE_MS + +const labels = (name: string, extra: Readonly>) => ({ + __name__: name, + job: "api", + instance: "i1", + ...extra, +}) + +const bucketSeries = (le: string, index: number): ExpectedSeries => ({ + labels: labels("http_server_request_duration_seconds_bucket", { http_route: "/checkout", le }), + samples: Arr.map(histogram.exports, ({ atMs, counts }) => [atMs, total(Arr.take(counts, index + 1))]), +}) + +describeWithChdb("PromQL selector source", () => { + let root = "" + let db: Chdb + + beforeAll(() => { + root = mkdtempSync(join(tmpdir(), "maple-promql-source-")) + db = Chdb.open({ dataDir: join(root, "data"), schemaSql }) + for (const series of [counterA, counterB, counterOrgB, deltaSum, gauge]) insertValues(db, series) + insertHistogram(db, histogram) + }) + + afterAll(() => { + db.close() + rmSync(root, { recursive: true, force: true }) + }) + + const counters = [ + { labels: labels("requests_total", { route: "/a" }), samples: counterA.samples }, + { labels: labels("requests_total", { route: "/b" }), samples: counterB.samples }, + ] + + test("a counter with a reset, bucketed by minute", () => { + const req = request("requests_total") + const data = select(db, ORG_A, req) + expect(normalized(asStats(data.series))).toEqual(expected(req, counters)) + // The reset at 1:45 (80 to 1) is one reset in the second minute: 70 to 80, then 1, then 1 to 5. + const routeA = Arr.filter(data.series, (s) => s.labels.route === "/a") + expect( + Arr.flatMap(routeA, (s) => + Arr.map(s.buckets, (b) => [b.end - BASE_MS, b.count, b.resets, b.increase]), + ), + ).toEqual([ + [MINUTE_MS, 4, 0, 30], + [2 * MINUTE_MS, 4, 1, 10 + 1 + 4], + [3 * MINUTE_MS, 4, 0, 12], + [4 * MINUTE_MS, 4, 0, 12], + [5 * MINUTE_MS, 4, 0, 12], + ]) + }) + + test("a counter on an unaligned grid, and raw with values", () => { + const unaligned = request("requests_total", [], { + originMs: BASE_MS + 7 * SECOND_MS, + widthMs: 45 * SECOND_MS, + }) + expect(selected(db, ORG_A, unaligned)).toEqual(expected(unaligned, counters)) + const raw = request("requests_total", [], { widthMs: 0, needsValues: true }) + expect(selected(db, ORG_A, raw)).toEqual(expected(raw, counters)) + }) + + test("label matchers run in the query with Prometheus semantics", () => { + const cases: ReadonlyArray, ReadonlyArray]> = [ + [[{ name: "route", op: "=", value: "/a" }], [counters[0]!]], + [[{ name: "route", op: "!=", value: "/a" }], [counters[1]!]], + [[{ name: "route", op: "=~", value: "/b|/c" }], [counters[1]!]], + [[{ name: "route", op: "=~", value: "/" }], []], + [[{ name: "route", op: "!~", value: "/a" }], [counters[1]!]], + [ + [ + { name: "job", op: "=", value: "api" }, + { name: "instance", op: "=~", value: "i." }, + ], + counters, + ], + [[{ name: "missing", op: "=", value: "" }], counters], + [[{ name: "telemetry_sdk_name", op: "=", value: "opentelemetry" }], []], + ] + for (const [matchers, series] of cases) { + const req = request("requests_total", matchers) + expect(selected(db, ORG_A, req)).toEqual(expected(req, series)) + expect(sqlSeriesCount(db, ORG_A, req)).toBe(series.length) + } + }) + + test("another org's rows never appear", () => { + const req = request("requests_total", [], { widthMs: 0 }) + const orgA = Arr.flatMap(select(db, ORG_A, req).series, (s) => Arr.map(s.buckets, (b) => b.lastV)) + expect(Arr.every(orgA, (v) => v < 1_000)).toBe(true) + const orgB = select(db, ORG_B, req) + expect(normalized(asStats(orgB.series))).toEqual( + expected(req, [ + { labels: labels("requests_total", { route: "/a" }), samples: counterOrgB.samples }, + ]), + ) + }) + + test("a delta sum reads as a running counter", () => { + const expectedSeries = (req: Request) => [ + { + labels: labels("jobs_processed_total", { queue: "emails" }), + samples: accumulate(deltaSum.samples, req.startMs), + }, + ] + for (const req of [ + request("jobs_processed_total", [], { originMs: BASE_MS + 7 * SECOND_MS }), + request("jobs_processed_total", [], { widthMs: 0, needsValues: true }), + request("jobs_processed_total", [], { startMs: BASE_MS + 90 * SECOND_MS }), + ]) { + expect(selected(db, ORG_A, req)).toEqual(expected(req, expectedSeries(req))) + } + }) + + test("a gauge with gaps, and the range end is inclusive", () => { + const series = [{ labels: labels("queue_depth", { queue_name: "emails" }), samples: gauge.samples }] + // `queue_name` matches the stored key `queue.name` through the normalized-key fallback. + const byName: Matcher = { name: "queue_name", op: "=", value: "emails" } + for (const req of [ + request("queue_depth", [byName], { widthMs: 45 * SECOND_MS }), + request("queue_depth", [], { widthMs: 0, needsValues: true }), + ]) { + expect(selected(db, ORG_A, req)).toEqual(expected(req, series)) + } + const other = request("queue_depth", [{ name: "queue_name", op: "=", value: "sms" }]) + expect(sqlSeriesCount(db, ORG_A, other)).toBe(0) + expect(sqlSeriesCount(db, ORG_A, request("queue_depth", [byName]))).toBe(1) + }) + + test("an explicit histogram's buckets, count and sum", () => { + const buckets = request("http_server_request_duration_seconds_bucket") + expect(selected(db, ORG_A, buckets)).toEqual( + expected(buckets, [ + bucketSeries("0.1", 0), + bucketSeries("0.5", 1), + bucketSeries("1.0", 2), + bucketSeries("+Inf", 3), + ]), + ) + const inf = request( + "http_server_request_duration_seconds_bucket", + [{ name: "le", op: "=", value: "+Inf" }], + { widthMs: 0 }, + ) + expect(selected(db, ORG_A, inf)).toEqual(expected(inf, [bucketSeries("+Inf", 3)])) + const count = request("http_server_request_duration_seconds_count") + expect(selected(db, ORG_A, count)).toEqual( + expected(count, [ + { + labels: labels("http_server_request_duration_seconds_count", { http_route: "/checkout" }), + samples: Arr.map(histogram.exports, ({ atMs, counts }) => [atMs, total(counts)]), + }, + ]), + ) + const sum = request("http_server_request_duration_seconds_sum", [], { widthMs: 0 }) + expect(selected(db, ORG_A, sum)).toEqual( + expected(sum, [ + { + labels: labels("http_server_request_duration_seconds_sum", { http_route: "/checkout" }), + samples: Arr.map(histogram.exports, ({ atMs, sum }) => [atMs, sum]), + }, + ]), + ) + }) + + test("a query returns one series past the cap so overflow shows", () => { + expect(select(db, ORG_A, request("requests_total"), 1).series).toHaveLength(2) + }) +}) diff --git a/bun.lock b/bun.lock index 5085d28093..2cd2d9bb45 100644 --- a/bun.lock +++ b/bun.lock @@ -157,6 +157,7 @@ }, "devDependencies": { "@effect/vitest": "catalog:effect", + "@maple/promql": "workspace:*", "@types/bun": "^1.4.4", "@types/node": "catalog:tooling", "fast-check": "^4.10.2", @@ -650,6 +651,7 @@ "@maple/lockfiles": "workspace:*", "@maple/primitives": "workspace:*", "@maple/prometheus-otlp": "workspace:*", + "@maple/promql": "workspace:*", "@maple/query-engine": "workspace:*", "@maple/query-engine-integrations": "workspace:*", "@maple/query-model": "workspace:*", @@ -931,6 +933,7 @@ "@maple/cache": "workspace:*", "@maple/domain": "workspace:*", "@maple/primitives": "workspace:*", + "@maple/promql": "workspace:*", "@maple/query-model": "workspace:*", "@maple/strings": "workspace:*", "effect": "catalog:effect", diff --git a/lib/promql/package.json b/lib/promql/package.json index 5ea0068a5d..4e1917fbb2 100644 --- a/lib/promql/package.json +++ b/lib/promql/package.json @@ -3,7 +3,8 @@ "private": true, "type": "module", "exports": { - ".": "./src/index.ts" + ".": "./src/index.ts", + "./compliance": "./scripts/compliance/index.ts" }, "scripts": { "test": "vitest run", diff --git a/lib/promql/scripts/compliance/index.ts b/lib/promql/scripts/compliance/index.ts new file mode 100644 index 0000000000..e461fc2033 --- /dev/null +++ b/lib/promql/scripts/compliance/index.ts @@ -0,0 +1,2 @@ +export { buildDataset, DATA_END_MS, DATA_START_MS, SCRAPE_MS, toOpenMetrics } from "./dataset" +export { QUERIES } from "./queries" diff --git a/packages/backend/package.json b/packages/backend/package.json index 2c9c5587fd..6320bcbca3 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -40,6 +40,7 @@ "@maple/lockfiles": "workspace:*", "@maple/primitives": "workspace:*", "@maple/prometheus-otlp": "workspace:*", + "@maple/promql": "workspace:*", "@maple/query-engine": "workspace:*", "@maple/query-engine-integrations": "workspace:*", "@maple/query-model": "workspace:*", diff --git a/packages/backend/src/services/promql/PromqlQueryService.test.ts b/packages/backend/src/services/promql/PromqlQueryService.test.ts new file mode 100644 index 0000000000..0dfe6eb675 --- /dev/null +++ b/packages/backend/src/services/promql/PromqlQueryService.test.ts @@ -0,0 +1,71 @@ +import { describe, expect, it } from "@effect/vitest" +import { Effect, Layer, Schema } from "effect" +import type { TenantContext } from "@maple/domain/http" +import { OrgId, UserId } from "@maple/primitives" +import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" +import { makeWarehouseServiceStub } from "@maple/backend/testing/warehouse-test-support" +import { PromqlQueryService } from "./PromqlQueryService" + +const tenant: TenantContext = { + orgId: Schema.decodeSync(OrgId)("org_promql"), + userId: Schema.decodeSync(UserId)("user_promql"), + roles: [], + authMode: "self_hosted", +} + +// Every case here fails before reading: the stub dies if a query reaches the warehouse. +const TestLayer = Layer.effect(PromqlQueryService, PromqlQueryService.make).pipe( + Layer.provide(Layer.succeed(WarehouseQueryService, makeWarehouseServiceStub())), +) + +const failureOf = (input: { query: string; startMs: number; endMs: number; stepMs: number }) => + Effect.gen(function* () { + const service = yield* PromqlQueryService + return yield* Effect.flip(service.query(tenant, input)) + }).pipe(Effect.provide(TestLayer)) + +describe("PromqlQueryService", () => { + it.effect("answers a query without selectors without reading the warehouse", () => + Effect.gen(function* () { + const service = yield* PromqlQueryService + const result = yield* service.query(tenant, { + query: "1 + 2 * 3", + startMs: 1000, + endMs: 1000, + stepMs: 0, + }) + expect(result).toEqual({ resultType: "scalar", result: { t: 1000, v: 7 } }) + }).pipe(Effect.provide(TestLayer)), + ) + + it.effect("reports invalid PromQL as a bad query with its position", () => + Effect.gen(function* () { + const error = yield* failureOf({ query: "sum(rate(x[5m])", startMs: 0, endMs: 0, stepMs: 0 }) + expect(error._tag).toBe("@maple/backend/promql/PromqlBadQueryError") + expect(error.message).toMatch(/syntax error|unexpected end/) + }), + ) + + it.effect("refuses more than 11000 points per series, as Prometheus does", () => + Effect.gen(function* () { + const error = yield* failureOf({ query: "up", startMs: 0, endMs: 3_600_000, stepMs: 100 }) + expect(error.message).toMatch(/maximum resolution of 11000 points/) + }), + ) + + it.effect("refuses a range that ends before it starts and a zero step", () => + Effect.gen(function* () { + const backwards = yield* failureOf({ query: "up", startMs: 10_000, endMs: 0, stepMs: 1000 }) + expect(backwards.message).toMatch(/end timestamp must not be before start time/) + const zeroStep = yield* failureOf({ query: "up", startMs: 0, endMs: 10_000, stepMs: 0 }) + expect(zeroStep.message).toMatch(/positive integer/) + }), + ) + + it.effect("reports evaluation errors as execution errors", () => + Effect.gen(function* () { + const error = yield* failureOf({ query: "topk(NaN, vector(1))", startMs: 0, endMs: 0, stepMs: 0 }) + expect(error._tag).toBe("@maple/backend/promql/PromqlExecutionError") + }), + ) +}) diff --git a/packages/backend/src/services/promql/PromqlQueryService.ts b/packages/backend/src/services/promql/PromqlQueryService.ts new file mode 100644 index 0000000000..2756176cfe --- /dev/null +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -0,0 +1,182 @@ +// PromQL over Maple's metric tables. +// +// The engine (`@maple/promql`) parses, plans and evaluates; this service is the +// Maple source behind it: one catalog read resolves Prometheus names to stored +// metrics, then every selector's warehouse queries run concurrently and the +// evaluator recombines their pre-aggregated buckets. + +import { Context, Effect, Layer, Result, Schema, Array as Arr } from "effect" +import { + DEFAULT_LIMITS, + evaluate, + type Expr, + parse, + planRequests, + type QueryParams, + type QueryResult, + type SelectorData, + type SelectorRequest, + type VectorSelector, +} from "@maple/promql" +import { CH, formatWarehouseDateTime } from "@maple/query-engine" +import { + buildSelectorQueries, + catalogFromRows, + catalogQuery, + toSelectorData, +} from "@maple/query-engine/promql" +import type { CatalogMetric } from "@maple/query-engine/promql" +import type { TenantContext } from "@maple/domain/http" +import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" + +/** The query is not valid PromQL, or its parameters are out of range. Prometheus' `bad_data`. */ +export class PromqlBadQueryError extends Schema.TaggedError()( + "@maple/backend/promql/PromqlBadQueryError", + { message: Schema.String, position: Schema.optional(Schema.Number) }, +) {} + +/** The query is valid but cannot be evaluated: limits, many-to-many matching. Prometheus' `execution`. */ +export class PromqlExecutionError extends Schema.TaggedError()( + "@maple/backend/promql/PromqlExecutionError", + { message: Schema.String }, +) {} + +/** Prometheus' own cap on points per series in a range query. */ +export const MAX_STEPS = 11_000 + +/** Selectors one query may read; each is at least one warehouse query. */ +const MAX_SELECTORS = 20 + +const WAREHOUSE_CONCURRENCY = 4 + +export interface PromqlQuery extends QueryParams { + readonly query: string +} + +const validate = (query: PromqlQuery): Effect.Effect => + Effect.gen(function* () { + const { startMs, endMs, stepMs } = query + if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs) { + return yield* new PromqlBadQueryError({ message: "end timestamp must not be before start time" }) + } + if (endMs > startMs) { + if (!(stepMs > 0)) { + return yield* new PromqlBadQueryError({ + message: + "zero or negative query resolution step widths are not accepted. Try a positive integer", + }) + } + if ((endMs - startMs) / stepMs > MAX_STEPS) { + return yield* new PromqlBadQueryError({ + message: `exceeded maximum resolution of ${MAX_STEPS} points per timeseries. Try decreasing the query resolution (?step=XX)`, + }) + } + } + const parsed = parse(query.query) + if (Result.isFailure(parsed)) { + return yield* new PromqlBadQueryError({ + message: parsed.failure.message, + position: parsed.failure.position, + }) + } + return parsed.success + }) + +const span = (requests: ReadonlyArray) => ({ + startMs: Math.min(...Arr.map(requests, (r) => r.startMs)), + endMs: Math.max(...Arr.map(requests, (r) => r.endMs)), +}) + +const make = Effect.gen(function* () { + const warehouse = yield* WarehouseQueryService + + const readCatalog = Effect.fn("PromqlQueryService.readCatalog")(function* ( + tenant: TenantContext, + window: { readonly startMs: number; readonly endMs: number }, + ) { + const compiled = CH.compile(catalogQuery(), { + orgId: tenant.orgId, + startTime: formatWarehouseDateTime(window.startMs), + endTime: formatWarehouseDateTime(window.endMs), + }) + const rows = yield* warehouse.compiledQuery(tenant, compiled, { + profile: "discovery", + context: "promqlCatalog", + }) + return catalogFromRows(rows) + }) + + const readSelector = Effect.fn("PromqlQueryService.readSelector")(function* ( + tenant: TenantContext, + request: SelectorRequest, + catalog: ReadonlyArray, + ) { + const plans = buildSelectorQueries(request, catalog, { + orgId: tenant.orgId, + maxSeries: DEFAULT_LIMITS.maxSeries, + }) + yield* Effect.annotateCurrentSpan({ + "maple.promql.metric": request.metricName ?? "", + "maple.promql.bucket_ms": request.widthMs, + "maple.promql.queries": plans.length, + }) + const results = yield* Effect.forEach( + plans, + (plan) => + Effect.map( + warehouse.compiledQuery(tenant, plan.compiled, { + profile: "aggregation", + context: "promqlSelector", + }), + (rows) => ({ plan, rows }), + ), + { concurrency: WAREHOUSE_CONCURRENCY }, + ) + return toSelectorData(request, results) + }) + + const query = Effect.fn("PromqlQueryService.query")(function* ( + tenant: TenantContext, + input: PromqlQuery, + ) { + yield* Effect.annotateCurrentSpan({ + "maple.promql.query": input.query, + "maple.promql.range_ms": input.endMs - input.startMs, + "maple.promql.step_ms": input.stepMs, + }) + const expr = yield* validate(input) + const plan = planRequests(expr, input) + const entries = [...plan.entries()] + if (entries.length > MAX_SELECTORS) { + return yield* new PromqlBadQueryError({ + message: `query reads more than ${MAX_SELECTORS} selectors`, + }) + } + const catalog = + entries.length === 0 + ? [] + : yield* readCatalog(tenant, span(Arr.map(entries, ([, request]) => request))) + const read = yield* Effect.forEach( + entries, + ([selector, request]) => + Effect.map( + readSelector(tenant, request, catalog), + (selectorData): readonly [VectorSelector, SelectorData] => [selector, selectorData], + ), + { concurrency: WAREHOUSE_CONCURRENCY }, + ) + const result = evaluate({ expr, params: input, data: new Map(read) }) + if (Result.isFailure(result)) + return yield* new PromqlExecutionError({ message: result.failure.message }) + return result.success satisfies QueryResult + }) + + return { query } +}) + +export class PromqlQueryService extends Context.Service()( + "@maple/backend/services/PromqlQueryService", + { make }, +) { + static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(WarehouseQueryService.layer)) +} diff --git a/packages/query-engine/package.json b/packages/query-engine/package.json index 3b7e0a0eb8..40b60c5e86 100644 --- a/packages/query-engine/package.json +++ b/packages/query-engine/package.json @@ -21,7 +21,8 @@ "./ch/tables": "./src/ch/tables.ts", "./ch/schema": "./src/ch/schema.ts", "./ch/format": "./src/ch/queries/format.ts", - "./ch/query-helpers": "./src/ch/queries/query-helpers.ts" + "./ch/query-helpers": "./src/ch/queries/query-helpers.ts", + "./promql": "./src/promql/index.ts" }, "scripts": { "test": "vitest run", @@ -32,6 +33,7 @@ "@maple/cache": "workspace:*", "@maple/domain": "workspace:*", "@maple/primitives": "workspace:*", + "@maple/promql": "workspace:*", "@maple/query-model": "workspace:*", "@maple/strings": "workspace:*", "effect": "catalog:effect" diff --git a/packages/query-engine/src/ch/index.ts b/packages/query-engine/src/ch/index.ts index cfc52e8f95..82f5d1e580 100644 --- a/packages/query-engine/src/ch/index.ts +++ b/packages/query-engine/src/ch/index.ts @@ -34,6 +34,7 @@ export * from "./pipe-rows" export * from "./queries/traces" export * from "./queries/attribute-keys" export * from "./queries/metrics" +export * from "./queries/promql" export * from "./queries/logs" export * from "./queries/session-replays" export * from "./queries/session-events" diff --git a/packages/query-engine/src/ch/queries/promql.ts b/packages/query-engine/src/ch/queries/promql.ts new file mode 100644 index 0000000000..efea4edd0d --- /dev/null +++ b/packages/query-engine/src/ch/queries/promql.ts @@ -0,0 +1,364 @@ +// PromQL selector data: one stored metric component (value, histogram bucket, count or sum), +// per series, its samples in `(startMs, endMs]` aggregated into evaluation buckets. +// +// Stages: scan with pushed-down label matchers; series key and sample value (delta sums +// accumulated into counters); previous sample per series; per (series, bucket) statistics; +// one row per series with the bucket statistics as parallel arrays. + +import { Schema } from "effect" +import * as T from "@maple-dev/effect-orm/clickhouse" +import { from, fromQuery, param, sql, table } from "@maple-dev/effect-orm/clickhouse" +import * as CH from "@maple-dev/effect-orm/expr" +import { CHNumber } from "../schema" +import * as Datasources from "@maple/domain/tinybird/datasources" +import { orgId, orgIdParam, utcSecondsParam } from "../tables" + +export type PromqlMetricTable = + | "metrics_sum" + | "metrics_gauge" + | "metrics_histogram" + | "metrics_exponential_histogram" + +export type PromqlComponent = "value" | "bucket" | "count" | "sum" + +/** The columns pushed-down matchers read. */ +export interface PromqlLabelColumns { + readonly Attributes: CH.Expr> + readonly ResourceAttributes: CH.Expr> + readonly ServiceName: CH.Expr +} + +export interface PromqlSelectorOpts { + readonly table: PromqlMetricTable + readonly component: PromqlComponent + /** Stored OTel metric names; one query reads them all. */ + readonly metricNames: ReadonlyArray + /** 0: one bucket per sample. */ + readonly widthMs: number + /** Also return each bucket's values in time order (raw mode). */ + readonly needsValues: boolean + /** Rows returned at most; pass the series cap plus one to detect overflow. */ + readonly limit: number + /** Label matchers as WHERE conditions, built from the table's columns. */ + readonly conditions: ($: PromqlLabelColumns) => ReadonlyArray +} + +/** Params: `orgId`, plus epoch ms `startMs`, `endMs`, `originMs` (bucket grid), `timeOriginMs` (regression). */ +export interface PromqlSelectorParams { + readonly orgId: string + readonly startMs: number + readonly endMs: number + readonly originMs: number + readonly timeOriginMs: number +} + +const stringMap = T.map(T.string, T.string) + +const metricTable = (name: PromqlMetricTable) => + table(name, { + external: true, + columns: { + OrgId: orgId, + MetricName: T.string, + ServiceName: T.string, + Attributes: stringMap, + ResourceAttributes: stringMap, + TimeUnix: T.dateTime64, + }, + }) + +/** The sample of one stored row as `[le, value]`; histogram buckets expand into one row per bound. */ +const samplePair = (component: PromqlComponent) => { + switch (component) { + case "bucket": + return sql( + T.array(T.float64), + )`arrayJoin(arrayMap((b, c) -> [b, toFloat64(c)], arrayPushBack(ExplicitBounds, inf), arrayCumSum(BucketCounts)))` + case "count": + return sql(T.array(T.float64))`[0, toFloat64(Count)]` + case "sum": + return sql(T.array(T.float64))`[0, toFloat64(Sum)]` + case "value": + return sql(T.array(T.float64))`[0, Value]` + } +} + +/** Delta temporality (OTel `AggregationTemporality` 1); gauges have no temporality. */ +const isDeltaExpr = (tableName: PromqlMetricTable) => + tableName === "metrics_gauge" ? sql(T.uint8)`0` : sql(T.uint8)`AggregationTemporality = 1` + +const finiteSampleCond = (component: PromqlComponent) => { + switch (component) { + case "bucket": + return sql.cond`length(BucketCounts) = length(ExplicitBounds) + 1` + case "count": + return undefined + case "sum": + return sql.cond`isFinite(Sum)` + case "value": + return sql.cond`isFinite(Value)` + } +} + +const scanQuery = (opts: PromqlSelectorOpts) => + from(metricTable(opts.table)) + .select(($) => ({ + MetricName: $.MetricName, + ServiceName: $.ServiceName, + Attributes: $.Attributes, + ResourceAttributes: $.ResourceAttributes, + t: sql(T.int64)`toUnixTimestamp64Milli(${$.TimeUnix})`, + isDelta: isDeltaExpr(opts.table), + pair: samplePair(opts.component), + })) + .where(($) => [ + $.OrgId.eq(orgIdParam), + $.MetricName.in_(...opts.metricNames), + sql.cond`${$.TimeUnix} > fromUnixTimestamp64Milli(toInt64(${param.int("startMs")}))`, + sql.cond`${$.TimeUnix} <= fromUnixTimestamp64Milli(toInt64(${param.int("endMs")}))`, + // A no-recorded-value point (a failed scrape) is not a sample. + sql.cond`bitAnd(Flags, 1) = 0`, + finiteSampleCond(opts.component), + ...opts.conditions($), + ]) + +/** The series key: the stored identity of the series, plus the bound for a bucket. */ +const keyedQuery = (opts: PromqlSelectorOpts) => + fromQuery(scanQuery(opts), "scan").select(($) => ({ + sk: sql( + T.uint64, + )`cityHash64(${$.MetricName}, ${$.ServiceName}, mapKeys(${$.Attributes}), mapValues(${$.Attributes}), mapKeys(${$.ResourceAttributes}), mapValues(${$.ResourceAttributes}), ${$.pair}[1])`, + MetricName: $.MetricName, + ServiceName: $.ServiceName, + Attributes: $.Attributes, + ResourceAttributes: $.ResourceAttributes, + t: $.t, + isDelta: $.isDelta, + le: sql(T.float64)`${$.pair}[1]`, + raw: sql(T.float64)`${$.pair}[2]`, + })) + +/** Each sample's value and the series' previous sample; delta samples accumulate into a counter. */ +const windowedQuery = (opts: PromqlSelectorOpts) => + fromQuery(keyedQuery(opts), "keyed").select(($) => { + const lag = CH.windowSpec({ + partitionBy: [$.sk], + orderBy: [[$.t, "asc"]], + frame: CH.rowsBetween(CH.preceding(1), CH.currentRow), + }) + const running = CH.windowSpec({ + partitionBy: [$.sk], + orderBy: [[$.t, "asc"]], + frame: CH.rowsBetween(CH.unboundedPreceding, CH.currentRow), + }) + const cumulative = CH.over(CH.sum($.raw), running) + return { + sk: $.sk, + MetricName: $.MetricName, + ServiceName: $.ServiceName, + Attributes: $.Attributes, + ResourceAttributes: $.ResourceAttributes, + le: $.le, + t: $.t, + v: sql(T.float64)`if(${$.isDelta} = 1, ${cumulative}, ${$.raw})`, + pv: sql( + T.float64, + )`if(${$.isDelta} = 1, ${cumulative} - ${$.raw}, ${CH.over(CH.lagInFrame($.raw, 1, $.raw), lag)})`, + pt: CH.over(CH.lagInFrame($.t, 1, $.t), lag), + n: CH.over(CH.count(), lag), + } + }) + +/** The bucket a time falls in, `(end - width, end]`, as its end; the time itself in raw mode. */ +const bucketEndExpr = (time: CH.Expr, widthMs: number) => + widthMs > 0 + ? sql( + T.int64, + )`${param.int("originMs")} + toInt64(ceil((${time} - ${param.int("originMs")}) / ${widthMs})) * ${widthMs}` + : sql(T.int64)`${time}` + +const placedQuery = (opts: PromqlSelectorOpts) => + fromQuery(windowedQuery(opts), "windowed").select(($) => { + const end = bucketEndExpr($.t, opts.widthMs) + return { + sk: $.sk, + MetricName: $.MetricName, + ServiceName: $.ServiceName, + Attributes: $.Attributes, + ResourceAttributes: $.ResourceAttributes, + le: $.le, + t: $.t, + v: $.v, + pv: $.pv, + pt: $.pt, + end, + // The pair (previous, this) counts in this bucket only when both samples are in it. + pairIn: sql(T.uint8)`${$.n} = 2 AND ${bucketEndExpr($.pt, opts.widthMs)} = ${end}`, + ts: sql(T.float64)`(${$.t} - ${param.int("timeOriginMs")}) / 1000`, + } + }) + +const bucketQuery = (opts: PromqlSelectorOpts) => + fromQuery(placedQuery(opts), "placed") + .select(($) => { + const count = CH.count() + const lastV = CH.argMax($.v, $.t) + const lastT = CH.max_($.t) + return { + sk: $.sk, + end: $.end, + MetricName: CH.any_($.MetricName), + ServiceName: CH.any_($.ServiceName), + Attributes: CH.any_($.Attributes), + ResourceAttributes: CH.any_($.ResourceAttributes), + le: CH.any_($.le), + firstT: CH.min_($.t), + firstV: CH.argMin($.v, $.t), + lastT, + lastV, + prevT: sql(T.float64)`if(${count} >= 2, ${CH.argMax($.pt, $.t)}, ${lastT})`, + prevV: sql(T.float64)`if(${count} >= 2, ${CH.argMax($.pv, $.t)}, ${lastV})`, + count, + sum: CH.sum($.v), + min: CH.min_($.v), + max: CH.max_($.v), + sumSquares: sql(T.float64)`sum(${$.v} * ${$.v})`, + increase: sql( + T.float64, + )`sumIf(if(${$.v} < ${$.pv}, ${$.v}, ${$.v} - ${$.pv}), ${$.pairIn} = 1)`, + resets: sql(T.float64)`countIf(${$.pairIn} = 1 AND ${$.v} < ${$.pv})`, + changes: sql(T.float64)`countIf(${$.pairIn} = 1 AND ${$.v} != ${$.pv})`, + sumT: sql(T.float64)`sum(${$.ts})`, + sumTT: sql(T.float64)`sum(${$.ts} * ${$.ts})`, + sumTV: sql(T.float64)`sum(${$.ts} * ${$.v})`, + values: opts.needsValues + ? sql(T.array(T.float64))`arrayMap(x -> x.2, arraySort(groupArray((${$.t}, ${$.v}))))` + : sql(T.array(T.float64))`emptyArrayFloat64()`, + } + }) + .groupBy("sk", "end") + +const BUCKET_FIELDS = [ + "end", + "firstT", + "firstV", + "lastT", + "lastV", + "prevT", + "prevV", + "count", + "sum", + "min", + "max", + "sumSquares", + "increase", + "resets", + "changes", + "sumT", + "sumTT", + "sumTV", +] as const + +export type PromqlBucketField = (typeof BUCKET_FIELDS)[number] + +/** One row per series: its labels' sources, and each bucket statistic as an array in bucket order. */ +export function promqlSelectorQuery(opts: PromqlSelectorOpts) { + return fromQuery(bucketQuery(opts), "buckets") + .select(($) => { + // Every array in bucket order: sorted by the bucket ends gathered beside it. + const ends = sql`groupArray(${$.end})` + const column = (field: PromqlBucketField) => + sql(T.array(T.float64))`arraySort((x, e) -> e, groupArray(toFloat64(${$[field]})), ${ends})` + return { + series: sql(T.string)`toString(${$.sk})`, + metricName: CH.any_($.MetricName), + serviceName: CH.any_($.ServiceName), + attributes: CH.any_($.Attributes), + resourceAttributes: CH.any_($.ResourceAttributes), + le: sql(T.string)`toString(any(${$.le}))`, + end: column("end"), + firstT: column("firstT"), + firstV: column("firstV"), + lastT: column("lastT"), + lastV: column("lastV"), + prevT: column("prevT"), + prevV: column("prevV"), + count: column("count"), + sum: column("sum"), + min: column("min"), + max: column("max"), + sumSquares: column("sumSquares"), + increase: column("increase"), + resets: column("resets"), + changes: column("changes"), + sumT: column("sumT"), + sumTT: column("sumTT"), + sumTV: column("sumTV"), + values: sql( + T.array(T.array(T.float64)), + )`arraySort((x, e) -> e, groupArray(${$.values}), ${ends})`, + } + }) + .groupBy("series") + .limit(opts.limit) + .format("JSON") +} + +const numbers = Schema.Array(CHNumber) + +export const promqlSelectorRowSchema = Schema.Struct({ + series: Schema.String, + metricName: Schema.String, + serviceName: Schema.String, + attributes: Schema.Record(Schema.String, Schema.String), + resourceAttributes: Schema.Record(Schema.String, Schema.String), + /** The bucket bound as ClickHouse prints it (`inf` for +Inf); `0` outside `_bucket`. */ + le: Schema.String, + end: numbers, + firstT: numbers, + firstV: numbers, + lastT: numbers, + lastV: numbers, + prevT: numbers, + prevV: numbers, + count: numbers, + sum: numbers, + min: numbers, + max: numbers, + sumSquares: numbers, + increase: numbers, + resets: numbers, + changes: numbers, + sumT: numbers, + sumTT: numbers, + sumTV: numbers, + values: Schema.Array(numbers), +}) +export type PromqlSelectorRow = typeof promqlSelectorRowSchema.Type + +/** Every stored metric of the org seen in `[startTime, endTime]`, for resolving selector names. */ +export function promqlCatalogQuery(opts: { readonly limit: number }) { + return from(Datasources.metricCatalog) + .select(($) => ({ + metricName: $.MetricName, + metricType: $.MetricType, + unit: CH.any_($.MetricUnit), + isMonotonic: sql(T.uint8)`max(${$.IsMonotonic})`, + })) + .where(($) => [ + $.OrgId.eq(orgIdParam), + $.Hour.gte(CH.toStartOfInterval(CH.toDateTime(utcSecondsParam("startTime")), 3600)), + $.Hour.lte(utcSecondsParam("endTime")), + ]) + .groupBy("metricName", "metricType") + .limit(opts.limit) + .format("JSON") +} + +export const promqlCatalogRowSchema = Schema.Struct({ + metricName: Schema.String, + metricType: Schema.String, + unit: Schema.String, + isMonotonic: CHNumber, +}) +export type PromqlCatalogRow = typeof promqlCatalogRowSchema.Type diff --git a/packages/query-engine/src/promql/index.ts b/packages/query-engine/src/promql/index.ts new file mode 100644 index 0000000000..43a35be15b --- /dev/null +++ b/packages/query-engine/src/promql/index.ts @@ -0,0 +1,9 @@ +export * from "./labels" +export * from "./names" +export * from "./source" +export { + type PromqlCatalogRow, + promqlCatalogRowSchema, + type PromqlSelectorRow, + promqlSelectorRowSchema, +} from "../ch/queries/promql" diff --git a/packages/query-engine/src/promql/labels.test.ts b/packages/query-engine/src/promql/labels.test.ts new file mode 100644 index 0000000000..4ad73b65a4 --- /dev/null +++ b/packages/query-engine/src/promql/labels.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from "vitest" +import { formatLe, labelValue, normalizeLabelName, seriesLabels, type StoredSeries } from "./labels" + +const row = (overrides: Partial = {}): StoredSeries => ({ + promName: "http_server_request_duration_seconds_bucket", + serviceName: "checkout", + attributes: { "http.request.method": "GET", "http.response.status_code": "200" }, + resourceAttributes: { + "service.name": "checkout", + "service.namespace": "shop", + "service.instance.id": "pod-1", + "host.name": "node-a", + "maple.org_id": "org_1", + "telemetry.sdk.name": "opentelemetry", + "process.command_line": "node server.js", + }, + le: 0.5, + ...overrides, +}) + +describe("normalizeLabelName", () => { + it("follows the Prometheus label name rules", () => { + expect(normalizeLabelName("http.request.method")).toBe("http_request_method") + expect(normalizeLabelName("a..b:c")).toBe("a_b_c") + expect(normalizeLabelName("9lives")).toBe("_9lives") + }) +}) + +describe("formatLe", () => { + it("formats bounds as Prometheus 3 does", () => { + expect(formatLe(Infinity)).toBe("+Inf") + expect(formatLe(0.5)).toBe("0.5") + expect(formatLe(1)).toBe("1.0") + expect(formatLe(100000)).toBe("100000.0") + expect(formatLe(1e6)).toBe("1e+06") + expect(formatLe(0.00001)).toBe("1e-05") + expect(formatLe(0.0001)).toBe("0.0001") + }) +}) + +describe("seriesLabels", () => { + it("merges datapoint and resource labels, with job, instance, __name__ and le", () => { + expect(seriesLabels(row())).toEqual({ + __name__: "http_server_request_duration_seconds_bucket", + host_name: "node-a", + http_request_method: "GET", + http_response_status_code: "200", + instance: "pod-1", + job: "shop/checkout", + le: "0.5", + }) + }) + + it("lets datapoint attributes win over resource attributes, and exact keys over normalized ones", () => { + const labels = seriesLabels( + row({ + attributes: { + "host.name": "dp-host", + region: "eu", + "region.x": "ignored", + job: "node", + instance: "10.0.0.1:9100", + }, + resourceAttributes: { "host.name": "res-host", region: "us", "service.name": "api" }, + le: undefined, + }), + ) + expect(labels.host_name).toBe("dp-host") + expect(labels.region).toBe("eu") + expect(labels.job).toBe("node") + expect(labels.instance).toBe("10.0.0.1:9100") + expect(labels.le).toBeUndefined() + }) + + it("falls back to the ServiceName column for job and leaves instance out without an instance id", () => { + const labels = seriesLabels(row({ resourceAttributes: {}, attributes: {}, le: undefined })) + expect(labels).toEqual({ __name__: "http_server_request_duration_seconds_bucket", job: "checkout" }) + }) + + it("treats an empty value as a missing label", () => { + expect(labelValue(row({ attributes: { "host.name": "" } }), "host_name")).toBe("node-a") + expect(labelValue(row(), "missing")).toBe("") + }) + + it("never promotes bookkeeping resource attributes", () => { + const labels = seriesLabels(row()) + expect(labels).not.toHaveProperty("maple_org_id") + expect(labels).not.toHaveProperty("telemetry_sdk_name") + expect(labels).not.toHaveProperty("process_command_line") + }) +}) diff --git a/packages/query-engine/src/promql/labels.ts b/packages/query-engine/src/promql/labels.ts new file mode 100644 index 0000000000..78f411a265 --- /dev/null +++ b/packages/query-engine/src/promql/labels.ts @@ -0,0 +1,169 @@ +// A stored row's Prometheus label set, computed the same way in TypeScript (`seriesLabels`) +// and in ClickHouse (`labelValueExpr`), so label matchers can run in the WHERE clause. +// An empty value is a missing label, as in Prometheus. + +import type { LabelMatcher } from "@maple/promql" +import * as CH from "@maple-dev/effect-orm/expr" +import { sql, string as chString } from "@maple-dev/effect-orm/clickhouse" +import { Array as Arr, Option, pipe, Record as Rec, String as Str } from "effect" +import { matchesValue } from "./names" + +export interface StoredSeries { + readonly promName: string + readonly serviceName: string + readonly attributes: Readonly> + readonly resourceAttributes: Readonly> + /** The bucket's upper bound, for `_bucket` series only. */ + readonly le: number | undefined +} + +/** Label name rule: characters outside `[a-zA-Z0-9_]` become `_`, runs collapse, a leading digit gets `_`. */ +export const normalizeLabelName = (key: string): string => { + const cleaned = pipe(key, Str.replace(/[^a-zA-Z0-9_]/g, "_"), Str.replace(/_+/g, "_")) + return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned +} + +/** Resource attributes that are identity or bookkeeping, not labels. */ +const EXCLUDED_RESOURCE_PREFIXES = ["maple_", "maple.", "telemetry.", "service.", "process.command"] + +export const isExcludedResourceKey = (key: string): boolean => + Arr.some(EXCLUDED_RESOURCE_PREFIXES, (prefix) => Str.startsWith(prefix)(key)) + +const lookup = ( + attrs: Readonly>, + name: string, + allowed: (key: string) => boolean, +): string => { + if (Rec.has(attrs, name) && allowed(name)) return attrs[name] ?? "" + return pipe( + Rec.toEntries(attrs), + Arr.findFirst(([key]) => allowed(key) && normalizeLabelName(key) === name), + Option.match({ onNone: () => "", onSome: ([, value]) => value }), + ) +} + +const always = () => true +const notExcluded = (key: string) => !isExcludedResourceKey(key) + +/** One label's value; `""` when the series does not have it. */ +export const labelValue = (row: StoredSeries, name: string): string => { + if (name === "__name__") return row.promName + if (name === "le" && row.le !== undefined) return formatLe(row.le) + const datapoint = lookup(row.attributes, name, always) + if (datapoint !== "") return datapoint + if (name === "job") { + const declared = row.resourceAttributes["service.name"] ?? "" + const service = declared === "" ? row.serviceName : declared + const namespace = row.resourceAttributes["service.namespace"] ?? "" + return namespace === "" ? service : `${namespace}/${service}` + } + if (name === "instance") return row.resourceAttributes["service.instance.id"] ?? "" + return lookup(row.resourceAttributes, name, notExcluded) +} + +/** Go `strconv.FormatFloat(f, 'g', -1, 64)`, with `.0` on integers as Prometheus 3 writes `le`. */ +export const formatLe = (le: number): string => { + if (le === Infinity) return "+Inf" + if (le === -Infinity) return "-Inf" + if (Number.isNaN(le)) return "NaN" + const [mantissa, exponentText = "0"] = Str.split(le.toExponential(), "e") + const exponent = Number(exponentText) + const text = + exponent < -4 || exponent >= 6 + ? `${mantissa}e${exponent < 0 ? "-" : "+"}${Str.padStart(2, "0")(String(Math.abs(exponent)))}` + : String(le) + return /[.e]/.test(text) ? text : `${text}.0` +} + +/** Every label of a stored series. */ +export const seriesLabels = (row: StoredSeries): Readonly> => { + const names = new Set(["__name__", "job", "instance"]) + if (row.le !== undefined) names.add("le") + for (const key of Rec.keys(row.attributes)) names.add(normalizeLabelName(key)) + for (const key of Rec.keys(row.resourceAttributes)) { + if (notExcluded(key)) names.add(normalizeLabelName(key)) + } + const labels: Record = {} + for (const name of [...names].sort()) { + const value = labelValue(row, name) + if (value !== "") labels[name] = value + } + return labels +} + +/** Whether a series' labels satisfy every matcher (a missing label is `""`). */ +export const matchesAll = (labels: Readonly>, matchers: ReadonlyArray) => + Arr.every(matchers, (m) => matchesValue(m, labels[m.name] ?? "")) + +/** The columns a label value reads. */ +export interface LabelColumns { + readonly Attributes: CH.Expr> + readonly ResourceAttributes: CH.Expr> + readonly ServiceName: CH.Expr +} + +/** `normalizeLabelName` of the lambda variable `_k`, in ClickHouse. */ +const NORMALIZED_KEY = sql.raw( + "concat(if(match(_k, '^[0-9]'), '_', ''), replaceRegexpAll(replaceRegexpAll(_k, '[^a-zA-Z0-9_]', '_'), '_+', '_'))", +) + +const EXCLUDED_KEY = sql.raw( + `(${Arr.join( + Arr.map(EXCLUDED_RESOURCE_PREFIXES, (prefix) => `startsWith(_k, '${prefix}')`), + " OR ", + )})`, +) + +/** The exact key first; only a missing key pays for normalizing every key of the map. */ +const mapLookupExpr = (map: CH.Expr>, name: string, filterExcluded: boolean) => { + const fallback = filterExcluded + ? sql( + chString, + )`mapValues(${map})[arrayFirstIndex(_k -> NOT ${EXCLUDED_KEY} AND ${NORMALIZED_KEY} = ${name}, mapKeys(${map}))]` + : sql( + chString, + )`mapValues(${map})[arrayFirstIndex(_k -> ${NORMALIZED_KEY} = ${name}, mapKeys(${map}))]` + if (filterExcluded && isExcludedResourceKey(name)) return fallback + return sql(chString)`if(mapContains(${map}, ${name}), ${map}[${name}], ${fallback})` +} + +/** + * The value `labelValue` gives a label, as a ClickHouse expression; `undefined` for `__name__` + * and `le`, which come from the resolved name and the bucket and are checked after the fetch. + */ +export const labelValueExpr = ($: LabelColumns, name: string): CH.Expr | undefined => { + if (name === "__name__" || name === "le") return undefined + const datapoint = mapLookupExpr($.Attributes, name, false) + const resource = $.ResourceAttributes + if (name === "job") { + const service = sql( + chString, + )`if(${resource}['service.name'] != '', ${resource}['service.name'], ${$.ServiceName})` + const namespace = sql(chString)`${resource}['service.namespace']` + return sql( + chString, + )`if(${datapoint} != '', ${datapoint}, if(${namespace} != '', concat(${namespace}, '/', ${service}), ${service}))` + } + if (name === "instance") { + return sql(chString)`if(${datapoint} != '', ${datapoint}, ${resource}['service.instance.id'])` + } + const fromResource = mapLookupExpr(resource, name, true) + return sql(chString)`if(${datapoint} != '', ${datapoint}, ${fromResource})` +} + +/** A matcher as a WHERE condition, Prometheus semantics; `undefined` when it cannot be pushed down. */ +export const matcherCondition = ($: LabelColumns, matcher: LabelMatcher): CH.Condition | undefined => { + const value = labelValueExpr($, matcher.name) + if (value === undefined) return undefined + const pattern = `^(?:${matcher.value})$` + switch (matcher.op) { + case "=": + return sql.cond`${value} = ${matcher.value}` + case "!=": + return sql.cond`${value} != ${matcher.value}` + case "=~": + return sql.cond`match(${value}, ${pattern})` + case "!~": + return sql.cond`NOT match(${value}, ${pattern})` + } +} diff --git a/packages/query-engine/src/promql/names.test.ts b/packages/query-engine/src/promql/names.test.ts new file mode 100644 index 0000000000..0464c1ea5d --- /dev/null +++ b/packages/query-engine/src/promql/names.test.ts @@ -0,0 +1,131 @@ +import type { LabelMatcher } from "@maple/promql" +import { Array as Arr } from "effect" +import { describe, expect, it } from "vitest" +import { + type CatalogMetric, + normalizeMetricName, + promNamesOf, + resolveSelectorName, + unitSuffix, +} from "./names" + +const eq = (value: string): LabelMatcher => ({ name: "__name__", op: "=", value }) +const re = (value: string): LabelMatcher => ({ name: "__name__", op: "=~", value }) + +const metric = (overrides: Partial & Pick): CatalogMetric => ({ + metricType: "gauge", + isMonotonic: false, + unit: "", + ...overrides, +}) + +const duration = metric({ metricName: "http.server.request.duration", metricType: "histogram", unit: "s" }) +const cpuTime = metric({ metricName: "system.cpu.time", metricType: "sum", isMonotonic: true, unit: "s" }) +const scraped = metric({ metricName: "node_cpu_seconds_total", metricType: "sum", isMonotonic: true }) +const memory = metric({ metricName: "jvm.memory.used", unit: "By" }) +const utilization = metric({ metricName: "system.cpu.utilization", unit: "1" }) +const scrapedHistogram = metric({ metricName: "http_request_duration_seconds", metricType: "histogram" }) +const expHistogram = metric({ metricName: "rpc.duration", metricType: "exponential_histogram", unit: "ms" }) + +const CATALOG = [duration, cpuTime, scraped, memory, utilization, scrapedHistogram, expHistogram] + +const resolve = (...matchers: ReadonlyArray) => + Arr.map( + resolveSelectorName(matchers, CATALOG), + (t) => `${t.table}:${t.metricName}:${t.component}:${t.promName}`, + ) + +const promNames = (m: CatalogMetric) => Arr.map(promNamesOf(m), (n) => n.promName) + +describe("normalizeMetricName", () => { + it("replaces invalid characters, collapses and trims underscores, guards a leading digit", () => { + expect(normalizeMetricName("http.server..request-duration_")).toBe("http_server_request_duration") + expect(normalizeMetricName("2xx.count")).toBe("_2xx_count") + expect(normalizeMetricName("ns:metric.name")).toBe("ns:metric_name") + }) +}) + +describe("unitSuffix", () => { + it("translates OTel units", () => { + expect(unitSuffix("s", "sum")).toEqual(["seconds"]) + expect(unitSuffix("KiBy", "gauge")).toEqual(["kibibytes"]) + expect(unitSuffix("{request}", "sum")).toEqual([]) + expect(unitSuffix("By/s", "gauge")).toEqual(["bytes", "per", "second"]) + expect(unitSuffix("{packets}/s", "gauge")).toEqual(["per", "second"]) + expect(unitSuffix("1", "gauge")).toEqual(["ratio"]) + expect(unitSuffix("1", "sum")).toEqual([]) + }) +}) + +describe("promNamesOf", () => { + it("names a histogram's series after its base with the unit", () => { + expect(promNames(duration)).toContain("http_server_request_duration_seconds_bucket") + }) + + it("puts the canonical counter name first and keeps the stored name", () => { + const names = promNames(cpuTime) + expect(names[0]).toBe("system_cpu_time_seconds_total") + expect(names).toContain("system.cpu.time") + }) + + it("does not repeat a unit or _total the scraped name already has", () => { + expect(promNames(scraped)).toEqual(["node_cpu_seconds_total"]) + }) +}) + +describe("resolveSelectorName", () => { + it("resolves the translated histogram components", () => { + expect(resolve(eq("http_server_request_duration_seconds_bucket"))).toEqual([ + "metrics_histogram:http.server.request.duration:bucket:http_server_request_duration_seconds_bucket", + ]) + expect(resolve(eq("http_server_request_duration_count"))).toEqual([ + "metrics_histogram:http.server.request.duration:count:http_server_request_duration_count", + ]) + }) + + it("matches a scraped name exactly", () => { + expect(resolve(eq("node_cpu_seconds_total"))).toEqual([ + "metrics_sum:node_cpu_seconds_total:value:node_cpu_seconds_total", + ]) + expect(resolve(eq("http_request_duration_seconds_bucket"))).toEqual([ + "metrics_histogram:http_request_duration_seconds:bucket:http_request_duration_seconds_bucket", + ]) + }) + + it("resolves counters, units and ratios", () => { + expect(resolve(eq("system_cpu_time_seconds_total"))).toEqual([ + "metrics_sum:system.cpu.time:value:system_cpu_time_seconds_total", + ]) + expect(resolve(eq("jvm_memory_used_bytes"))).toEqual([ + "metrics_gauge:jvm.memory.used:value:jvm_memory_used_bytes", + ]) + expect(resolve(eq("system_cpu_utilization_ratio"))).toEqual([ + "metrics_gauge:system.cpu.utilization:value:system_cpu_utilization_ratio", + ]) + }) + + it("gives each stored metric and component one name, the first a regex accepts", () => { + expect(resolve(re("system.*"))).toEqual([ + "metrics_sum:system.cpu.time:value:system_cpu_time_seconds_total", + "metrics_gauge:system.cpu.utilization:value:system_cpu_utilization_ratio", + ]) + }) + + it("anchors regexes and applies negative matchers", () => { + expect(resolve(re("cpu"))).toEqual([]) + expect( + resolve(re("rpc_duration_milliseconds_.*"), { + name: "__name__", + op: "!=", + value: "rpc_duration_milliseconds_sum", + }), + ).toEqual(["metrics_exponential_histogram:rpc.duration:count:rpc_duration_milliseconds_count"]) + }) + + it("has no bucket series for an exponential histogram", () => { + expect(resolve(re(".*_bucket"))).not.toContain( + "metrics_exponential_histogram:rpc.duration:bucket:rpc_duration_milliseconds_bucket", + ) + expect(resolve(re(".*_bucket"))).toHaveLength(2) + }) +}) diff --git a/packages/query-engine/src/promql/names.ts b/packages/query-engine/src/promql/names.ts new file mode 100644 index 0000000000..6cba9d91da --- /dev/null +++ b/packages/query-engine/src/promql/names.ts @@ -0,0 +1,210 @@ +// Prometheus names for OTel metrics, after the OpenTelemetry-to-Prometheus translation +// ("UnderscoreEscapingWithSuffixes"), plus the stored name itself so scraped data matches as-is. + +import { anchoredRegex, type LabelMatcher } from "@maple/promql" +import { Array as Arr, Option, pipe, String as Str } from "effect" + +export type OtelMetricType = "sum" | "gauge" | "histogram" | "exponential_histogram" + +export type MetricTable = + | "metrics_sum" + | "metrics_gauge" + | "metrics_histogram" + | "metrics_exponential_histogram" + +/** Which value of a stored metric a Prometheus name reads. */ +export type MetricComponent = "value" | "bucket" | "count" | "sum" + +export interface CatalogMetric { + readonly metricName: string + readonly metricType: OtelMetricType + readonly isMonotonic: boolean + readonly unit: string +} + +export interface PromNameTarget { + readonly table: MetricTable + /** The stored OTel name. */ + readonly metricName: string + readonly component: MetricComponent + readonly promName: string +} + +const TABLES = { + sum: "metrics_sum", + gauge: "metrics_gauge", + histogram: "metrics_histogram", + exponential_histogram: "metrics_exponential_histogram", +} satisfies Record + +export const tableOf = (type: OtelMetricType): MetricTable => TABLES[type] + +/** Replace characters outside `[a-zA-Z0-9_:]`, collapse and trim underscores, guard a leading digit. */ +export const normalizeMetricName = (name: string): string => { + const cleaned = pipe( + name, + Str.replace(/[^a-zA-Z0-9_:]/g, "_"), + Str.replace(/_+/g, "_"), + Str.replace(/^_+|_+$/g, ""), + ) + return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned +} + +const UNITS = new Map([ + ["d", "days"], + ["h", "hours"], + ["min", "minutes"], + ["s", "seconds"], + ["ms", "milliseconds"], + ["us", "microseconds"], + ["ns", "nanoseconds"], + ["By", "bytes"], + ["KiBy", "kibibytes"], + ["MiBy", "mebibytes"], + ["GiBy", "gibibytes"], + ["TiBy", "tebibytes"], + ["KBy", "kilobytes"], + ["MBy", "megabytes"], + ["GBy", "gigabytes"], + ["TBy", "terabytes"], + ["m", "meters"], + ["V", "volts"], + ["A", "amperes"], + ["J", "joules"], + ["W", "watts"], + ["g", "grams"], + ["Cel", "celsius"], + ["Hz", "hertz"], + ["%", "percent"], +]) + +const PER_UNITS = new Map([ + ["s", "second"], + ["m", "minute"], + ["h", "hour"], + ["d", "day"], + ["w", "week"], + ["mo", "month"], + ["y", "year"], +]) + +const unitTokens = (unit: string): ReadonlyArray => + Arr.filter(Str.split(normalizeMetricName(unit), "_"), (token) => token !== "") + +/** The unit's Prometheus suffix tokens: `{...}` annotations dropped, `x/y` as `x_per_y`. */ +export const unitSuffix = (unit: string, metricType: OtelMetricType): ReadonlyArray => { + const stripped = pipe(unit, Str.replace(/\{[^}]*\}/g, ""), Str.trim) + if (stripped === "1") return metricType === "gauge" ? ["ratio"] : [] + if (stripped === "") return [] + const [main, per] = Option.match(Str.indexOf("/")(stripped), { + onNone: () => [stripped, ""] as const, + onSome: (slash) => + [Str.trim(Str.slice(0, slash)(stripped)), Str.trim(Str.slice(slash + 1)(stripped))] as const, + }) + const mainTokens = main === "" || main === "1" ? [] : unitTokens(UNITS.get(main) ?? main) + const perTokens = per === "" ? [] : unitTokens(PER_UNITS.get(per) ?? per) + return perTokens.length === 0 ? mainTokens : [...mainTokens, "per", ...perTokens] +} + +/** Appends the suffix unless the name already holds it as whole tokens (`node_cpu_seconds_total`). */ +const withSuffix = (base: string, suffix: ReadonlyArray): string => { + if (suffix.length === 0) return base + const tail = Arr.join(suffix, "_") + return Str.includes(`_${tail}_`)(`_${base}_`) ? base : `${base}_${tail}` +} + +const withTotal = (base: string): string => withSuffix(Str.replace(/_total(?=_|$)/g, "")(base), ["total"]) + +const unique = (names: ReadonlyArray): ReadonlyArray => + Arr.dedupe(Arr.filter(names, (name) => name !== "")) + +/** The base names a stored metric answers to, the canonical (suffixed) one first. */ +const baseNames = (metric: CatalogMetric): ReadonlyArray => { + const normalized = normalizeMetricName(metric.metricName) + const withUnit = withSuffix(normalized, unitSuffix(metric.unit, metric.metricType)) + return unique([withUnit, normalized]) +} + +export interface PromName { + readonly promName: string + readonly component: MetricComponent +} + +/** Every Prometheus name of a stored metric, in preference order (canonical first, stored name last). */ +export const promNamesOf = (metric: CatalogMetric): ReadonlyArray => { + const bases = baseNames(metric) + switch (metric.metricType) { + case "sum": + case "gauge": { + const counter = metric.metricType === "sum" && metric.isMonotonic + const names = counter ? [...Arr.map(bases, withTotal), ...bases] : bases + return Arr.map(unique([...names, metric.metricName]), (promName) => ({ + promName, + component: "value", + })) + } + case "histogram": + case "exponential_histogram": { + const suffixed = (suffix: string, component: MetricComponent): ReadonlyArray => + Arr.map(bases, (base) => ({ promName: `${base}_${suffix}`, component })) + return [ + ...(metric.metricType === "histogram" ? suffixed("bucket", "bucket") : []), + ...suffixed("count", "count"), + ...suffixed("sum", "sum"), + ] + } + } +} + +const regexCache = new Map>() + +const regexOf = (pattern: string): Option.Option => { + const cached = regexCache.get(pattern) + if (cached !== undefined) return cached + const compiled = anchoredRegex(pattern) + if (regexCache.size > 512) regexCache.clear() + regexCache.set(pattern, compiled) + return compiled +} + +/** Prometheus matcher semantics on one value; regexes are fully anchored. */ +export const matchesValue = (matcher: LabelMatcher, value: string): boolean => { + switch (matcher.op) { + case "=": + return value === matcher.value + case "!=": + return value !== matcher.value + case "=~": + return Option.match(regexOf(matcher.value), { + onNone: () => false, + onSome: (re) => re.test(value), + }) + case "!~": + return Option.match(regexOf(matcher.value), { + onNone: () => true, + onSome: (re) => !re.test(value), + }) + } +} + +/** + * The stored metrics a selector's `__name__` matchers select. Each stored metric and component + * answers to one name: the first of its names, in preference order, that every matcher accepts. + */ +export const resolveSelectorName = ( + nameMatchers: ReadonlyArray, + catalog: ReadonlyArray, +): ReadonlyArray => + Arr.flatMap(catalog, (metric) => { + const picked = new Map() + for (const { promName, component } of promNamesOf(metric)) { + if (picked.has(component)) continue + if (Arr.every(nameMatchers, (m) => matchesValue(m, promName))) picked.set(component, promName) + } + return Arr.map([...picked], ([component, promName]) => ({ + table: tableOf(metric.metricType), + metricName: metric.metricName, + component, + promName, + })) + }) diff --git a/packages/query-engine/src/promql/source.ts b/packages/query-engine/src/promql/source.ts new file mode 100644 index 0000000000..a6e1a0df20 --- /dev/null +++ b/packages/query-engine/src/promql/source.ts @@ -0,0 +1,199 @@ +// The Maple source for the PromQL evaluator: a selector request becomes one warehouse query per +// (table, component) of the stored metrics its name resolves to, and their rows become SelectorData. +// Pure: the caller runs the compiled queries. + +import type { LabelMatcher, SampleBucket, SelectorData, SelectorRequest, SeriesData } from "@maple/promql" +import { Array as Arr, Order } from "effect" +import { compile } from "@maple-dev/effect-orm/clickhouse" +import type { OrgId } from "@maple/primitives" +import { + type PromqlCatalogRow, + type PromqlSelectorRow, + promqlCatalogQuery, + promqlSelectorQuery, +} from "../ch/queries/promql" +import { matchesAll, matcherCondition, seriesLabels } from "./labels" +import { + type CatalogMetric, + type MetricComponent, + type MetricTable, + type OtelMetricType, + type PromNameTarget, + resolveSelectorName, +} from "./names" + +export interface SelectorPlanOptions { + readonly orgId: OrgId + /** The evaluator's series cap; each query returns at most one more so overflow shows. */ + readonly maxSeries: number +} + +export interface SelectorPlan { + readonly table: MetricTable + readonly component: MetricComponent + /** Stored name to the Prometheus name its series carry. */ + readonly promNames: ReadonlyMap + readonly compiled: ReturnType +} + +const compileSelector = ( + request: SelectorRequest, + group: { + readonly table: MetricTable + readonly component: MetricComponent + readonly metricNames: ReadonlyArray + }, + options: SelectorPlanOptions, +) => { + const labelMatchers = Arr.filter(request.matchers, (m) => m.name !== "__name__") + return compile( + promqlSelectorQuery({ + table: group.table, + component: group.component, + metricNames: group.metricNames, + widthMs: request.widthMs, + needsValues: request.needsValues, + limit: options.maxSeries + 1, + conditions: ($) => Arr.map(labelMatchers, (m) => matcherCondition($, m)), + }), + { + orgId: options.orgId, + startMs: request.startMs, + endMs: request.endMs, + originMs: request.originMs, + timeOriginMs: request.startMs, + }, + ) +} + +const nameMatchersOf = (request: SelectorRequest): ReadonlyArray => + Arr.filter(request.matchers, (m) => m.name === "__name__") + +/** The targets of a request, grouped by the table and component one query reads. */ +export const groupTargets = ( + targets: ReadonlyArray, +): ReadonlyArray<{ + readonly table: MetricTable + readonly component: MetricComponent + readonly targets: ReadonlyArray +}> => { + const groups = new Map< + string, + { table: MetricTable; component: MetricComponent; targets: PromNameTarget[] } + >() + for (const target of targets) { + const key = `${target.table}/${target.component}` + const group = groups.get(key) + if (group === undefined) + groups.set(key, { table: target.table, component: target.component, targets: [target] }) + else group.targets.push(target) + } + return [...groups.values()] +} + +/** One compiled query per (table, component) the selector's name resolves to; none when nothing matches. */ +export const buildSelectorQueries = ( + request: SelectorRequest, + catalog: ReadonlyArray, + options: SelectorPlanOptions, +): ReadonlyArray => + Arr.map(groupTargets(resolveSelectorName(nameMatchersOf(request), catalog)), (group) => { + const promNames = new Map(Arr.map(group.targets, (t) => [t.metricName, t.promName] as const)) + return { + table: group.table, + component: group.component, + promNames, + compiled: compileSelector(request, { ...group, metricNames: [...promNames.keys()] }, options), + } + }) + +/** ClickHouse prints the bucket bound with `toString`: `inf` for +Inf. */ +export const parseLe = (text: string): number => { + if (text === "inf" || text === "+inf") return Infinity + if (text === "-inf") return -Infinity + return Number(text) +} + +const bucketsOf = (row: PromqlSelectorRow, needsValues: boolean): ReadonlyArray => { + const at = (values: ReadonlyArray, i: number) => values[i] ?? 0 + const buckets = Arr.map(row.end, (end, i): SampleBucket => { + const bucket: SampleBucket = { + end, + firstT: at(row.firstT, i), + firstV: at(row.firstV, i), + lastT: at(row.lastT, i), + lastV: at(row.lastV, i), + prevT: at(row.prevT, i), + prevV: at(row.prevV, i), + count: at(row.count, i), + sum: at(row.sum, i), + min: at(row.min, i), + max: at(row.max, i), + sumSquares: at(row.sumSquares, i), + increase: at(row.increase, i), + resets: at(row.resets, i), + changes: at(row.changes, i), + sumT: at(row.sumT, i), + sumTT: at(row.sumTT, i), + sumTV: at(row.sumTV, i), + } + return needsValues ? { ...bucket, values: row.values[i] ?? [] } : bucket + }) + return Arr.sort( + buckets, + Order.mapInput(Order.Number, (b: SampleBucket) => b.end), + ) +} + +/** + * The rows of every plan as the evaluator's SelectorData. Labels are recomputed and every matcher + * re-checked here; series whose label sets collide are all returned (the evaluator reports them). + */ +export const toSelectorData = ( + request: SelectorRequest, + results: ReadonlyArray<{ readonly plan: SelectorPlan; readonly rows: ReadonlyArray }>, +): SelectorData => ({ + timeOriginMs: request.startMs, + series: Arr.flatMap(results, ({ plan, rows }) => + Arr.flatMap(rows, (row): ReadonlyArray => { + const promName = plan.promNames.get(row.metricName) + if (promName === undefined) return [] + const labels = seriesLabels({ + promName, + serviceName: row.serviceName, + attributes: row.attributes, + resourceAttributes: row.resourceAttributes, + le: plan.component === "bucket" ? parseLe(row.le) : undefined, + }) + if (!matchesAll(labels, request.matchers)) return [] + const buckets = bucketsOf(row, request.needsValues) + return buckets.length === 0 ? [] : [{ labels, buckets }] + }), + ), +}) + +const METRIC_TYPES: ReadonlySet = new Set([ + "sum", + "gauge", + "histogram", + "exponential_histogram", +]) + +const isMetricType = (value: string): value is OtelMetricType => METRIC_TYPES.has(value) + +/** The catalog query over `[startTime, endTime]`; feed its rows to `catalogFromRows`. */ +export const catalogQuery = (limit = 50_000) => promqlCatalogQuery({ limit }) + +export const catalogFromRows = (rows: ReadonlyArray): ReadonlyArray => + Arr.flatMap(rows, (row) => + isMetricType(row.metricType) + ? [ + { + metricName: row.metricName, + metricType: row.metricType, + isMonotonic: row.isMonotonic > 0, + unit: row.unit, + }, + ] + : [], + ) From 468c8ea4c5844dab333acc1029b1ca785dec2f0e Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 15:34:30 +0100 Subject: [PATCH 2/7] fix(promql): one series across a deploy, and bounded selector reads The series key hashed every resource attribute, but the labels drop service.*, telemetry.* and maple* keys. A deploy that changed service.version split one counter into two series with the same labels, and rate() over the deploy failed with a duplicate labelset. The key now hashes exactly what the labels are built from. Pushed-down regexes are anchored as ^(?s:...)$, the way Prometheus and the evaluator's RE2 anchor them. A selector may resolve to at most 100 stored metrics, the catalog read fails instead of truncating past 50,000 metrics, and resolution limits run before anything is read. --- apps/cli/test/promql-source.test.ts | 20 +++++++++++ .../promql/PromqlQueryService.test.ts | 34 +++++++++++++++++++ .../src/services/promql/PromqlQueryService.ts | 25 ++++++++++++-- .../query-engine/src/ch/queries/promql.ts | 9 +++-- packages/query-engine/src/promql/labels.ts | 6 ++-- packages/query-engine/src/promql/names.ts | 6 ++-- 6 files changed, 91 insertions(+), 9 deletions(-) diff --git a/apps/cli/test/promql-source.test.ts b/apps/cli/test/promql-source.test.ts index 47beafad72..5db10cc852 100644 --- a/apps/cli/test/promql-source.test.ts +++ b/apps/cli/test/promql-source.test.ts @@ -527,4 +527,24 @@ describeWithChdb("PromQL selector source", () => { test("a query returns one series past the cap so overflow shows", () => { expect(select(db, ORG_A, request("requests_total"), 1).series).toHaveLength(2) }) + + test("a deploy that changes service.version keeps one series", () => { + // Inside the request window (BASE, BASE + 5m]; the start is exclusive. + const samples = Arr.map(every(15 * SECOND_MS, 5 * MINUTE_MS, 15 * SECOND_MS), (t, k): Sample => [ + t, + 3 * k, + ]) + const half = Math.floor(samples.length / 2) + const deployed = (version: string, part: ReadonlyArray): SumSeries => ({ + ...counterA, + metric: "deploys", + resource: { ...RESOURCE, "service.version": version, "telemetry.sdk.version": version }, + samples: part, + }) + insertValues(db, deployed("1.0", Arr.take(samples, half))) + insertValues(db, deployed("2.0", Arr.drop(samples, half))) + const series = select(db, ORG_A, request("deploys_total")).series + expect(series).toHaveLength(1) + expect(total(Arr.flatMap(series, (s) => Arr.map(s.buckets, (b) => b.count)))).toBe(samples.length) + }) }) diff --git a/packages/backend/src/services/promql/PromqlQueryService.test.ts b/packages/backend/src/services/promql/PromqlQueryService.test.ts index 0dfe6eb675..ade64ce4e0 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.test.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.test.ts @@ -68,4 +68,38 @@ describe("PromqlQueryService", () => { expect(error._tag).toBe("@maple/backend/promql/PromqlExecutionError") }), ) + + const withCatalog = (rows: ReadonlyArray>) => + Layer.effect(PromqlQueryService, PromqlQueryService.make).pipe( + Layer.provide( + Layer.succeed( + WarehouseQueryService, + makeWarehouseServiceStub({ compiledQuery: () => Effect.succeed(rows) }), + ), + ), + ) + + const errorWith = (rows: ReadonlyArray>, query: string) => + Effect.gen(function* () { + const service = yield* PromqlQueryService + return yield* Effect.flip(service.query(tenant, { query, startMs: 0, endMs: 0, stepMs: 0 })) + }).pipe(Effect.provide(withCatalog(rows))) + + const gauge = (i: number) => ({ metricName: `m_${i}`, metricType: "gauge", unit: "", isMonotonic: 0 }) + + it.effect("refuses a selector that matches more than 100 metrics", () => + Effect.gen(function* () { + const rows = Array.from({ length: 101 }, (_, i) => gauge(i)) + const error = yield* errorWith(rows, '{__name__=~"m_.*"}') + expect(error.message).toMatch(/matches 101 metrics, at most 100/) + }), + ) + + it.effect("refuses to resolve names against a catalog that was cut off", () => + Effect.gen(function* () { + const rows = Array.from({ length: 50_001 }, (_, i) => gauge(i)) + const error = yield* errorWith(rows, "m_1") + expect(error.message).toMatch(/more than 50000 metrics/) + }), + ) }) diff --git a/packages/backend/src/services/promql/PromqlQueryService.ts b/packages/backend/src/services/promql/PromqlQueryService.ts index 2756176cfe..b06c8d5a4d 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -13,6 +13,7 @@ import { parse, planRequests, type QueryParams, + resolutionError, type QueryResult, type SelectorData, type SelectorRequest, @@ -32,7 +33,7 @@ import { WarehouseQueryService } from "@maple/backend/services/warehouse/Warehou /** The query is not valid PromQL, or its parameters are out of range. Prometheus' `bad_data`. */ export class PromqlBadQueryError extends Schema.TaggedError()( "@maple/backend/promql/PromqlBadQueryError", - { message: Schema.String, position: Schema.optional(Schema.Number) }, + { message: Schema.String, position: Schema.optionalKey(Schema.Number) }, ) {} /** The query is valid but cannot be evaluated: limits, many-to-many matching. Prometheus' `execution`. */ @@ -49,6 +50,12 @@ const MAX_SELECTORS = 20 const WAREHOUSE_CONCURRENCY = 4 +/** Stored metrics one selector may read; `{__name__=~".+"}` would otherwise read them all. */ +const MAX_METRICS_PER_SELECTOR = 100 + +/** Catalog rows read to resolve names; one more comes back when the org has more. */ +const CATALOG_LIMIT = 50_000 + export interface PromqlQuery extends QueryParams { readonly query: string } @@ -94,7 +101,7 @@ const make = Effect.gen(function* () { tenant: TenantContext, window: { readonly startMs: number; readonly endMs: number }, ) { - const compiled = CH.compile(catalogQuery(), { + const compiled = CH.compile(catalogQuery(CATALOG_LIMIT + 1), { orgId: tenant.orgId, startTime: formatWarehouseDateTime(window.startMs), endTime: formatWarehouseDateTime(window.endMs), @@ -103,6 +110,12 @@ const make = Effect.gen(function* () { profile: "discovery", context: "promqlCatalog", }) + if (rows.length > CATALOG_LIMIT) { + // A cut catalog would silently drop names; refuse instead. + return yield* new PromqlExecutionError({ + message: `this organization has more than ${CATALOG_LIMIT} metrics in the range; shorten the range`, + }) + } return catalogFromRows(rows) }) @@ -115,6 +128,12 @@ const make = Effect.gen(function* () { orgId: tenant.orgId, maxSeries: DEFAULT_LIMITS.maxSeries, }) + const metrics = Arr.reduce(plans, 0, (n, plan) => n + plan.promNames.size) + if (metrics > MAX_METRICS_PER_SELECTOR) { + return yield* new PromqlExecutionError({ + message: `a selector matches ${metrics} metrics, at most ${MAX_METRICS_PER_SELECTOR}; narrow its __name__ matcher`, + }) + } yield* Effect.annotateCurrentSpan({ "maple.promql.metric": request.metricName ?? "", "maple.promql.bucket_ms": request.widthMs, @@ -145,6 +164,8 @@ const make = Effect.gen(function* () { "maple.promql.step_ms": input.stepMs, }) const expr = yield* validate(input) + const resolution = resolutionError(expr, input) + if (resolution !== undefined) return yield* new PromqlBadQueryError({ message: resolution }) const plan = planRequests(expr, input) const entries = [...plan.entries()] if (entries.length > MAX_SELECTORS) { diff --git a/packages/query-engine/src/ch/queries/promql.ts b/packages/query-engine/src/ch/queries/promql.ts index efea4edd0d..08d7e3b373 100644 --- a/packages/query-engine/src/ch/queries/promql.ts +++ b/packages/query-engine/src/ch/queries/promql.ts @@ -12,6 +12,7 @@ import * as CH from "@maple-dev/effect-orm/expr" import { CHNumber } from "../schema" import * as Datasources from "@maple/domain/tinybird/datasources" import { orgId, orgIdParam, utcSecondsParam } from "../tables" +import { EXCLUDED_KEY } from "../../promql/labels" export type PromqlMetricTable = | "metrics_sum" @@ -122,12 +123,16 @@ const scanQuery = (opts: PromqlSelectorOpts) => ...opts.conditions($), ]) -/** The series key: the stored identity of the series, plus the bound for a bucket. */ +/** + * The series key: everything the series' labels are built from, and nothing else. A resource + * key the labels drop (service.version, telemetry.sdk.*) must not split a series, or a deploy + * turns one counter into two with the same labels. + */ const keyedQuery = (opts: PromqlSelectorOpts) => fromQuery(scanQuery(opts), "scan").select(($) => ({ sk: sql( T.uint64, - )`cityHash64(${$.MetricName}, ${$.ServiceName}, mapKeys(${$.Attributes}), mapValues(${$.Attributes}), mapKeys(${$.ResourceAttributes}), mapValues(${$.ResourceAttributes}), ${$.pair}[1])`, + )`cityHash64(${$.MetricName}, ${$.ServiceName}, mapKeys(${$.Attributes}), mapValues(${$.Attributes}), mapKeys(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes})), mapValues(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes})), ${$.ResourceAttributes}['service.name'], ${$.ResourceAttributes}['service.namespace'], ${$.ResourceAttributes}['service.instance.id'], ${$.pair}[1])`, MetricName: $.MetricName, ServiceName: $.ServiceName, Attributes: $.Attributes, diff --git a/packages/query-engine/src/promql/labels.ts b/packages/query-engine/src/promql/labels.ts index 78f411a265..1164fe0629 100644 --- a/packages/query-engine/src/promql/labels.ts +++ b/packages/query-engine/src/promql/labels.ts @@ -107,7 +107,8 @@ const NORMALIZED_KEY = sql.raw( "concat(if(match(_k, '^[0-9]'), '_', ''), replaceRegexpAll(replaceRegexpAll(_k, '[^a-zA-Z0-9_]', '_'), '_+', '_'))", ) -const EXCLUDED_KEY = sql.raw( +/** Whether resource key `_k` is left out of the labels, in ClickHouse. */ +export const EXCLUDED_KEY = sql.raw( `(${Arr.join( Arr.map(EXCLUDED_RESOURCE_PREFIXES, (prefix) => `startsWith(_k, '${prefix}')`), " OR ", @@ -155,7 +156,8 @@ export const labelValueExpr = ($: LabelColumns, name: string): CH.Expr | export const matcherCondition = ($: LabelColumns, matcher: LabelMatcher): CH.Condition | undefined => { const value = labelValueExpr($, matcher.name) if (value === undefined) return undefined - const pattern = `^(?:${matcher.value})$` + // The anchoring Prometheus uses; ClickHouse's `match` is RE2 like Prometheus'. + const pattern = `^(?s:${matcher.value})$` switch (matcher.op) { case "=": return sql.cond`${value} = ${matcher.value}` diff --git a/packages/query-engine/src/promql/names.ts b/packages/query-engine/src/promql/names.ts index 6cba9d91da..3308d46732 100644 --- a/packages/query-engine/src/promql/names.ts +++ b/packages/query-engine/src/promql/names.ts @@ -1,7 +1,7 @@ // Prometheus names for OTel metrics, after the OpenTelemetry-to-Prometheus translation // ("UnderscoreEscapingWithSuffixes"), plus the stored name itself so scraped data matches as-is. -import { anchoredRegex, type LabelMatcher } from "@maple/promql" +import { anchoredRegex, type LabelMatcher, type LabelRegex } from "@maple/promql" import { Array as Arr, Option, pipe, String as Str } from "effect" export type OtelMetricType = "sum" | "gauge" | "histogram" | "exponential_histogram" @@ -156,9 +156,9 @@ export const promNamesOf = (metric: CatalogMetric): ReadonlyArray => { } } -const regexCache = new Map>() +const regexCache = new Map>() -const regexOf = (pattern: string): Option.Option => { +const regexOf = (pattern: string): Option.Option => { const cached = regexCache.get(pattern) if (cached !== undefined) return cached const compiled = anchoredRegex(pattern) From e8941d3dee75d454b79f3668df68345ad1c8389c Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 15:59:55 +0100 Subject: [PATCH 3/7] fix(promql): one name in two units is two metrics, attribute order never splits a series The catalog took one arbitrary unit per metric name, so a name exported in ms by one service and in s by another answered to one Prometheus name with mixed values. Names now resolve per (name, unit) and the scan reads only the resolved pairs: request_duration_seconds and request_duration_milliseconds are separate metrics. The series key hashes sorted attribute maps, so an exporter reordering attributes keeps one series. A selector read that hit its row limit fails instead of returning what survived the le check after the limit. --- apps/cli/test/promql-source.test.ts | 46 +++++++++++++++++++ .../src/services/promql/PromqlQueryService.ts | 6 +++ .../query-engine/src/ch/queries/promql.ts | 28 +++++++---- packages/query-engine/src/promql/names.ts | 3 ++ packages/query-engine/src/promql/source.ts | 13 ++++-- 5 files changed, 83 insertions(+), 13 deletions(-) diff --git a/apps/cli/test/promql-source.test.ts b/apps/cli/test/promql-source.test.ts index 5db10cc852..2ee7f28851 100644 --- a/apps/cli/test/promql-source.test.ts +++ b/apps/cli/test/promql-source.test.ts @@ -547,4 +547,50 @@ describeWithChdb("PromQL selector source", () => { expect(series).toHaveLength(1) expect(total(Arr.flatMap(series, (s) => Arr.map(s.buckets, (b) => b.count)))).toBe(samples.length) }) + + test("one name stored in two units reads as two metrics", () => { + const exports = Arr.map(every(15 * SECOND_MS, MINUTE_MS, 15 * SECOND_MS), (t): Sample => [t, 1]) + const gaugeIn = (service: string, unit: string, value: number): SumSeries => ({ + ...gauge, + metric: "request.duration", + unit, + attributes: {}, + resource: { ...RESOURCE, "service.name": service }, + samples: Arr.map(exports, ([t]): Sample => [t, value]), + }) + insertValues(db, gaugeIn("seconds-svc", "s", 0.2)) + insertValues(db, gaugeIn("millis-svc", "ms", 200)) + const seconds = select(db, ORG_A, request("request_duration_seconds")).series + const millis = select(db, ORG_A, request("request_duration_milliseconds")).series + expect(Arr.map(seconds, (s) => s.labels.job)).toEqual(["seconds-svc"]) + expect(Arr.map(millis, (s) => s.labels.job)).toEqual(["millis-svc"]) + }) + + test("attribute order does not split a series", () => { + const times = every(15 * SECOND_MS, 2 * MINUTE_MS, 15 * SECOND_MS) + const ordered = ( + attributes: Readonly>, + part: ReadonlyArray, + ): SumSeries => ({ + ...counterA, + metric: "ordered", + attributes, + samples: Arr.map(part, (t, k): Sample => [t, k]), + }) + insertValues( + db, + ordered( + { route: "/a", method: "GET" }, + Arr.filter(times, (_t, i) => i % 2 === 0), + ), + ) + insertValues( + db, + ordered( + { method: "GET", route: "/a" }, + Arr.filter(times, (_t, i) => i % 2 === 1), + ), + ) + expect(select(db, ORG_A, request("ordered_total")).series).toHaveLength(1) + }) }) diff --git a/packages/backend/src/services/promql/PromqlQueryService.ts b/packages/backend/src/services/promql/PromqlQueryService.ts index b06c8d5a4d..3c17ccdf7e 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -151,6 +151,12 @@ const make = Effect.gen(function* () { ), { concurrency: WAREHOUSE_CONCURRENCY }, ) + // A query that hit its LIMIT was cut before the `le` check after it; refuse a partial answer. + if (Arr.some(results, ({ rows }) => rows.length > DEFAULT_LIMITS.maxSeries)) { + return yield* new PromqlExecutionError({ + message: `query selects more than ${DEFAULT_LIMITS.maxSeries} series; narrow the selector`, + }) + } return toSelectorData(request, results) }) diff --git a/packages/query-engine/src/ch/queries/promql.ts b/packages/query-engine/src/ch/queries/promql.ts index 08d7e3b373..426d0ce2c1 100644 --- a/packages/query-engine/src/ch/queries/promql.ts +++ b/packages/query-engine/src/ch/queries/promql.ts @@ -5,7 +5,7 @@ // accumulated into counters); previous sample per series; per (series, bucket) statistics; // one row per series with the bucket statistics as parallel arrays. -import { Schema } from "effect" +import { Array as Arr, Schema } from "effect" import * as T from "@maple-dev/effect-orm/clickhouse" import { from, fromQuery, param, sql, table } from "@maple-dev/effect-orm/clickhouse" import * as CH from "@maple-dev/effect-orm/expr" @@ -14,6 +14,9 @@ import * as Datasources from "@maple/domain/tinybird/datasources" import { orgId, orgIdParam, utcSecondsParam } from "../tables" import { EXCLUDED_KEY } from "../../promql/labels" +/** Joins a stored metric's name and unit into the identity a selector row reports. */ +export const METRIC_UNIT_SEPARATOR = "\u001f" + export type PromqlMetricTable = | "metrics_sum" | "metrics_gauge" @@ -32,8 +35,8 @@ export interface PromqlLabelColumns { export interface PromqlSelectorOpts { readonly table: PromqlMetricTable readonly component: PromqlComponent - /** Stored OTel metric names; one query reads them all. */ - readonly metricNames: ReadonlyArray + /** Stored (OTel name, unit) pairs; one query reads them all. */ + readonly targets: ReadonlyArray<{ readonly metricName: string; readonly unit: string }> /** 0: one bucket per sample. */ readonly widthMs: number /** Also return each bucket's values in time order (raw mode). */ @@ -61,6 +64,7 @@ const metricTable = (name: PromqlMetricTable) => columns: { OrgId: orgId, MetricName: T.string, + MetricUnit: T.string, ServiceName: T.string, Attributes: stringMap, ResourceAttributes: stringMap, @@ -104,7 +108,8 @@ const finiteSampleCond = (component: PromqlComponent) => { const scanQuery = (opts: PromqlSelectorOpts) => from(metricTable(opts.table)) .select(($) => ({ - MetricName: $.MetricName, + // Name and unit together: one name in two units is two metrics (`_seconds`, `_milliseconds`). + MetricName: sql(T.string)`concat(${$.MetricName}, ${METRIC_UNIT_SEPARATOR}, ${$.MetricUnit})`, ServiceName: $.ServiceName, Attributes: $.Attributes, ResourceAttributes: $.ResourceAttributes, @@ -114,7 +119,11 @@ const scanQuery = (opts: PromqlSelectorOpts) => })) .where(($) => [ $.OrgId.eq(orgIdParam), - $.MetricName.in_(...opts.metricNames), + $.MetricName.in_(...Arr.dedupe(Arr.map(opts.targets, (t) => t.metricName))), + sql.cond`(${$.MetricName}, ${$.MetricUnit}) IN (${sql.join( + Arr.map(opts.targets, (t) => sql`(${t.metricName}, ${t.unit})`), + ", ", + )})`, sql.cond`${$.TimeUnix} > fromUnixTimestamp64Milli(toInt64(${param.int("startMs")}))`, sql.cond`${$.TimeUnix} <= fromUnixTimestamp64Milli(toInt64(${param.int("endMs")}))`, // A no-recorded-value point (a failed scrape) is not a sample. @@ -124,7 +133,8 @@ const scanQuery = (opts: PromqlSelectorOpts) => ]) /** - * The series key: everything the series' labels are built from, and nothing else. A resource + * The series key: everything the series' labels are built from, maps sorted so attribute order + * does not matter, and nothing else. A resource * key the labels drop (service.version, telemetry.sdk.*) must not split a series, or a deploy * turns one counter into two with the same labels. */ @@ -132,7 +142,7 @@ const keyedQuery = (opts: PromqlSelectorOpts) => fromQuery(scanQuery(opts), "scan").select(($) => ({ sk: sql( T.uint64, - )`cityHash64(${$.MetricName}, ${$.ServiceName}, mapKeys(${$.Attributes}), mapValues(${$.Attributes}), mapKeys(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes})), mapValues(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes})), ${$.ResourceAttributes}['service.name'], ${$.ResourceAttributes}['service.namespace'], ${$.ResourceAttributes}['service.instance.id'], ${$.pair}[1])`, + )`cityHash64(${$.MetricName}, ${$.ServiceName}, mapKeys(mapSort(${$.Attributes})), mapValues(mapSort(${$.Attributes})), mapKeys(mapSort(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes}))), mapValues(mapSort(mapFilter((_k, _v) -> NOT ${EXCLUDED_KEY}, ${$.ResourceAttributes}))), ${$.ResourceAttributes}['service.name'], ${$.ResourceAttributes}['service.namespace'], ${$.ResourceAttributes}['service.instance.id'], ${$.pair}[1])`, MetricName: $.MetricName, ServiceName: $.ServiceName, Attributes: $.Attributes, @@ -347,7 +357,7 @@ export function promqlCatalogQuery(opts: { readonly limit: number }) { .select(($) => ({ metricName: $.MetricName, metricType: $.MetricType, - unit: CH.any_($.MetricUnit), + unit: $.MetricUnit, isMonotonic: sql(T.uint8)`max(${$.IsMonotonic})`, })) .where(($) => [ @@ -355,7 +365,7 @@ export function promqlCatalogQuery(opts: { readonly limit: number }) { $.Hour.gte(CH.toStartOfInterval(CH.toDateTime(utcSecondsParam("startTime")), 3600)), $.Hour.lte(utcSecondsParam("endTime")), ]) - .groupBy("metricName", "metricType") + .groupBy("metricName", "metricType", "unit") .limit(opts.limit) .format("JSON") } diff --git a/packages/query-engine/src/promql/names.ts b/packages/query-engine/src/promql/names.ts index 3308d46732..fae5134e09 100644 --- a/packages/query-engine/src/promql/names.ts +++ b/packages/query-engine/src/promql/names.ts @@ -28,6 +28,8 @@ export interface PromNameTarget { readonly metricName: string readonly component: MetricComponent readonly promName: string + /** The stored unit: one name may be stored in two units, which are two metrics. */ + readonly unit: string } const TABLES = { @@ -206,5 +208,6 @@ export const resolveSelectorName = ( metricName: metric.metricName, component, promName, + unit: metric.unit, })) }) diff --git a/packages/query-engine/src/promql/source.ts b/packages/query-engine/src/promql/source.ts index a6e1a0df20..ec8669c52a 100644 --- a/packages/query-engine/src/promql/source.ts +++ b/packages/query-engine/src/promql/source.ts @@ -7,6 +7,7 @@ import { Array as Arr, Order } from "effect" import { compile } from "@maple-dev/effect-orm/clickhouse" import type { OrgId } from "@maple/primitives" import { + METRIC_UNIT_SEPARATOR, type PromqlCatalogRow, type PromqlSelectorRow, promqlCatalogQuery, @@ -41,7 +42,7 @@ const compileSelector = ( group: { readonly table: MetricTable readonly component: MetricComponent - readonly metricNames: ReadonlyArray + readonly targets: ReadonlyArray }, options: SelectorPlanOptions, ) => { @@ -50,7 +51,7 @@ const compileSelector = ( promqlSelectorQuery({ table: group.table, component: group.component, - metricNames: group.metricNames, + targets: group.targets, widthMs: request.widthMs, needsValues: request.needsValues, limit: options.maxSeries + 1, @@ -66,6 +67,10 @@ const compileSelector = ( ) } +/** The identity a selector row reports for a target: its stored name and unit. */ +const targetKey = (target: Pick): string => + `${target.metricName}${METRIC_UNIT_SEPARATOR}${target.unit}` + const nameMatchersOf = (request: SelectorRequest): ReadonlyArray => Arr.filter(request.matchers, (m) => m.name === "__name__") @@ -98,12 +103,12 @@ export const buildSelectorQueries = ( options: SelectorPlanOptions, ): ReadonlyArray => Arr.map(groupTargets(resolveSelectorName(nameMatchersOf(request), catalog)), (group) => { - const promNames = new Map(Arr.map(group.targets, (t) => [t.metricName, t.promName] as const)) + const promNames = new Map(Arr.map(group.targets, (t) => [targetKey(t), t.promName] as const)) return { table: group.table, component: group.component, promNames, - compiled: compileSelector(request, { ...group, metricNames: [...promNames.keys()] }, options), + compiled: compileSelector(request, group, options), } }) From ca528ef6a868b72a0483fb35cf6c83baa8a2200e Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 17:07:08 +0100 Subject: [PATCH 4/7] fix(promql): keep the query text out of span attributes Matcher values can carry user identifiers; record the query length instead. The selector and metric attributes already identify the read. --- packages/backend/src/services/promql/PromqlQueryService.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/backend/src/services/promql/PromqlQueryService.ts b/packages/backend/src/services/promql/PromqlQueryService.ts index 3c17ccdf7e..8af99b2a9c 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -165,7 +165,7 @@ const make = Effect.gen(function* () { input: PromqlQuery, ) { yield* Effect.annotateCurrentSpan({ - "maple.promql.query": input.query, + "maple.promql.query_length": input.query.length, "maple.promql.range_ms": input.endMs - input.startMs, "maple.promql.step_ms": input.stepMs, }) From 4dff062a81480cbac76577f6cca95fb0a66295ed Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 17:32:41 +0100 Subject: [PATCH 5/7] fix(promql): series matchers read own labels only --- .../query-engine/src/promql/labels.test.ts | 23 ++++++++++++++++++- packages/query-engine/src/promql/labels.ts | 20 ++++++++++------ 2 files changed, 35 insertions(+), 8 deletions(-) diff --git a/packages/query-engine/src/promql/labels.test.ts b/packages/query-engine/src/promql/labels.test.ts index 4ad73b65a4..6eac5c971b 100644 --- a/packages/query-engine/src/promql/labels.test.ts +++ b/packages/query-engine/src/promql/labels.test.ts @@ -1,5 +1,12 @@ import { describe, expect, it } from "vitest" -import { formatLe, labelValue, normalizeLabelName, seriesLabels, type StoredSeries } from "./labels" +import { + formatLe, + labelValue, + matchesAll, + normalizeLabelName, + seriesLabels, + type StoredSeries, +} from "./labels" const row = (overrides: Partial = {}): StoredSeries => ({ promName: "http_server_request_duration_seconds_bucket", @@ -89,3 +96,17 @@ describe("seriesLabels", () => { expect(labels).not.toHaveProperty("process_command_line") }) }) + +describe("prototype-named labels", () => { + it("reads an attribute called constructor as its own string value", () => { + const labels = seriesLabels(row({ attributes: { constructor: "x" } })) + expect(Object.hasOwn(labels, "constructor") && labels.constructor).toBe("x") + expect(matchesAll(labels, [{ name: "constructor", op: "=", value: "x" }])).toBe(true) + }) + + it("matches a label named like an Object member as missing", () => { + const labels = seriesLabels(row()) + expect(matchesAll(labels, [{ name: "constructor", op: "=", value: "" }])).toBe(true) + expect(matchesAll(labels, [{ name: "toString", op: "!=", value: "" }])).toBe(false) + }) +}) diff --git a/packages/query-engine/src/promql/labels.ts b/packages/query-engine/src/promql/labels.ts index 1164fe0629..98c871c616 100644 --- a/packages/query-engine/src/promql/labels.ts +++ b/packages/query-engine/src/promql/labels.ts @@ -83,17 +83,23 @@ export const seriesLabels = (row: StoredSeries): Readonly for (const key of Rec.keys(row.resourceAttributes)) { if (notExcluded(key)) names.add(normalizeLabelName(key)) } - const labels: Record = {} - for (const name of [...names].sort()) { - const value = labelValue(row, name) - if (value !== "") labels[name] = value - } - return labels + // fromEntries defines own properties, so a label called __proto__ stays a label. + return Object.fromEntries( + Arr.filter( + Arr.map([...names].sort(), (name) => [name, labelValue(row, name)] as const), + ([, value]) => value !== "", + ), + ) } /** Whether a series' labels satisfy every matcher (a missing label is `""`). */ export const matchesAll = (labels: Readonly>, matchers: ReadonlyArray) => - Arr.every(matchers, (m) => matchesValue(m, labels[m.name] ?? "")) + Arr.every(matchers, (m) => + matchesValue( + m, + Option.getOrElse(Rec.get(labels, m.name), () => ""), + ), + ) /** The columns a label value reads. */ export interface LabelColumns { From d40f9eafbaea044792229e5b7e75a9f507514858 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 17:33:01 +0100 Subject: [PATCH 6/7] chore(promql): Record helpers for own-key label reads --- packages/query-engine/src/promql/labels.test.ts | 3 ++- packages/query-engine/src/promql/labels.ts | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/query-engine/src/promql/labels.test.ts b/packages/query-engine/src/promql/labels.test.ts index 6eac5c971b..089aa58c93 100644 --- a/packages/query-engine/src/promql/labels.test.ts +++ b/packages/query-engine/src/promql/labels.test.ts @@ -1,3 +1,4 @@ +import { Option, Record as Rec } from "effect" import { describe, expect, it } from "vitest" import { formatLe, @@ -100,7 +101,7 @@ describe("seriesLabels", () => { describe("prototype-named labels", () => { it("reads an attribute called constructor as its own string value", () => { const labels = seriesLabels(row({ attributes: { constructor: "x" } })) - expect(Object.hasOwn(labels, "constructor") && labels.constructor).toBe("x") + expect(Rec.get(labels, "constructor")).toEqual(Option.some("x")) expect(matchesAll(labels, [{ name: "constructor", op: "=", value: "x" }])).toBe(true) }) diff --git a/packages/query-engine/src/promql/labels.ts b/packages/query-engine/src/promql/labels.ts index 98c871c616..295c460a81 100644 --- a/packages/query-engine/src/promql/labels.ts +++ b/packages/query-engine/src/promql/labels.ts @@ -84,7 +84,7 @@ export const seriesLabels = (row: StoredSeries): Readonly if (notExcluded(key)) names.add(normalizeLabelName(key)) } // fromEntries defines own properties, so a label called __proto__ stays a label. - return Object.fromEntries( + return Rec.fromEntries( Arr.filter( Arr.map([...names].sort(), (name) => [name, labelValue(row, name)] as const), ([, value]) => value !== "", From a448666703421a07fd38e25fdd1c25643a5b4c51 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sun, 15 Nov 2026 18:24:35 +0100 Subject: [PATCH 7/7] fix(promql): metric tables declare their tenant column Without it the OrgId filter did not count, every selector read compiled as untenanted and the warehouse refused it. The chDB parity suite now asserts every compiled read is single-tenant. --- apps/cli/test/promql-engine.test.ts | 15 ++++++++++++--- packages/query-engine/src/ch/queries/promql.ts | 2 ++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/apps/cli/test/promql-engine.test.ts b/apps/cli/test/promql-engine.test.ts index 5066c0fb24..73d6765ac6 100644 --- a/apps/cli/test/promql-engine.test.ts +++ b/apps/cli/test/promql-engine.test.ts @@ -112,6 +112,13 @@ const insertHistogram = (db: Chdb, service: string): void => { const decodeRows = decodeJsonEachRow(promqlSelectorRowSchema) const decodeCatalog = decodeJsonEachRow(promqlCatalogRowSchema) +/** The tenant scope of every compiled read; the warehouse refuses anything but single-tenant. */ +const scopes = new Set() +const sqlOf = (compiled: { readonly sql: string; readonly tenantScope: string }) => { + scopes.add(compiled.tenantScope) + return normalizeSqlForClickHouseClient(compiled.sql) +} + const sqlRun = (db: Chdb, catalog: ReadonlyArray, query: string, params: QueryParams) => { const parsed = parse(query) if (Result.isFailure(parsed)) return Result.fail(parsed.failure.message) @@ -121,9 +128,7 @@ const sqlRun = (db: Chdb, catalog: ReadonlyArray, query: string, buildSelectorQueries(request, catalog, { orgId: OrgId.make(ORG), maxSeries: 10_000 }), (plan) => ({ plan, - rows: decodeRows( - db.query(normalizeSqlForClickHouseClient(Effect.runSync(plan.compiled).sql)), - ), + rows: decodeRows(db.query(sqlOf(Effect.runSync(plan.compiled)))), }), ) data.set(selector, toSelectorData(request, results)) @@ -227,4 +232,8 @@ describeWithChdb("PromQL on the warehouse matches the reference", () => { } }) } + + test("every compiled read is single-tenant, as the warehouse requires", () => { + expect([...scopes]).toEqual(["single-tenant"]) + }) }) diff --git a/packages/query-engine/src/ch/queries/promql.ts b/packages/query-engine/src/ch/queries/promql.ts index 426d0ce2c1..b48461669d 100644 --- a/packages/query-engine/src/ch/queries/promql.ts +++ b/packages/query-engine/src/ch/queries/promql.ts @@ -61,6 +61,8 @@ const stringMap = T.map(T.string, T.string) const metricTable = (name: PromqlMetricTable) => table(name, { external: true, + // Without it the OrgId filter does not count and the warehouse refuses every read as untenanted. + tenantColumn: "OrgId", columns: { OrgId: orgId, MetricName: T.string,