@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.3

package/dist/telemetry/metrics/metric-catalog.helpers.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eq = exports.T = exports.LARGEST_TABLES_MAX_ROWS = exports.HOST_TABLES = exports.HOST_FILTERS = exports.APP_FILTERS = exports.METRIC_FILTER_COLUMNS = exports.METRIC_UNITS = void 0;
+const telemetry_1 = require("@marinoscar/platform-contract/telemetry");
+Object.defineProperty(exports, "METRIC_UNITS", { enumerable: true, get: function () { return telemetry_1.METRIC_UNITS; } });
+const telemetry_dashboard_verdict_1 = require("../dashboard/telemetry-dashboard.verdict");
+/**
+ * The request filters a family may honour, and the column each one matches.
+ *
+ * @stability experimental
+ */
+exports.METRIC_FILTER_COLUMNS = {
+    service: 'service_name',
+    instance: 'app_instance_id',
+    host: 'host_name',
+};
+/** API tables (`app_*`): the service and the instance id. Their `host_name` is the API container, not a host. */
+exports.APP_FILTERS = ['service', 'instance'];
+/** Tables the collector scraped itself: `host_name` is the real host. */
+exports.HOST_FILTERS = ['host'];
+exports.HOST_TABLES = {
+    cpuUtilization: 'system_cpu_utilization_ratio',
+    memoryUtilization: 'system_memory_utilization_ratio',
+    load1m: 'system_cpu_load_average_1m',
+    filesystemUtilization: 'system_filesystem_utilization_ratio',
+    filesystemUsage: 'system_filesystem_usage_bytes',
+    diskIo: 'system_disk_io_bytes_total',
+    networkIo: 'system_network_io_bytes_total',
+};
+/** Rows of `largestTables`: every table of a realistic schema; bounded so a runaway schema can't blow the payload (#632). */
+exports.LARGEST_TABLES_MAX_ROWS = 500;
+/** The dashboard's verdict thresholds, which several families declare (documentary). */
+exports.T = telemetry_dashboard_verdict_1.DEFAULT_VERDICT_THRESHOLDS;
+/** A fixed label predicate. Values are catalog constants, never request input. */
+const eq = (column, value) => ({ column, op: '=', value });
+exports.eq = eq;
+//# sourceMappingURL=metric-catalog.helpers.js.map

package/dist/telemetry/metrics/metric-catalog.helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-catalog.helpers.js","sourceRoot":"","sources":["../../../src/telemetry/metrics/metric-catalog.helpers.ts"],"names":[],"mappings":";;;AAAA,uEAAuE;AAwB9D,6FAxBA,wBAAY,OAwBA;AAtBrB,0FAAsF;AAwBtF;;;;GAIG;AACU,QAAA,qBAAqB,GAAoC;IACpE,OAAO,EAAE,cAAc;IACvB,QAAQ,EAAE,iBAAiB;IAC3B,IAAI,EAAE,WAAW;CAClB,CAAC;AAEF,iHAAiH;AACpG,QAAA,WAAW,GAA+B,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAC/E,yEAAyE;AAC5D,QAAA,YAAY,GAA+B,CAAC,MAAM,CAAC,CAAC;AAEpD,QAAA,WAAW,GAAG;IACzB,cAAc,EAAE,8BAA8B;IAC9C,iBAAiB,EAAE,iCAAiC;IACpD,MAAM,EAAE,4BAA4B;IACpC,qBAAqB,EAAE,qCAAqC;IAC5D,eAAe,EAAE,+BAA+B;IAChD,MAAM,EAAE,4BAA4B;IACpC,SAAS,EAAE,+BAA+B;CAClC,CAAC;AAEX,6HAA6H;AAChH,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAE3C,wFAAwF;AAC3E,QAAA,CAAC,GAAG,wDAA0B,CAAC;AAE5C,kFAAkF;AAC3E,MAAM,EAAE,GAAG,CAAC,MAAc,EAAE,KAAa,EAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;AAAtF,QAAA,EAAE,MAAoF"}

package/dist/telemetry/metrics/metric-catalog.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METRIC_TABLES = exports.METRIC_RATIOS = exports.METRIC_FAMILIES = exports.METRIC_GROUP_LABELS = exports.METRIC_GROUPS = exports.HTTPCHECK_ERROR_TABLE = exports.HTTPCHECK_STATUS_TABLE = exports.HOST_DISTINCT_TABLE = exports.METRIC_VALUE_COLUMN = exports.METRIC_TIME_COLUMN = exports.registerMetricGroups = exports.metricGroupRegistry = exports.METRIC_GROUP_ID_PATTERN = exports.METRIC_UNITS = exports.METRIC_FILTER_COLUMNS = exports.LARGEST_TABLES_MAX_ROWS = exports.HOST_TABLES = exports.HOST_FILTERS = exports.eq = exports.APP_FILTERS = void 0;
+exports.metricGroups = metricGroups;
+exports.metricGroupIds = metricGroupIds;
+exports.isMetricGroup = isMetricGroup;
+exports.familiesOf = familiesOf;
+exports.ratiosOf = ratiosOf;
+exports.tablesOf = tablesOf;
+exports.familyByKey = familyByKey;
+exports.metricTablesOf = metricTablesOf;
+exports.tableWith = tableWith;
+require("./metric-group.manifest");
+const metric_catalog_helpers_1 = require("./metric-catalog.helpers");
+const metric_group_registry_1 = require("./metric-group.registry");
+// =============================================================================
+// The metric catalog (issue #601, epic #576)
+// =============================================================================
+//
+// A DECLARATIVE list of the metric families the Telemetry Dashboard reads from
+// the Prometheus-style metric tables the collector and the API write
+// (docs/specs/telemetry.md §11.3 and §11.13), grouped into the platform's six
+// groups (an app may register more):
+//
+//   host      hostmetrics: CPU, memory, load, filesystems, disk and network IO
+//   database  the postgresql receiver: connections, size, commits, cache hits
+//   queue     app.jobs.* and app.backup.*: depth, age, settle rate, duration
+//   nodes     app.nodes.*: fleet health and per-node vitals
+//   uptime    httpcheck and nginx: status per URL, latency, TLS, edge traffic
+//   pipeline  the collector's and GreptimeDB's own counters, and `up`
+//
+// Nothing here runs SQL: `metric-sql.ts` renders a family into a statement,
+// and `metric-group.ts` turns the rows into tiles, series and tables. A family
+// whose table, or one of whose `requiredColumns`, is absent from the store is
+// SKIPPED (reported in `skipped`), never an error: every table appears only
+// once its source has written a row.
+//
+// Every metric table has `greptime_timestamp` (time index) and
+// `greptime_value` (Float64); every other column is a String tag, and a
+// series is one combination of tag values. Semantics:
+//
+//   gauge      a level. Per timestamp the rows are combined across series
+//              (`seriesAggregate`: sum for "how many", max for "the worst"),
+//              then per bucket (`bucketAggregate`).
+//   counter    cumulative (`_total`). The increase between consecutive points
+//              of ONE series (`lag` over every tag column) is summed; a drop
+//              is a reset and counts the new value (Prometheus semantics); the
+//              first point of a series in the window has no predecessor and
+//              contributes nothing (conservative: never an invented spike).
+//   histogram  cumulative `_bucket` counters with a string `le` tag; the
+//              quantile is interpolated from the increases per `le`.
+//
+// API gauges are reported identically by every replica (docs §11.13), so
+// they are never summed across replicas on purpose; replicas export at
+// different instants, so per-timestamp rows rarely mix two replicas.
+//
+// THE GROUPS ARE A REGISTRY (issue #680). Each group is declared in
+// `groups/<id>.metric-group.ts` with its families, ratios and tables, and
+// registered by `metric-group.manifest.ts` (imported above, so any consumer of
+// this file sees the registry filled): the platform's six in the order above,
+// then the app's own (`TelemetryModule.forRoot({ metricGroups })`).
+// This file keeps the shapes, the units, the filter columns, table discovery
+// and the derived views every consumer already imports (`METRIC_GROUPS`,
+// `METRIC_FAMILIES`, `familiesOf`, …).
+// =============================================================================
+var metric_catalog_helpers_2 = require("./metric-catalog.helpers");
+Object.defineProperty(exports, "APP_FILTERS", { enumerable: true, get: function () { return metric_catalog_helpers_2.APP_FILTERS; } });
+Object.defineProperty(exports, "eq", { enumerable: true, get: function () { return metric_catalog_helpers_2.eq; } });
+Object.defineProperty(exports, "HOST_FILTERS", { enumerable: true, get: function () { return metric_catalog_helpers_2.HOST_FILTERS; } });
+Object.defineProperty(exports, "HOST_TABLES", { enumerable: true, get: function () { return metric_catalog_helpers_2.HOST_TABLES; } });
+Object.defineProperty(exports, "LARGEST_TABLES_MAX_ROWS", { enumerable: true, get: function () { return metric_catalog_helpers_2.LARGEST_TABLES_MAX_ROWS; } });
+Object.defineProperty(exports, "METRIC_FILTER_COLUMNS", { enumerable: true, get: function () { return metric_catalog_helpers_2.METRIC_FILTER_COLUMNS; } });
+Object.defineProperty(exports, "METRIC_UNITS", { enumerable: true, get: function () { return metric_catalog_helpers_2.METRIC_UNITS; } });
+var metric_group_registry_2 = require("./metric-group.registry");
+Object.defineProperty(exports, "METRIC_GROUP_ID_PATTERN", { enumerable: true, get: function () { return metric_group_registry_2.METRIC_GROUP_ID_PATTERN; } });
+Object.defineProperty(exports, "metricGroupRegistry", { enumerable: true, get: function () { return metric_group_registry_2.metricGroupRegistry; } });
+Object.defineProperty(exports, "registerMetricGroups", { enumerable: true, get: function () { return metric_group_registry_2.registerMetricGroups; } });
+exports.METRIC_TIME_COLUMN = 'greptime_timestamp';
+exports.METRIC_VALUE_COLUMN = 'greptime_value';
+/** Where `/filters` reads the distinct host names from: small, always written by hostmetrics. */
+exports.HOST_DISTINCT_TABLE = metric_catalog_helpers_1.HOST_TABLES.load1m;
+exports.HTTPCHECK_STATUS_TABLE = 'httpcheck_status';
+exports.HTTPCHECK_ERROR_TABLE = 'httpcheck_error';
+// ---- derived views ---------------------------------------------------------------
+//
+// Snapshots of the registry taken when this module is evaluated, which is
+// after the manifest has registered every platform and app group. The
+// registry is frozen once the application has bootstrapped, so in a running
+// API they never go stale. The lookups below read the registry itself, so a
+// group a test adds with `withTemporaryEntries` is served too.
+function frozen(items) {
+    return Object.freeze(items);
+}
+/**
+ * Every registered group id, in dashboard order. Non-empty (the platform registers six).
+ *
+ * @stability experimental
+ */
+exports.METRIC_GROUPS = Object.freeze(metric_group_registry_1.metricGroupRegistry.ids());
+/**
+ * The API label of every group (the dashboard section title is `MetricGroupDef.title`).
+ *
+ * @stability experimental
+ */
+exports.METRIC_GROUP_LABELS = Object.freeze(Object.fromEntries(metric_group_registry_1.metricGroupRegistry.list().map((g) => [g.id, g.label])));
+exports.METRIC_FAMILIES = frozen(metric_group_registry_1.metricGroupRegistry.list().flatMap((g) => [...g.families]));
+exports.METRIC_RATIOS = frozen(metric_group_registry_1.metricGroupRegistry.list().flatMap((g) => [...(g.ratios ?? [])]));
+exports.METRIC_TABLES = frozen(metric_group_registry_1.metricGroupRegistry.list().flatMap((g) => [...(g.tables ?? [])]));
+// ---- lookups (live) ----------------------------------------------------------------
+/**
+ * Every registered group, in dashboard order, read live from the registry.
+ *
+ * @stability experimental
+ */
+function metricGroups() {
+    return metric_group_registry_1.metricGroupRegistry.list();
+}
+/**
+ * Every registered group id, in dashboard order, read live from the registry.
+ *
+ * @stability experimental
+ */
+function metricGroupIds() {
+    return metric_group_registry_1.metricGroupRegistry.ids();
+}
+/**
+ * Whether `id` names a registered group.
+ *
+ * @stability experimental
+ */
+function isMetricGroup(id) {
+    return typeof id === 'string' && metric_group_registry_1.metricGroupRegistry.has(id);
+}
+function familiesOf(group) {
+    return [...(metric_group_registry_1.metricGroupRegistry.get(group)?.families ?? [])];
+}
+function ratiosOf(group) {
+    return [...(metric_group_registry_1.metricGroupRegistry.get(group)?.ratios ?? [])];
+}
+function tablesOf(group) {
+    return [...(metric_group_registry_1.metricGroupRegistry.get(group)?.tables ?? [])];
+}
+function familyByKey(key) {
+    for (const group of metric_group_registry_1.metricGroupRegistry.list()) {
+        const family = group.families.find((f) => f.key === key);
+        if (family)
+            return family;
+    }
+    return undefined;
+}
+/**
+ * Every table of the schema that looks like a metric table (has the time and
+ * value columns), with its tag columns: `semantic_type = 'TAG'` where the
+ * store reports it, else every column but the time and value.
+ */
+function metricTablesOf(schema) {
+    const tables = new Map();
+    for (const table of schema.tables) {
+        const names = new Set(table.columns.map((c) => c.name));
+        if (!names.has(exports.METRIC_TIME_COLUMN) || !names.has(exports.METRIC_VALUE_COLUMN))
+            continue;
+        const reported = table.columns.some((c) => c.semanticType);
+        const tags = table.columns
+            .filter((c) => reported
+            ? String(c.semanticType).toUpperCase() === 'TAG'
+            : c.name !== exports.METRIC_TIME_COLUMN && c.name !== exports.METRIC_VALUE_COLUMN)
+            .map((c) => c.name)
+            .sort();
+        tables.set(table.name, { columns: names, tags });
+    }
+    return tables;
+}
+/** The table's info when it exists with every required column, else null. */
+function tableWith(tables, table, required) {
+    const info = tables.get(table);
+    if (!info)
+        return null;
+    return required.every((c) => info.columns.has(c)) ? info : null;
+}
+//# sourceMappingURL=metric-catalog.js.map

package/dist/telemetry/metrics/metric-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-catalog.js","sourceRoot":"","sources":["../../../src/telemetry/metrics/metric-catalog.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/metrics/metric-group-registry.service.d.ts

@@ -0,0 +1,59 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { type MetricGroupDef } from './metric-group.registry';
+/**
+ * A dashboard metric group, under the name the platform-packages spec uses
+ * (#703): the same shape as {@link MetricGroupDef} (#680), whose naming wins.
+ *
+ * @stability experimental
+ */
+export type MetricGroupDefinition = MetricGroupDef;
+/**
+ * The dashboard's metric groups: the six platform groups, then the app's,
+ * in dashboard order. Provided by `TelemetryModule.forRoot()`.
+ *
+ * @stability experimental
+ */
+export declare class MetricGroupRegistry implements OnApplicationBootstrap {
+    /**
+     * Adds a group, checked against every group already registered (unique id,
+     * family, ratio and table keys unique across ALL groups, known units and
+     * filters, references to registered families).
+     *
+     * @param definition - the group.
+     * @throws RegistryError `DUPLICATE_ID`, `INVALID_ID`, `INVALID_ENTRY`, or
+     *   `FROZEN` once the application has bootstrapped.
+     *
+     * @extensionPoint registry
+     */
+    register(definition: MetricGroupDefinition): void;
+    /** Every registered group, in dashboard order (`order`, then id): the platform's first. */
+    list(): readonly MetricGroupDefinition[];
+    /**
+     * The group registered under `id`, or `undefined`.
+     *
+     * @param id - the group id (`host`, `coach`, ...).
+     */
+    get(id: string): MetricGroupDefinition | undefined;
+    /** Refuses further registrations once every module's `onModuleInit` has run. */
+    onApplicationBootstrap(): void;
+}
+/**
+ * Registers one metric group; the function form of
+ * {@link MetricGroupRegistry.register}.
+ *
+ * @param registry - the injected registry.
+ * @param definition - the group.
+ * @throws RegistryError as {@link MetricGroupRegistry.register} does.
+ *
+ * @example
+ * ```ts
+ * onModuleInit(): void {
+ *   registerMetricGroup(this.groups, COACH_METRIC_GROUP);
+ * }
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerMetricGroup(registry: MetricGroupRegistry, definition: MetricGroupDefinition): void;
+//# sourceMappingURL=metric-group-registry.service.d.ts.map

package/dist/telemetry/metrics/metric-group-registry.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-group-registry.service.d.ts","sourceRoot":"","sources":["../../../src/telemetry/metrics/metric-group-registry.service.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAc,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzG;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAEnD;;;;;GAKG;AACH,qBACa,mBAAoB,YAAW,sBAAsB;IAChE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI;IAIjD,2FAA2F;IAC3F,IAAI,IAAI,SAAS,qBAAqB,EAAE;IAIxC;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAIlD,gFAAgF;IAChF,sBAAsB,IAAI,IAAI;CAG/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAE1G"}

package/dist/telemetry/metrics/metric-group-registry.service.js

@@ -0,0 +1,99 @@
+"use strict";
+// =============================================================================
+// MetricGroupRegistry: the metric-group registry as an injectable (issue #703,
+// Extension Contract rung 2)
+// =============================================================================
+//
+// A facade over the static `metricGroupRegistry` (./metric-group.registry.ts,
+// #680), NOT a second registry: the dashboard route, its documentation, the
+// assistant's tools and the support bundle all read the one static registry,
+// and this class reads and writes the same one. It exists so an app can add a
+// group the Nest way, from its own `onModuleInit`:
+//
+//   constructor(private readonly groups: MetricGroupRegistry) {}
+//   onModuleInit() { registerMetricGroup(this.groups, COACH_METRIC_GROUP); }
+//
+// The simpler path, and the only one that also puts the group in the
+// `/metrics` route's documented enum, is `TelemetryModule.forRoot({
+// metricGroups })`. Either way the rules are the registry's own: a duplicate
+// id or family key throws (boot fails), and after `onApplicationBootstrap` the
+// registry is frozen and a late `register` throws `FROZEN`.
+//
+// Kept apart from ./metric-group.registry.ts so that file stays
+// framework-free (it is evaluated by the DTOs at import time).
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricGroupRegistry = void 0;
+exports.registerMetricGroup = registerMetricGroup;
+const common_1 = require("@nestjs/common");
+const metric_group_registry_1 = require("./metric-group.registry");
+/**
+ * The dashboard's metric groups: the six platform groups, then the app's,
+ * in dashboard order. Provided by `TelemetryModule.forRoot()`.
+ *
+ * @stability experimental
+ */
+let MetricGroupRegistry = class MetricGroupRegistry {
+    /**
+     * Adds a group, checked against every group already registered (unique id,
+     * family, ratio and table keys unique across ALL groups, known units and
+     * filters, references to registered families).
+     *
+     * @param definition - the group.
+     * @throws RegistryError `DUPLICATE_ID`, `INVALID_ID`, `INVALID_ENTRY`, or
+     *   `FROZEN` once the application has bootstrapped.
+     *
+     * @extensionPoint registry
+     */
+    register(definition) {
+        (0, metric_group_registry_1.registerMetricGroups)([definition]);
+    }
+    /** Every registered group, in dashboard order (`order`, then id): the platform's first. */
+    list() {
+        return metric_group_registry_1.metricGroupRegistry.list();
+    }
+    /**
+     * The group registered under `id`, or `undefined`.
+     *
+     * @param id - the group id (`host`, `coach`, ...).
+     */
+    get(id) {
+        return metric_group_registry_1.metricGroupRegistry.get(id);
+    }
+    /** Refuses further registrations once every module's `onModuleInit` has run. */
+    onApplicationBootstrap() {
+        metric_group_registry_1.metricGroupRegistry.freeze();
+    }
+};
+exports.MetricGroupRegistry = MetricGroupRegistry;
+exports.MetricGroupRegistry = MetricGroupRegistry = __decorate([
+    (0, common_1.Injectable)()
+], MetricGroupRegistry);
+/**
+ * Registers one metric group; the function form of
+ * {@link MetricGroupRegistry.register}.
+ *
+ * @param registry - the injected registry.
+ * @param definition - the group.
+ * @throws RegistryError as {@link MetricGroupRegistry.register} does.
+ *
+ * @example
+ * ```ts
+ * onModuleInit(): void {
+ *   registerMetricGroup(this.groups, COACH_METRIC_GROUP);
+ * }
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerMetricGroup(registry, definition) {
+    registry.register(definition);
+}
+//# sourceMappingURL=metric-group-registry.service.js.map

package/dist/telemetry/metrics/metric-group-registry.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-group-registry.service.js","sourceRoot":"","sources":["../../../src/telemetry/metrics/metric-group-registry.service.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+EAA+E;AAC/E,6BAA6B;AAC7B,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AAC9E,mDAAmD;AACnD,EAAE;AACF,iEAAiE;AACjE,6EAA6E;AAC7E,EAAE;AACF,qEAAqE;AACrE,oEAAoE;AACpE,6EAA6E;AAC7E,+EAA+E;AAC/E,4DAA4D;AAC5D,EAAE;AACF,gEAAgE;AAChE,+DAA+D;AAC/D,gFAAgF;;;;;;;;;AA2EhF,kDAEC;AA3ED,2CAAoE;AAEpE,mEAAyG;AAUzG;;;;;GAKG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAiC;QACxC,IAAA,4CAAoB,EAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,2FAA2F;IAC3F,IAAI;QACF,OAAO,2CAAmB,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,2CAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,gFAAgF;IAChF,sBAAsB;QACpB,2CAAmB,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;CACF,CAAA;AAlCY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;GACA,mBAAmB,CAkC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,mBAAmB,CAAC,QAA6B,EAAE,UAAiC;IAClG,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAChC,CAAC"}

package/dist/telemetry/metrics/metric-group.d.ts

@@ -0,0 +1,113 @@
+import type { DashboardSqlFilters } from '../dashboard/telemetry-dashboard.sql';
+import type { TelemetryQueryResult } from '../greptime/greptime.client';
+import { type MetricFamily, type MetricGroup, type MetricTables, type MetricTableSpec, type MetricUnit } from './metric-catalog';
+import { type LatestPart } from './metric-sql';
+/**
+ * The default freshness window: a `last` table cell older than its part's
+ * newest reading by more than this is not current. An app changes it with
+ * `TelemetryModule.forRoot({ metrics: { freshMs } })`.
+ *
+ * @stability experimental
+ */
+export declare const METRIC_FRESH_MS = 150000;
+/**
+ * The window one metric group is computed over, and the previous window of
+ * equal length it is compared with.
+ *
+ * @stability experimental
+ */
+export interface MetricGroupWindow {
+    /** The window's start. */
+    from: Date;
+    /** Its end. */
+    to: Date;
+    /** The previous window's start (it ends at `from`). */
+    previousFrom: Date;
+    /** The dashboard's bucket size; metric statements use at least `METRIC_MIN_BUCKET_SECONDS`. */
+    bucketSeconds: number;
+}
+export interface MetricRunner {
+    maybe(sql: string | null): Promise<TelemetryQueryResult | null>;
+}
+export interface MetricTile {
+    key: string;
+    label: string;
+    value: number | string | null;
+    previous: number | string | null;
+    unit: string;
+    sparkline: (number | null)[];
+}
+export interface MetricSeries {
+    key: string;
+    label: string;
+    unit: MetricUnit;
+    /** The label column the series is split by, or null for a single series. */
+    dimension: string | null;
+    /** This series' value of `dimension`, or null. */
+    groupBy: string | null;
+    points: {
+        t: string;
+        v: number | null;
+    }[];
+}
+export type MetricCell = string | number | boolean | null;
+export interface MetricTableColumn {
+    key: string;
+    label: string;
+    unit: MetricUnit;
+}
+export interface MetricTable {
+    key: string;
+    label: string;
+    columns: MetricTableColumn[];
+    rows: Record<string, MetricCell>[];
+}
+export interface MetricGroupResult {
+    bucketSeconds: number;
+    available: boolean;
+    truncated: boolean;
+    tiles: MetricTile[];
+    series: MetricSeries[];
+    tables: MetricTable[];
+    skipped: string[];
+}
+export declare function metricBucketSeconds(bucketSeconds: number): number;
+type Buckets = Map<number, number>;
+interface FamilyData {
+    family: MetricFamily;
+    /** group value → bucket start (ms) → raw value (a counter's increase in that bucket). */
+    groups: Map<string, Buckets>;
+    /** Histograms: period → group → `le` → cumulative count increase. */
+    histogram?: Map<string, Map<string, Map<string, number>>>;
+}
+/** A table spec's parts as latest-per-key statement parts (also read by the telemetry assistant, #603). */
+export declare function tableParts(spec: MetricTableSpec, tables: MetricTables): LatestPart[];
+export interface TableInputs {
+    latest: TelemetryQueryResult | null;
+    status?: TelemetryQueryResult | null;
+    errors?: TelemetryQueryResult | null;
+    histogram?: FamilyData | null;
+    /** The freshness window in milliseconds; default `METRIC_FRESH_MS`. */
+    freshMs?: number;
+}
+/** One per-key table from its statements' rows (also used by the telemetry assistant, #603). */
+export declare function buildTable(spec: MetricTableSpec, inputs: TableInputs): {
+    table: MetricTable;
+    truncated: boolean;
+};
+/**
+ * Every statement of the group, run at once through `runner`, shaped into the
+ * group response (minus the envelope). `now` is the request's clock;
+ * `freshMs` the tables' freshness window (default `METRIC_FRESH_MS`).
+ */
+export declare function computeMetricGroup(input: {
+    group: MetricGroup;
+    window: MetricGroupWindow;
+    filters: DashboardSqlFilters;
+    tables: MetricTables;
+    runner: MetricRunner;
+    now: Date;
+    freshMs?: number;
+}): Promise<MetricGroupResult>;
+export {};
+//# sourceMappingURL=metric-group.d.ts.map

package/dist/telemetry/metrics/metric-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-group.d.ts","sourceRoot":"","sources":["../../../src/telemetry/metrics/metric-group.ts"],"names":[],"mappings":"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"}