@maroonedsoftware/telemetry 0.0.0-stage → 0.1.1

package/dist/kysely.js

@@ -0,0 +1,237 @@
+import {
+  mergeAggregates
+} from "./chunk-E7OXUL3D.js";
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/metrics.store.ts
+import { sql } from "kysely";
+import { DateTime } from "luxon";
+var PRIMARY_KEY = [
+  "resolution",
+  "name",
+  "labels_key",
+  "bucket"
+];
+var instantOf = /* @__PURE__ */ __name((value) => {
+  if (DateTime.isDateTime(value)) {
+    return value.toUTC();
+  }
+  if (value instanceof Date) {
+    return DateTime.fromJSDate(value, {
+      zone: "utc"
+    });
+  }
+  return DateTime.fromISO(value.replace(" ", "T"), {
+    zone: "utc"
+  });
+}, "instantOf");
+var MetricsStore = class {
+  static {
+    __name(this, "MetricsStore");
+  }
+  db;
+  table;
+  scope;
+  batchSize;
+  /**
+  * @param db - Any Kysely instance on the database holding the table.
+  * @param options - The table and scope.
+  */
+  constructor(db, options) {
+    this.db = db.withoutPlugins();
+    this.table = options.table;
+    this.scope = Object.entries(options.scope ?? {});
+    this.batchSize = options.batchSize ?? 500;
+  }
+  /**
+  * Writes minute buckets, merging each into the row already stored for its series and minute.
+  *
+  * A minute flushed twice therefore adds up rather than failing or being overwritten, which is what
+  * lets a recorder drain its still-open minute. Buckets for the same series and minute in one call
+  * are merged first, since PostgreSQL refuses to update one row twice in a statement.
+  *
+  * @param buckets - What a recorder drained.
+  * @param source - Recorded on each row; tells an app's own metrics from received ones. Defaults to `'app'`.
+  * @returns How many rows were written.
+  */
+  async upsertMinutes(buckets, source = "app") {
+    const merged = /* @__PURE__ */ new Map();
+    for (const bucket of buckets) {
+      const id = `${bucket.name}\0${bucket.labelsKey}\0${bucket.start.toMillis()}`;
+      const existing = merged.get(id);
+      merged.set(id, existing === void 0 ? bucket : {
+        ...existing,
+        aggregate: mergeAggregates(existing.aggregate, bucket.aggregate)
+      });
+    }
+    const rows = [
+      ...merged.values()
+    ].map((bucket) => ({
+      ...Object.fromEntries(this.scope),
+      resolution: "minute",
+      bucket: bucket.start.toUTC().toJSDate(),
+      name: bucket.name,
+      labels: JSON.stringify(bucket.labels),
+      labels_key: bucket.labelsKey,
+      source,
+      ...bucket.aggregate
+    }));
+    let written = 0;
+    for (let at = 0; at < rows.length; at += this.batchSize) {
+      const batch = rows.slice(at, at + this.batchSize);
+      const result = await sql`
+        insert into ${sql.table(this.table)} as stored (${sql.join(Object.keys(batch[0] ?? {}).map((column) => sql.ref(column)))})
+        values ${sql.join(batch.map((row) => sql`(${sql.join(Object.values(row))})`))}
+        on conflict (${this.conflictTarget()}) do update set
+          count = ${this.column("count")} + excluded.count,
+          sum = ${this.column("sum")} + excluded.sum,
+          min = least(${this.column("min")}, excluded.min),
+          max = greatest(${this.column("max")}, excluded.max),
+          last = excluded.last
+      `.execute(this.db);
+      written += Number(result.numAffectedRows ?? 0n);
+    }
+    return written;
+  }
+  /**
+  * Folds one hour of minute rows into hour rows.
+  *
+  * Idempotent: the hour row is replaced, not added to, so running it twice (a retried job, an
+  * overlapping schedule) leaves the same answer. Run it once the hour is complete; run before then
+  * and a later run corrects it.
+  *
+  * @param hourStart - Any instant inside the hour to roll up; it is truncated to the UTC hour.
+  * @returns How many hour rows were written.
+  */
+  async rollupHour(hourStart) {
+    const from = hourStart.toUTC().startOf("hour");
+    const to = from.plus({
+      hours: 1
+    });
+    const scopeColumns = this.scope.map(([column]) => sql`${sql.ref(column)}, `);
+    const scopeValues = this.scope.map(([, value]) => sql`${value}, `);
+    const result = await sql`
+      insert into ${sql.table(this.table)} (${sql.join(scopeColumns, sql``)}resolution, bucket, name, labels, labels_key, source, count, sum, min, max, last)
+      select ${sql.join(scopeValues, sql``)}'hour', ${from.toJSDate()}, name, (array_agg(labels))[1], labels_key, (array_agg(source))[1],
+        sum(count), sum(sum), min(min), max(max), (array_agg(last order by bucket desc))[1]
+      from ${sql.table(this.table)}
+      where ${this.where(sql`resolution = 'minute'`, sql`bucket >= ${from.toJSDate()}`, sql`bucket < ${to.toJSDate()}`)}
+      group by name, labels_key
+      on conflict (${this.conflictTarget()}) do update set
+        labels = excluded.labels, source = excluded.source,
+        count = excluded.count, sum = excluded.sum, min = excluded.min, max = excluded.max, last = excluded.last
+    `.execute(this.db);
+    return Number(result.numAffectedRows ?? 0n);
+  }
+  /**
+  * Deletes rows of one resolution older than `olderThan`.
+  *
+  * @param resolution - Which rows.
+  * @param olderThan - How old a row's bucket must be to go.
+  * @param now - The instant ages are measured from. Defaults to now.
+  * @returns How many rows were deleted.
+  */
+  async prune(resolution, olderThan, now = DateTime.now()) {
+    const cutoff = now.minus(olderThan).toUTC().toJSDate();
+    const result = await sql`
+      delete from ${sql.table(this.table)}
+      where ${this.where(sql`resolution = ${resolution}`, sql`bucket < ${cutoff}`)}
+    `.execute(this.db);
+    return Number(result.numAffectedRows ?? 0n);
+  }
+  /**
+  * Reads series over a range, one entry per name and label set, points oldest first.
+  *
+  * @param query - The names, range, resolution and label filter.
+  */
+  async series(query) {
+    if (query.names.length === 0) {
+      return [];
+    }
+    const conditions = [
+      sql`resolution = ${query.resolution}`,
+      sql`name in (${sql.join([
+        ...query.names
+      ])})`,
+      sql`bucket >= ${query.from.toUTC().toJSDate()}`,
+      sql`bucket < ${query.to.toUTC().toJSDate()}`
+    ];
+    if (query.labels !== void 0 && Object.keys(query.labels).length > 0) {
+      conditions.push(sql`labels @> ${JSON.stringify(query.labels)}::jsonb`);
+    }
+    const { rows } = await sql`
+      select name, labels, labels_key, source, bucket, count, sum, min, max, last
+      from ${sql.table(this.table)}
+      where ${this.where(...conditions)}
+      order by name, labels_key, bucket
+    `.execute(this.db);
+    const series = [];
+    let current;
+    for (const row of rows) {
+      if (current === void 0 || current.name !== row.name || current.labelsKey !== row.labels_key) {
+        const labels = typeof row.labels === "string" ? JSON.parse(row.labels) : row.labels;
+        current = {
+          name: row.name,
+          labels,
+          labelsKey: row.labels_key,
+          source: row.source,
+          points: []
+        };
+        series.push(current);
+      }
+      current.points.push({
+        start: instantOf(row.bucket),
+        aggregate: {
+          count: row.count,
+          sum: row.sum,
+          min: row.min,
+          max: row.max,
+          last: row.last
+        }
+      });
+    }
+    return series;
+  }
+  /**
+  * Lists every metric name the store holds, with its source, label keys and newest bucket.
+  */
+  async names() {
+    const { rows } = await sql`
+      select name, source, max(bucket) as last_seen, array_agg(distinct key) filter (where key is not null) as label_keys
+      from ${sql.table(this.table)} left join lateral jsonb_object_keys(labels) as key on true
+      where ${this.where(sql`true`)}
+      group by name, source
+      order by name, source
+    `.execute(this.db);
+    return rows.map((row) => ({
+      name: row.name,
+      source: row.source,
+      labelKeys: [
+        ...row.label_keys ?? []
+      ].sort(),
+      lastSeen: instantOf(row.last_seen)
+    }));
+  }
+  /** A column of the row already stored, inside an upsert's `do update`; the insert aliases the table `stored`. */
+  column(name) {
+    return sql.ref(`stored.${name}`);
+  }
+  conflictTarget() {
+    return sql.join([
+      ...this.scope.map(([column]) => column),
+      ...PRIMARY_KEY
+    ].map((column) => sql.ref(column)));
+  }
+  where(...conditions) {
+    return sql.join([
+      ...this.scope.map(([column, value]) => sql`${sql.ref(column)} = ${value}`),
+      ...conditions
+    ], sql` and `);
+  }
+};
+export {
+  MetricsStore
+};
+//# sourceMappingURL=kysely.js.map

package/dist/kysely.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/metrics.store.ts"],"sourcesContent":["import { Kysely, RawBuilder, sql } from 'kysely';\nimport { DateTime, Duration } from 'luxon';\nimport { mergeAggregates, MetricAggregate } from './metric.aggregate.js';\nimport { MetricBucket } from './metric.bucket.js';\nimport { MetricLabels } from './metric.labels.js';\nimport { MetricResolution } from './metric.resolution.js';\n\n/**\n * Where a {@link MetricsStore} keeps its rows.\n */\nexport interface MetricsStoreOptions {\n  /** The table, schema-qualified if needed: `'metrics.metric_samples'`. */\n  table: string;\n  /**\n   * Fixed column values every row carries and every read filters on, e.g. `{ tenant_key: 'main' }`\n   * for an app that keeps several tenants in one table. Each column must be part of the table's\n   * primary key. Column names are written as they are in the database.\n   */\n  scope?: Readonly<Record<string, string>>;\n  /** Rows per `insert` statement when upserting. Defaults to 500. */\n  batchSize?: number;\n}\n\n/**\n * One stored point of a series.\n */\nexport interface MetricPoint {\n  /** The start of the point's minute or hour, in UTC. */\n  start: DateTime;\n  /** The point's aggregate. */\n  aggregate: MetricAggregate;\n}\n\n/**\n * One series read back from the store, its points oldest first.\n */\nexport interface MetricSeries {\n  name: string;\n  labels: MetricLabels;\n  labelsKey: string;\n  source: string;\n  points: MetricPoint[];\n}\n\n/**\n * What to read with {@link MetricsStore.series}.\n */\nexport interface MetricSeriesQuery {\n  /** The metric names to read. An empty list reads nothing. */\n  names: readonly string[];\n  /** Inclusive start. */\n  from: DateTime;\n  /** Exclusive end. */\n  to: DateTime;\n  /** Which rows to read. See `resolutionFor`. */\n  resolution: MetricResolution;\n  /** Only series whose labels contain all of these pairs. */\n  labels?: MetricLabels;\n}\n\n/**\n * A metric name the store holds, for building a picker.\n */\nexport interface MetricName {\n  name: string;\n  source: string;\n  /** Every label key any of its series carries, sorted. */\n  labelKeys: string[];\n  /** The newest bucket stored for it, at any resolution. */\n  lastSeen: DateTime;\n}\n\ninterface SeriesRow {\n  name: string;\n  labels: MetricLabels | string;\n  labels_key: string;\n  source: string;\n  bucket: DateTime | Date | string;\n  count: number;\n  sum: number;\n  min: number;\n  max: number;\n  last: number;\n}\n\ninterface NameRow {\n  name: string;\n  source: string;\n  last_seen: DateTime | Date | string;\n  label_keys: string[] | null;\n}\n\nconst PRIMARY_KEY = ['resolution', 'name', 'labels_key', 'bucket'] as const;\n\n/**\n * Reads a `timestamptz` however the pool hands it back: a `DateTime` under\n * `@maroonedsoftware/kysely`'s `KyselyPgTypeOverrides`, a `Date` under `pg`'s defaults, or text under\n * a parser that returns the raw value.\n */\nconst instantOf = (value: DateTime | Date | string): DateTime => {\n  if (DateTime.isDateTime(value)) {\n    return value.toUTC();\n  }\n  if (value instanceof Date) {\n    return DateTime.fromJSDate(value, { zone: 'utc' });\n  }\n  return DateTime.fromISO(value.replace(' ', 'T'), { zone: 'utc' });\n};\n\n/**\n * Keeps metric buckets in one PostgreSQL table at two resolutions, minutes and hours.\n *\n * The table is the app's own, created by its own migration from the reference DDL in this package's\n * README. The store only reads and writes it.\n *\n * It runs on `db.withoutPlugins()`, so the app's `CamelCasePlugin` (or any other) never rewrites the\n * snake_case columns this class names, and rows come back exactly as PostgreSQL sends them.\n *\n * @example\n * ```typescript\n * const store = new MetricsStore(db, { table: 'app.metric_samples' });\n * await store.upsertMinutes(recorder.drain());\n * await store.rollupHour(DateTime.utc().startOf('hour').minus({ hours: 1 }));\n * ```\n *\n * @typeParam DB - The app's database type. The store never uses it (every statement is raw SQL on the\n *   table it was given), so any `Kysely<DB>` is accepted as it is, with no cast at the call site.\n */\nexport class MetricsStore<DB = unknown> {\n  private readonly db: Kysely<DB>;\n  private readonly table: string;\n  private readonly scope: [string, string][];\n  private readonly batchSize: number;\n\n  /**\n   * @param db - Any Kysely instance on the database holding the table.\n   * @param options - The table and scope.\n   */\n  constructor(db: Kysely<DB>, options: MetricsStoreOptions) {\n    this.db = db.withoutPlugins();\n    this.table = options.table;\n    this.scope = Object.entries(options.scope ?? {});\n    this.batchSize = options.batchSize ?? 500;\n  }\n\n  /**\n   * Writes minute buckets, merging each into the row already stored for its series and minute.\n   *\n   * A minute flushed twice therefore adds up rather than failing or being overwritten, which is what\n   * lets a recorder drain its still-open minute. Buckets for the same series and minute in one call\n   * are merged first, since PostgreSQL refuses to update one row twice in a statement.\n   *\n   * @param buckets - What a recorder drained.\n   * @param source - Recorded on each row; tells an app's own metrics from received ones. Defaults to `'app'`.\n   * @returns How many rows were written.\n   */\n  async upsertMinutes(buckets: readonly MetricBucket[], source = 'app'): Promise<number> {\n    const merged = new Map<string, MetricBucket>();\n    for (const bucket of buckets) {\n      const id = `${bucket.name}\\u0000${bucket.labelsKey}\\u0000${bucket.start.toMillis()}`;\n      const existing = merged.get(id);\n      merged.set(id, existing === undefined ? bucket : { ...existing, aggregate: mergeAggregates(existing.aggregate, bucket.aggregate) });\n    }\n    const rows = [...merged.values()].map(bucket => ({\n      ...Object.fromEntries(this.scope),\n      resolution: 'minute',\n      bucket: bucket.start.toUTC().toJSDate(),\n      name: bucket.name,\n      labels: JSON.stringify(bucket.labels),\n      labels_key: bucket.labelsKey,\n      source,\n      ...bucket.aggregate,\n    }));\n\n    let written = 0;\n    for (let at = 0; at < rows.length; at += this.batchSize) {\n      const batch = rows.slice(at, at + this.batchSize);\n      const result = await sql`\n        insert into ${sql.table(this.table)} as stored (${sql.join(Object.keys(batch[0] ?? {}).map(column => sql.ref(column)))})\n        values ${sql.join(batch.map(row => sql`(${sql.join(Object.values(row))})`))}\n        on conflict (${this.conflictTarget()}) do update set\n          count = ${this.column('count')} + excluded.count,\n          sum = ${this.column('sum')} + excluded.sum,\n          min = least(${this.column('min')}, excluded.min),\n          max = greatest(${this.column('max')}, excluded.max),\n          last = excluded.last\n      `.execute(this.db);\n      written += Number(result.numAffectedRows ?? 0n);\n    }\n    return written;\n  }\n\n  /**\n   * Folds one hour of minute rows into hour rows.\n   *\n   * Idempotent: the hour row is replaced, not added to, so running it twice (a retried job, an\n   * overlapping schedule) leaves the same answer. Run it once the hour is complete; run before then\n   * and a later run corrects it.\n   *\n   * @param hourStart - Any instant inside the hour to roll up; it is truncated to the UTC hour.\n   * @returns How many hour rows were written.\n   */\n  async rollupHour(hourStart: DateTime): Promise<number> {\n    const from = hourStart.toUTC().startOf('hour');\n    const to = from.plus({ hours: 1 });\n    const scopeColumns = this.scope.map(([column]) => sql`${sql.ref(column)}, `);\n    const scopeValues = this.scope.map(([, value]) => sql`${value}, `);\n\n    const result = await sql`\n      insert into ${sql.table(this.table)} (${sql.join(scopeColumns, sql``)}resolution, bucket, name, labels, labels_key, source, count, sum, min, max, last)\n      select ${sql.join(scopeValues, sql``)}'hour', ${from.toJSDate()}, name, (array_agg(labels))[1], labels_key, (array_agg(source))[1],\n        sum(count), sum(sum), min(min), max(max), (array_agg(last order by bucket desc))[1]\n      from ${sql.table(this.table)}\n      where ${this.where(sql`resolution = 'minute'`, sql`bucket >= ${from.toJSDate()}`, sql`bucket < ${to.toJSDate()}`)}\n      group by name, labels_key\n      on conflict (${this.conflictTarget()}) do update set\n        labels = excluded.labels, source = excluded.source,\n        count = excluded.count, sum = excluded.sum, min = excluded.min, max = excluded.max, last = excluded.last\n    `.execute(this.db);\n    return Number(result.numAffectedRows ?? 0n);\n  }\n\n  /**\n   * Deletes rows of one resolution older than `olderThan`.\n   *\n   * @param resolution - Which rows.\n   * @param olderThan - How old a row's bucket must be to go.\n   * @param now - The instant ages are measured from. Defaults to now.\n   * @returns How many rows were deleted.\n   */\n  async prune(resolution: MetricResolution, olderThan: Duration, now: DateTime = DateTime.now()): Promise<number> {\n    const cutoff = now.minus(olderThan).toUTC().toJSDate();\n    const result = await sql`\n      delete from ${sql.table(this.table)}\n      where ${this.where(sql`resolution = ${resolution}`, sql`bucket < ${cutoff}`)}\n    `.execute(this.db);\n    return Number(result.numAffectedRows ?? 0n);\n  }\n\n  /**\n   * Reads series over a range, one entry per name and label set, points oldest first.\n   *\n   * @param query - The names, range, resolution and label filter.\n   */\n  async series(query: MetricSeriesQuery): Promise<MetricSeries[]> {\n    if (query.names.length === 0) {\n      return [];\n    }\n    const conditions: RawBuilder<unknown>[] = [\n      sql`resolution = ${query.resolution}`,\n      sql`name in (${sql.join([...query.names])})`,\n      sql`bucket >= ${query.from.toUTC().toJSDate()}`,\n      sql`bucket < ${query.to.toUTC().toJSDate()}`,\n    ];\n    if (query.labels !== undefined && Object.keys(query.labels).length > 0) {\n      conditions.push(sql`labels @> ${JSON.stringify(query.labels)}::jsonb`);\n    }\n    const { rows } = await sql<SeriesRow>`\n      select name, labels, labels_key, source, bucket, count, sum, min, max, last\n      from ${sql.table(this.table)}\n      where ${this.where(...conditions)}\n      order by name, labels_key, bucket\n    `.execute(this.db);\n\n    const series: MetricSeries[] = [];\n    let current: MetricSeries | undefined;\n    for (const row of rows) {\n      if (current === undefined || current.name !== row.name || current.labelsKey !== row.labels_key) {\n        const labels = typeof row.labels === 'string' ? (JSON.parse(row.labels) as MetricLabels) : row.labels;\n        current = { name: row.name, labels, labelsKey: row.labels_key, source: row.source, points: [] };\n        series.push(current);\n      }\n      current.points.push({\n        start: instantOf(row.bucket),\n        aggregate: { count: row.count, sum: row.sum, min: row.min, max: row.max, last: row.last },\n      });\n    }\n    return series;\n  }\n\n  /**\n   * Lists every metric name the store holds, with its source, label keys and newest bucket.\n   */\n  async names(): Promise<MetricName[]> {\n    const { rows } = await sql<NameRow>`\n      select name, source, max(bucket) as last_seen, array_agg(distinct key) filter (where key is not null) as label_keys\n      from ${sql.table(this.table)} left join lateral jsonb_object_keys(labels) as key on true\n      where ${this.where(sql`true`)}\n      group by name, source\n      order by name, source\n    `.execute(this.db);\n    return rows.map(row => ({\n      name: row.name,\n      source: row.source,\n      labelKeys: [...(row.label_keys ?? [])].sort(),\n      lastSeen: instantOf(row.last_seen),\n    }));\n  }\n\n  /** A column of the row already stored, inside an upsert's `do update`; the insert aliases the table `stored`. */\n  private column(name: string): RawBuilder<unknown> {\n    return sql.ref(`stored.${name}`);\n  }\n\n  private conflictTarget(): RawBuilder<unknown> {\n    return sql.join([...this.scope.map(([column]) => column), ...PRIMARY_KEY].map(column => sql.ref(column)));\n  }\n\n  private where(...conditions: RawBuilder<unknown>[]): RawBuilder<unknown> {\n    return sql.join([...this.scope.map(([column, value]) => sql`${sql.ref(column)} = ${value}`), ...conditions], sql` and `);\n  }\n}\n"],"mappings":"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","names":["sql","DateTime","PRIMARY_KEY","instantOf","value","DateTime","isDateTime","toUTC","Date","fromJSDate","zone","fromISO","replace","MetricsStore","db","table","scope","batchSize","options","withoutPlugins","Object","entries","upsertMinutes","buckets","source","merged","Map","bucket","id","name","labelsKey","start","toMillis","existing","get","set","undefined","aggregate","mergeAggregates","rows","values","map","fromEntries","resolution","toJSDate","labels","JSON","stringify","labels_key","written","at","length","batch","slice","result","sql","join","keys","column","ref","row","conflictTarget","execute","Number","numAffectedRows","rollupHour","hourStart","from","startOf","to","plus","hours","scopeColumns","scopeValues","where","prune","olderThan","now","cutoff","minus","series","query","names","conditions","push","current","parse","points","count","sum","min","max","last","labelKeys","label_keys","sort","lastSeen","last_seen"]}

package/dist/metric.aggregate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Five numbers that summarise every observation of one series inside one bucket.
+ *
+ * One shape covers all three kinds of metric, so a store needs a single row type:
+ * - a **gauge** reads `last` (or `sum / count` for the bucket's mean),
+ * - a **counter** reads `sum`,
+ * - a **duration** reads `sum / count` for the mean and `max` for the worst.
+ *
+ * There are no percentiles. They need a histogram or a sketch per bucket, and the
+ * mean beside the max is enough to see that something got slow.
+ */
+export interface MetricAggregate {
+    /** How many observations were folded in. */
+    count: number;
+    /** Their total. */
+    sum: number;
+    /** The smallest observation. */
+    min: number;
+    /** The largest observation. */
+    max: number;
+    /** The most recent observation. */
+    last: number;
+}
+/**
+ * The aggregate of a single observation.
+ *
+ * @param value - The observed value. The caller is expected to have rejected non-finite values.
+ */
+export declare const aggregateOf: (value: number) => MetricAggregate;
+/**
+ * Folds `next` into `previous`.
+ *
+ * Associative, so buckets can be merged in any grouping (a flush into a stored row, minutes into an
+ * hour). Not commutative in `last`: `next` is taken to be the later of the two.
+ *
+ * @param previous - The earlier aggregate.
+ * @param next - The later aggregate.
+ * @returns A new aggregate; neither input is modified.
+ */
+export declare const mergeAggregates: (previous: MetricAggregate, next: MetricAggregate) => MetricAggregate;
+//# sourceMappingURL=metric.aggregate.d.ts.map

package/dist/metric.aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.aggregate.d.ts","sourceRoot":"","sources":["../src/metric.aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,eAAkF,CAAC;AAE/H;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,eAAe,EAAE,MAAM,eAAe,KAAG,eAMjF,CAAC"}

package/dist/metric.bucket.d.ts

@@ -0,0 +1,25 @@
+import { DateTime } from 'luxon';
+import { MetricAggregate } from './metric.aggregate.js';
+import { MetricLabels } from './metric.labels.js';
+/**
+ * One series' aggregate over one minute: what a recorder drains and what a store writes.
+ */
+export interface MetricBucket {
+    /** The metric's name, in dot notation: `work.job.ms`. */
+    name: string;
+    /** The series' labels. */
+    labels: MetricLabels;
+    /** {@link labelsKey} of `labels`, computed once at observation time. */
+    labelsKey: string;
+    /** The start of the bucket's minute, in UTC. */
+    start: DateTime;
+    /** Everything observed for this series in this minute. */
+    aggregate: MetricAggregate;
+}
+/**
+ * The start of the minute `at` falls in, in UTC.
+ *
+ * @param at - Any instant.
+ */
+export declare const minuteOf: (at: DateTime) => DateTime;
+//# sourceMappingURL=metric.bucket.d.ts.map

package/dist/metric.bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.bucket.d.ts","sourceRoot":"","sources":["../src/metric.bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,KAAK,EAAE,QAAQ,CAAC;IAChB,0DAA0D;IAC1D,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,IAAI,QAAQ,KAAG,QAAwC,CAAC"}

package/dist/metric.labels.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The labels that tell one series of a metric from another, e.g. `{ queue: 'catalog.sync' }`.
+ *
+ * Values are strings only. A number used as a label is almost always a cardinality mistake waiting
+ * to happen, and making the caller write `String(x)` is a moment to notice it.
+ */
+export type MetricLabels = Readonly<Record<string, string>>;
+/**
+ * A canonical string for a label set: JSON with keys sorted.
+ *
+ * Two label sets with the same pairs in a different order produce the same key, so the key can sit
+ * in a primary key where the `jsonb` labels themselves cannot be compared cheaply.
+ *
+ * @param labels - The label set.
+ * @returns `'{}'` for no labels, otherwise sorted JSON.
+ */
+export declare const labelsKey: (labels: MetricLabels) => string;
+//# sourceMappingURL=metric.labels.d.ts.map

package/dist/metric.labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.labels.d.ts","sourceRoot":"","sources":["../src/metric.labels.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,YAAY,KAAG,MAShD,CAAC"}

package/dist/metric.resolution.d.ts

@@ -0,0 +1,19 @@
+import { DateTime, Duration } from 'luxon';
+/**
+ * The two widths a stored metric row can have: raw minutes, and the hours they are rolled up into.
+ */
+export type MetricResolution = 'minute' | 'hour';
+/**
+ * The widest range still read at minute resolution by {@link resolutionFor}: two days is 2,880
+ * points per series, about as many as a chart can draw usefully.
+ */
+export declare const MINUTE_RESOLUTION_LIMIT: Duration<true>;
+/**
+ * The resolution to read a range at: minutes for a range up to `limit`, hours beyond it.
+ *
+ * @param from - The start of the range.
+ * @param to - The end of the range.
+ * @param limit - The widest range read in minutes. Defaults to {@link MINUTE_RESOLUTION_LIMIT}.
+ */
+export declare const resolutionFor: (from: DateTime, to: DateTime, limit?: Duration) => MetricResolution;
+//# sourceMappingURL=metric.resolution.d.ts.map

package/dist/metric.resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.resolution.d.ts","sourceRoot":"","sources":["../src/metric.resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,gBAAqC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,QAAQ,EAAE,IAAI,QAAQ,EAAE,QAAO,QAAkC,KAAG,gBAC5D,CAAC"}

package/dist/metrics.recorder.d.ts

@@ -0,0 +1,96 @@
+import { DateTime, Duration } from 'luxon';
+import { MetricBucket } from './metric.bucket.js';
+import { MetricLabels } from './metric.labels.js';
+/**
+ * Reads a gauge's current value. `undefined` means "no reading this time" and records nothing.
+ */
+export type GaugeReader = () => number | undefined | Promise<number | undefined>;
+/**
+ * Called when a gauge's reader throws. The sample is skipped either way.
+ */
+export type GaugeErrorHandler = (name: string, error: unknown) => void;
+/**
+ * How a gauge is registered.
+ */
+export interface GaugeOptions {
+    /** Labels for the gauge's series. Defaults to none. */
+    labels?: MetricLabels;
+    /**
+     * The least time between two samples. Defaults to zero: sampled on every
+     * {@link MetricsRecorder.sampleGauges} call. Use it for a reading that is expensive (a disk scan)
+     * while the sampler runs every minute for the cheap ones.
+     */
+    every?: Duration;
+}
+/**
+ * Accumulates observations into one-minute buckets in memory, and samples registered gauges.
+ *
+ * Nothing here does I/O. The owner runs a loop that calls {@link sampleGauges} and then
+ * {@link drain}, and writes what it drained wherever it keeps metrics (the `/kysely` store, an OTLP
+ * bridge, both). Draining hands over the current, still-open minute too: a store merges a later
+ * flush of the same minute into the row already written, so nothing waits for a minute to close.
+ *
+ * Register it as a singleton. One instance per process is the point: every producer observes into
+ * the same buffer.
+ *
+ * @example
+ * ```typescript
+ * const recorder = container.get(MetricsRecorder);
+ * recorder.observe('work.job.ms', 412, { queue: 'catalog.sync' });
+ * recorder.gauge('station.listeners', () => audience.count());
+ *
+ * await recorder.sampleGauges();
+ * await store.upsertMinutes(recorder.drain());
+ * ```
+ */
+export declare class MetricsRecorder {
+    private open;
+    private readonly gauges;
+    /**
+     * Told about a gauge whose reader threw. Unset, such failures are silent: a gauge that cannot be
+     * read simply leaves a gap, which is what a chart should show.
+     */
+    onGaugeError?: GaugeErrorHandler;
+    /**
+     * Records one observation into the minute `at` falls in.
+     *
+     * Non-finite values (`NaN`, `Infinity`) are dropped: one of them would poison every aggregate
+     * of the bucket it lands in.
+     *
+     * @param name - The metric's name.
+     * @param value - The observed value.
+     * @param labels - The series' labels.
+     * @param at - When it was observed. Defaults to now.
+     */
+    observe(name: string, value: number, labels?: MetricLabels, at?: DateTime): void;
+    /**
+     * Registers a gauge to be sampled by {@link sampleGauges}.
+     *
+     * Registering the same name and labels again replaces the earlier reader.
+     *
+     * @param name - The metric's name.
+     * @param read - Returns the current value.
+     * @param options - Labels and sampling cadence.
+     * @returns A function that unregisters this gauge.
+     */
+    gauge(name: string, read: GaugeReader, options?: GaugeOptions): () => void;
+    /**
+     * Reads every gauge that is due and observes its value at `now`.
+     *
+     * Readers run concurrently, so one slow gauge does not delay the others. A reader that throws
+     * or answers `undefined` records nothing; it is still marked sampled, so a failing reader is
+     * retried at its own cadence rather than on every call.
+     *
+     * @param now - The sampling instant. Defaults to now.
+     */
+    sampleGauges(now?: DateTime): Promise<void>;
+    /**
+     * Hands over every bucket recorded since the last drain and empties the buffer.
+     *
+     * @returns The buckets, oldest minute first.
+     */
+    drain(): MetricBucket[];
+    /** How many buckets are waiting to be drained. */
+    get pending(): number;
+}
+//# sourceMappingURL=metrics.recorder.d.ts.map

package/dist/metrics.recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.recorder.d.ts","sourceRoot":"","sources":["../src/metrics.recorder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAY,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAa,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAmC;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAE7D;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAEjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,YAAiB,EAAE,EAAE,GAAE,QAAyB,GAAG,IAAI;IAepG;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,IAAI;IAY9E;;;;;;;;OAQG;IACG,YAAY,CAAC,GAAG,GAAE,QAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjE;;;;OAIG;IACH,KAAK,IAAI,YAAY,EAAE;IAMvB,kDAAkD;IAClD,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}

package/dist/metrics.store.d.ts

@@ -0,0 +1,143 @@
+import { Kysely } from 'kysely';
+import { DateTime, Duration } from 'luxon';
+import { MetricAggregate } from './metric.aggregate.js';
+import { MetricBucket } from './metric.bucket.js';
+import { MetricLabels } from './metric.labels.js';
+import { MetricResolution } from './metric.resolution.js';
+/**
+ * Where a {@link MetricsStore} keeps its rows.
+ */
+export interface MetricsStoreOptions {
+    /** The table, schema-qualified if needed: `'metrics.metric_samples'`. */
+    table: string;
+    /**
+     * Fixed column values every row carries and every read filters on, e.g. `{ tenant_key: 'main' }`
+     * for an app that keeps several tenants in one table. Each column must be part of the table's
+     * primary key. Column names are written as they are in the database.
+     */
+    scope?: Readonly<Record<string, string>>;
+    /** Rows per `insert` statement when upserting. Defaults to 500. */
+    batchSize?: number;
+}
+/**
+ * One stored point of a series.
+ */
+export interface MetricPoint {
+    /** The start of the point's minute or hour, in UTC. */
+    start: DateTime;
+    /** The point's aggregate. */
+    aggregate: MetricAggregate;
+}
+/**
+ * One series read back from the store, its points oldest first.
+ */
+export interface MetricSeries {
+    name: string;
+    labels: MetricLabels;
+    labelsKey: string;
+    source: string;
+    points: MetricPoint[];
+}
+/**
+ * What to read with {@link MetricsStore.series}.
+ */
+export interface MetricSeriesQuery {
+    /** The metric names to read. An empty list reads nothing. */
+    names: readonly string[];
+    /** Inclusive start. */
+    from: DateTime;
+    /** Exclusive end. */
+    to: DateTime;
+    /** Which rows to read. See `resolutionFor`. */
+    resolution: MetricResolution;
+    /** Only series whose labels contain all of these pairs. */
+    labels?: MetricLabels;
+}
+/**
+ * A metric name the store holds, for building a picker.
+ */
+export interface MetricName {
+    name: string;
+    source: string;
+    /** Every label key any of its series carries, sorted. */
+    labelKeys: string[];
+    /** The newest bucket stored for it, at any resolution. */
+    lastSeen: DateTime;
+}
+/**
+ * Keeps metric buckets in one PostgreSQL table at two resolutions, minutes and hours.
+ *
+ * The table is the app's own, created by its own migration from the reference DDL in this package's
+ * README. The store only reads and writes it.
+ *
+ * It runs on `db.withoutPlugins()`, so the app's `CamelCasePlugin` (or any other) never rewrites the
+ * snake_case columns this class names, and rows come back exactly as PostgreSQL sends them.
+ *
+ * @example
+ * ```typescript
+ * const store = new MetricsStore(db, { table: 'app.metric_samples' });
+ * await store.upsertMinutes(recorder.drain());
+ * await store.rollupHour(DateTime.utc().startOf('hour').minus({ hours: 1 }));
+ * ```
+ *
+ * @typeParam DB - The app's database type. The store never uses it (every statement is raw SQL on the
+ *   table it was given), so any `Kysely<DB>` is accepted as it is, with no cast at the call site.
+ */
+export declare class MetricsStore<DB = unknown> {
+    private readonly db;
+    private readonly table;
+    private readonly scope;
+    private readonly batchSize;
+    /**
+     * @param db - Any Kysely instance on the database holding the table.
+     * @param options - The table and scope.
+     */
+    constructor(db: Kysely<DB>, options: MetricsStoreOptions);
+    /**
+     * Writes minute buckets, merging each into the row already stored for its series and minute.
+     *
+     * A minute flushed twice therefore adds up rather than failing or being overwritten, which is what
+     * lets a recorder drain its still-open minute. Buckets for the same series and minute in one call
+     * are merged first, since PostgreSQL refuses to update one row twice in a statement.
+     *
+     * @param buckets - What a recorder drained.
+     * @param source - Recorded on each row; tells an app's own metrics from received ones. Defaults to `'app'`.
+     * @returns How many rows were written.
+     */
+    upsertMinutes(buckets: readonly MetricBucket[], source?: string): Promise<number>;
+    /**
+     * Folds one hour of minute rows into hour rows.
+     *
+     * Idempotent: the hour row is replaced, not added to, so running it twice (a retried job, an
+     * overlapping schedule) leaves the same answer. Run it once the hour is complete; run before then
+     * and a later run corrects it.
+     *
+     * @param hourStart - Any instant inside the hour to roll up; it is truncated to the UTC hour.
+     * @returns How many hour rows were written.
+     */
+    rollupHour(hourStart: DateTime): Promise<number>;
+    /**
+     * Deletes rows of one resolution older than `olderThan`.
+     *
+     * @param resolution - Which rows.
+     * @param olderThan - How old a row's bucket must be to go.
+     * @param now - The instant ages are measured from. Defaults to now.
+     * @returns How many rows were deleted.
+     */
+    prune(resolution: MetricResolution, olderThan: Duration, now?: DateTime): Promise<number>;
+    /**
+     * Reads series over a range, one entry per name and label set, points oldest first.
+     *
+     * @param query - The names, range, resolution and label filter.
+     */
+    series(query: MetricSeriesQuery): Promise<MetricSeries[]>;
+    /**
+     * Lists every metric name the store holds, with its source, label keys and newest bucket.
+     */
+    names(): Promise<MetricName[]>;
+    /** A column of the row already stored, inside an upsert's `do update`; the insert aliases the table `stored`. */
+    private column;
+    private conflictTarget;
+    private where;
+}
+//# sourceMappingURL=metrics.store.d.ts.map

package/dist/metrics.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.store.d.ts","sourceRoot":"","sources":["../src/metrics.store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAmB,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAmB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,KAAK,EAAE,QAAQ,CAAC;IAChB,6BAA6B;IAC7B,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,uBAAuB;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,qBAAqB;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,+CAA+C;IAC/C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAuCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY,CAAC,EAAE,GAAG,OAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;OAGG;gBACS,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,mBAAmB;IAOxD;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,MAAM,SAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAoCtF;;;;;;;;;OASG;IACG,UAAU,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBtD;;;;;;;OAOG;IACG,KAAK,CAAC,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,GAAE,QAAyB,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/G;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAoC/D;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAgBpC,iHAAiH;IACjH,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,KAAK;CAGd"}

package/dist/otlp.d.ts

@@ -0,0 +1,4 @@
+export * from './otlp.ids.js';
+export * from './otlp.metrics.bridge.js';
+export * from './otlp.span.bridge.js';
+//# sourceMappingURL=otlp.d.ts.map

package/dist/otlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.d.ts","sourceRoot":"","sources":["../src/otlp.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC"}