diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9323892bcb..fa6a9a6725 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -543,7 +543,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 exponential-histogram-metrics release-verification profile-sample-types service-usage-profiles search-traces-filters; 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 exponential-histogram-metrics release-verification profile-sample-types service-usage-profiles search-traces-filters 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..73d6765ac6 --- /dev/null +++ b/apps/cli/test/promql-engine.test.ts @@ -0,0 +1,239 @@ +// 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) + +/** 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) + 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(sqlOf(Effect.runSync(plan.compiled)))), + }), + ) + 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`) + } + }) + } + + test("every compiled read is single-tenant, as the warehouse requires", () => { + expect([...scopes]).toEqual(["single-tenant"]) + }) +}) diff --git a/apps/cli/test/promql-source.test.ts b/apps/cli/test/promql-source.test.ts new file mode 100644 index 0000000000..2ee7f28851 --- /dev/null +++ b/apps/cli/test/promql-source.test.ts @@ -0,0 +1,596 @@ +// 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) + }) + + 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) + }) + + 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/bun.lock b/bun.lock index e27e5794df..1a7c380a00 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", @@ -652,6 +653,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:*", @@ -933,6 +935,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 ab8f2590cb..4e3ecc0bb6 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..ade64ce4e0 --- /dev/null +++ b/packages/backend/src/services/promql/PromqlQueryService.test.ts @@ -0,0 +1,105 @@ +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") + }), + ) + + 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 new file mode 100644 index 0000000000..8af99b2a9c --- /dev/null +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -0,0 +1,209 @@ +// 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, + resolutionError, + 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.optionalKey(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 + +/** 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 +} + +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(CATALOG_LIMIT + 1), { + orgId: tenant.orgId, + startTime: formatWarehouseDateTime(window.startMs), + endTime: formatWarehouseDateTime(window.endMs), + }) + const rows = yield* warehouse.compiledQuery(tenant, compiled, { + 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) + }) + + 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, + }) + 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, + "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 }, + ) + // 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) + }) + + const query = Effect.fn("PromqlQueryService.query")(function* ( + tenant: TenantContext, + input: PromqlQuery, + ) { + yield* Effect.annotateCurrentSpan({ + "maple.promql.query_length": input.query.length, + "maple.promql.range_ms": input.endMs - input.startMs, + "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) { + 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 c11eb7044b..367676b8ae 100644 --- a/packages/query-engine/package.json +++ b/packages/query-engine/package.json @@ -22,7 +22,8 @@ "./ch/schema": "./src/ch/schema.ts", "./ch/format": "./src/ch/queries/format.ts", "./ch/query-helpers": "./src/ch/queries/query-helpers.ts", - "./ch/rollup-splice": "./src/ch/queries/rollup-splice.ts" + "./ch/rollup-splice": "./src/ch/queries/rollup-splice.ts", + "./promql": "./src/promql/index.ts" }, "scripts": { "test": "vitest run", @@ -33,6 +34,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 4141e8e4c8..3359578db2 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..b48461669d --- /dev/null +++ b/packages/query-engine/src/ch/queries/promql.ts @@ -0,0 +1,381 @@ +// 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 { 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" +import { CHNumber } from "../schema" +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" + | "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 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). */ + 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, + // Without it the OrgId filter does not count and the warehouse refuses every read as untenanted. + tenantColumn: "OrgId", + columns: { + OrgId: orgId, + MetricName: T.string, + MetricUnit: 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(($) => ({ + // 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, + t: sql(T.int64)`toUnixTimestamp64Milli(${$.TimeUnix})`, + isDelta: isDeltaExpr(opts.table), + pair: samplePair(opts.component), + })) + .where(($) => [ + $.OrgId.eq(orgIdParam), + $.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. + sql.cond`bitAnd(Flags, 1) = 0`, + finiteSampleCond(opts.component), + ...opts.conditions($), + ]) + +/** + * 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. + */ +const keyedQuery = (opts: PromqlSelectorOpts) => + fromQuery(scanQuery(opts), "scan").select(($) => ({ + sk: sql( + T.uint64, + )`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, + 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: $.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", "unit") + .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..089aa58c93 --- /dev/null +++ b/packages/query-engine/src/promql/labels.test.ts @@ -0,0 +1,113 @@ +import { Option, Record as Rec } from "effect" +import { describe, expect, it } from "vitest" +import { + formatLe, + labelValue, + matchesAll, + 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") + }) +}) + +describe("prototype-named labels", () => { + it("reads an attribute called constructor as its own string value", () => { + const labels = seriesLabels(row({ attributes: { constructor: "x" } })) + expect(Rec.get(labels, "constructor")).toEqual(Option.some("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 new file mode 100644 index 0000000000..295c460a81 --- /dev/null +++ b/packages/query-engine/src/promql/labels.ts @@ -0,0 +1,177 @@ +// 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)) + } + // fromEntries defines own properties, so a label called __proto__ stays a label. + return Rec.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, + Option.getOrElse(Rec.get(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_]', '_'), '_+', '_'))", +) + +/** 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 ", + )})`, +) + +/** 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 + // 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}` + 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..fae5134e09 --- /dev/null +++ b/packages/query-engine/src/promql/names.ts @@ -0,0 +1,213 @@ +// 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, type LabelRegex } 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 + /** The stored unit: one name may be stored in two units, which are two metrics. */ + readonly unit: 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, + unit: metric.unit, + })) + }) diff --git a/packages/query-engine/src/promql/source.ts b/packages/query-engine/src/promql/source.ts new file mode 100644 index 0000000000..ec8669c52a --- /dev/null +++ b/packages/query-engine/src/promql/source.ts @@ -0,0 +1,204 @@ +// 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 { + METRIC_UNIT_SEPARATOR, + 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 targets: ReadonlyArray + }, + options: SelectorPlanOptions, +) => { + const labelMatchers = Arr.filter(request.matchers, (m) => m.name !== "__name__") + return compile( + promqlSelectorQuery({ + table: group.table, + component: group.component, + targets: group.targets, + 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, + }, + ) +} + +/** 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__") + +/** 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) => [targetKey(t), t.promName] as const)) + return { + table: group.table, + component: group.component, + promNames, + compiled: compileSelector(request, group, 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, + }, + ] + : [], + )