@miragon/pulse-analytics-client 0.0.0-bootstrap.0 → 0.21.0

package/dist/queries/engine-landscape.js

@@ -0,0 +1,183 @@
+import { engineMatcher, selector, } from "../prometheus.js";
+import { METRIC_NAMES as M } from "../metric-names.js";
+import { asOfNow, engineState } from "./helpers.js";
+/** A per-key gauge summed per (engine, key) — `incidents_open` also carries a type. */
+const byKey = (gauge, sel) => `sum by (engine_id, process_definition_key)(${engineState(gauge, sel)})`;
+/**
+ * Cross-engine landscape: what runs where, how much of it, and which engines
+ * carry a backlog.
+ *
+ * Deliberately NOT an engine-vs-engine scoreboard. Rates (failure rate,
+ * incident rate, duration) aggregated per engine measure that engine's PROCESS
+ * MIX, not the engine: an engine hosting an inherently error-prone process
+ * reads "unhealthy" while running perfectly. So this query reports the two
+ * things that survive a different mix per engine:
+ *
+ *  1. Absolute counts (running instances, open incidents, failed jobs) — they
+ *     say where work and trouble physically sit, which is what an operator
+ *     acts on, and they stay additive across engines.
+ *  2. The engine-owned backlog gauges (`jobs_executable`, `jobs_suspended`,
+ *     `jobs_due_future`, `external_tasks_open`), whose contract labels are
+ *     `engine_id` ONLY. With no process dimension there is no mix to confound
+ *     them, so these genuinely do rank engines against each other.
+ *
+ * The inventory matrix then names the one place a KPI comparison IS sound: a
+ * process definition key present on two or more engines (`sharedProcessKeys`)
+ * — the drill-down {@link engineCompare} requires.
+ *
+ * Pass `engine` as the array of CONFIGURED engine ids to also surface engines
+ * that report nothing (`reporting: false`); without it the landscape can only
+ * show engines Prometheus has series for.
+ */
+export async function engineLandscape(ch, params = {}) {
+    const asOf = asOfNow();
+    const sel = selector(engineMatcher(params.engine));
+    // One `sum by (…)` per gauge over its node-folded rows — the joining
+    // happens in TS.
+    const [deployed, running, incidents, failedJobs, executable, suspended, dueFuture, externalTasks,] = await Promise.all([
+        ch.instant(byKey(M.processDefinitionsDeployed, sel)),
+        ch.instant(byKey(M.processInstancesRunning, sel)),
+        ch.instant(byKey(M.incidentsOpen, sel)),
+        ch.instant(byKey(M.jobsFailed, sel)),
+        ch.instant(engineState(M.jobsExecutable, sel)),
+        ch.instant(engineState(M.jobsSuspended, sel)),
+        ch.instant(engineState(M.jobsDueFuture, sel)),
+        ch.instant(engineState(M.externalTasksOpen, sel)),
+    ]);
+    const deployedCells = cells(deployed);
+    const runningCells = cells(running);
+    const incidentCells = cells(incidents);
+    const failedCells = cells(failedJobs);
+    // A key counts as present on an engine when it is deployed there OR still has
+    // live state there — a key undeployed while instances keep running would
+    // otherwise drop out of the matrix that is supposed to explain them.
+    const presence = [...deployedCells, ...runningCells, ...incidentCells, ...failedCells];
+    // Every engine id seen anywhere, plus the ones the caller declared — so a
+    // silent engine gets a row instead of vanishing from the overview.
+    const reporting = new Set([deployed, running, incidents, failedJobs, executable, suspended, dueFuture, externalTasks]
+        .flat()
+        .map((s) => s.metric.engine_id)
+        .filter((id) => !!id));
+    const engineIds = [...new Set([...expectedEngineIds(params.engine), ...reporting])].sort();
+    const keysOn = (engineId) => [
+        ...new Set(presence.filter((c) => c.engineId === engineId).map((c) => c.processDefinitionKey)),
+    ];
+    const enginesWithKey = (key) => [
+        ...new Set(presence.filter((c) => c.processDefinitionKey === key).map((c) => c.engineId)),
+    ].sort();
+    const engines = engineIds.map((engineId) => {
+        if (!reporting.has(engineId))
+            return silentEngine(engineId);
+        const keys = keysOn(engineId);
+        return {
+            engineId,
+            reporting: true,
+            runningInstances: sumBy(runningCells, (c) => c.engineId === engineId),
+            openIncidents: sumBy(incidentCells, (c) => c.engineId === engineId),
+            failedJobs: sumBy(failedCells, (c) => c.engineId === engineId),
+            executableJobs: engineValue(executable, engineId),
+            suspendedJobs: engineValue(suspended, engineId),
+            jobsDueFuture: engineValue(dueFuture, engineId),
+            openExternalTasks: engineValue(externalTasks, engineId),
+            deployedDefinitionKeys: keys.length,
+            exclusiveDefinitionKeys: keys.filter((k) => enginesWithKey(k).length === 1).length,
+        };
+    });
+    const processes = [
+        ...new Set(presence.map((c) => c.processDefinitionKey)),
+    ]
+        .map((processDefinitionKey) => {
+        const on = enginesWithKey(processDefinitionKey);
+        const runningByEngine = {};
+        for (const engineId of on) {
+            const value = sumBy(runningCells, (c) => c.engineId === engineId && c.processDefinitionKey === processDefinitionKey);
+            if (value !== 0)
+                runningByEngine[engineId] = value;
+        }
+        const forKey = (list) => sumBy(list, (c) => c.processDefinitionKey === processDefinitionKey);
+        return {
+            processDefinitionKey,
+            engineIds: on,
+            shared: on.length > 1,
+            runningByEngine,
+            runningTotal: forKey(runningCells),
+            openIncidentsTotal: forKey(incidentCells),
+            failedJobsTotal: forKey(failedCells),
+        };
+    })
+        // Shared keys lead: they are the only rows offering a valid comparison.
+        .sort((a, b) => Number(b.shared) - Number(a.shared) ||
+        b.runningTotal - a.runningTotal ||
+        a.processDefinitionKey.localeCompare(b.processDefinitionKey));
+    const sharedProcessKeys = processes.filter((p) => p.shared).map((p) => p.processDefinitionKey);
+    const reportingEngineCount = engines.filter((e) => e.reporting).length;
+    /** A total over the reporting engines; unknown (null) while none reports. */
+    const total = (list) => (reportingEngineCount > 0 ? sumBy(list, () => true) : null);
+    return {
+        asOf,
+        engines,
+        processes,
+        sharedProcessKeys,
+        totals: {
+            engineCount: engines.length,
+            reportingEngineCount,
+            processKeyCount: processes.length,
+            sharedProcessKeyCount: sharedProcessKeys.length,
+            runningInstances: total(runningCells),
+            openIncidents: total(incidentCells),
+            failedJobs: total(failedCells),
+        },
+    };
+}
+/**
+ * The row of a declared engine that sent no series at all: every count is
+ * unknown. A row of zeros would read as an idle, healthy engine.
+ */
+function silentEngine(engineId) {
+    return {
+        engineId,
+        reporting: false,
+        runningInstances: null,
+        openIncidents: null,
+        failedJobs: null,
+        executableJobs: null,
+        suspendedJobs: null,
+        jobsDueFuture: null,
+        openExternalTasks: null,
+        deployedDefinitionKeys: null,
+        exclusiveDefinitionKeys: null,
+    };
+}
+/** The engine ids the caller declared, so silent engines still get a row. */
+function expectedEngineIds(engine) {
+    if (engine === undefined || engine === null)
+        return [];
+    const ids = Array.isArray(engine) ? engine : [engine];
+    return ids.filter((id) => id.length > 0);
+}
+/**
+ * `(engine_id, process_definition_key)` samples as flat cells, dropping any
+ * sample missing either label. Values are rounded — every source gauge is an
+ * integer count.
+ *
+ * The `sum by (engine_id, process_definition_key)` above already folds every
+ * extra dimension away (`incidents_open` carries an `incident_type`), so
+ * Prometheus returns exactly ONE sample per pair. The `sumBy` callers therefore
+ * add across pairs — all keys of one engine, or all engines of one key — never
+ * within a pair.
+ */
+function cells(samples) {
+    const out = [];
+    for (const s of samples) {
+        const engineId = s.metric.engine_id;
+        const processDefinitionKey = s.metric.process_definition_key;
+        if (!engineId || !processDefinitionKey)
+            continue;
+        out.push({ engineId, processDefinitionKey, value: Math.round(s.value) });
+    }
+    return out;
+}
+const sumBy = (list, match) => list.reduce((sum, c) => (match(c) ? sum + c.value : sum), 0);
+/** Value of the `sum by (engine_id)` sample for one engine, or 0 when absent. */
+const engineValue = (samples, engineId) => Math.round(samples.find((s) => s.metric.engine_id === engineId)?.value ?? 0);
+//# sourceMappingURL=engine-landscape.js.map

package/dist/queries/engine-landscape.js.map

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

package/dist/queries/engine-landscape.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine-landscape.test.d.ts.map

package/dist/queries/engine-landscape.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-landscape.test.d.ts","sourceRoot":"","sources":["../../src/queries/engine-landscape.test.ts"],"names":[],"mappings":""}

package/dist/queries/engine-landscape.test.js

@@ -0,0 +1,171 @@
+import { describe, expect, it, vi } from "vitest";
+import { engineLandscape } from "./engine-landscape.js";
+const cell = (engine_id, process_definition_key, value) => ({
+    metric: { engine_id, process_definition_key },
+    value,
+});
+const gauge = (engine_id, value) => ({ metric: { engine_id }, value });
+/**
+ * Two engines with a partly overlapping process landscape: `order` runs on
+ * both (the only comparable key), `invoice` only on prod-a, `onboarding` only
+ * on prod-b.
+ */
+function mockClient() {
+    const instant = vi.fn(async (q) => {
+        if (q.includes("process_definitions_deployed")) {
+            return [
+                cell("prod-a", "order", 3),
+                cell("prod-a", "invoice", 1),
+                cell("prod-b", "order", 2),
+                cell("prod-b", "onboarding", 1),
+            ];
+        }
+        if (q.includes("process_instances_running")) {
+            return [
+                cell("prod-a", "order", 5),
+                cell("prod-a", "invoice", 2),
+                cell("prod-b", "order", 7),
+                cell("prod-b", "onboarding", 4),
+            ];
+        }
+        if (q.includes("incidents_open")) {
+            // `sum by (engine_id, process_definition_key)` folds `incident_type`
+            // away, so there is one sample per pair however many types produced it.
+            return [cell("prod-a", "order", 3), cell("prod-b", "onboarding", 4)];
+        }
+        if (q.includes("jobs_failed"))
+            return [cell("prod-a", "order", 3)];
+        if (q.includes("jobs_executable"))
+            return [gauge("prod-a", 12), gauge("prod-b", 40)];
+        if (q.includes("jobs_suspended"))
+            return [gauge("prod-b", 2)];
+        if (q.includes("jobs_due_future"))
+            return [gauge("prod-a", 8)];
+        if (q.includes("external_tasks_open"))
+            return [gauge("prod-b", 6)];
+        return [];
+    });
+    const ch = { instant };
+    return { ch, instant };
+}
+describe("engineLandscape", () => {
+    it("reports absolute load and the engine-owned backlog per engine", async () => {
+        const { ch } = mockClient();
+        const res = await engineLandscape(ch);
+        expect(res.engines).toEqual([
+            {
+                engineId: "prod-a",
+                reporting: true,
+                runningInstances: 7,
+                openIncidents: 3,
+                failedJobs: 3,
+                executableJobs: 12,
+                suspendedJobs: 0,
+                jobsDueFuture: 8,
+                openExternalTasks: 0,
+                deployedDefinitionKeys: 2,
+                exclusiveDefinitionKeys: 1, // invoice
+            },
+            {
+                engineId: "prod-b",
+                reporting: true,
+                runningInstances: 11,
+                openIncidents: 4,
+                failedJobs: 0,
+                executableJobs: 40,
+                suspendedJobs: 2,
+                jobsDueFuture: 0,
+                openExternalTasks: 6,
+                deployedDefinitionKeys: 2,
+                exclusiveDefinitionKeys: 1, // onboarding
+            },
+        ]);
+    });
+    it("marks only the process deployed on more than one engine as shared", async () => {
+        const { ch } = mockClient();
+        const res = await engineLandscape(ch);
+        expect(res.sharedProcessKeys).toEqual(["order"]);
+        // Shared keys sort first, then by running instances descending.
+        expect(res.processes.map((p) => p.processDefinitionKey)).toEqual([
+            "order",
+            "onboarding",
+            "invoice",
+        ]);
+        expect(res.processes[0]).toEqual({
+            processDefinitionKey: "order",
+            engineIds: ["prod-a", "prod-b"],
+            shared: true,
+            runningByEngine: { "prod-a": 5, "prod-b": 7 },
+            runningTotal: 12,
+            openIncidentsTotal: 3,
+            failedJobsTotal: 3,
+        });
+        expect(res.processes[2]).toMatchObject({
+            processDefinitionKey: "invoice",
+            engineIds: ["prod-a"],
+            shared: false,
+        });
+    });
+    it("totals the landscape without double counting", async () => {
+        const { ch } = mockClient();
+        const res = await engineLandscape(ch);
+        expect(res.totals).toEqual({
+            engineCount: 2,
+            reportingEngineCount: 2,
+            processKeyCount: 3,
+            sharedProcessKeyCount: 1,
+            runningInstances: 18,
+            openIncidents: 7,
+            failedJobs: 3,
+        });
+    });
+    it("keeps a configured engine that reports no metrics visible", async () => {
+        const { ch } = mockClient();
+        const res = await engineLandscape(ch, { engine: ["prod-a", "prod-b", "prod-c"] });
+        const silent = res.engines.find((e) => e.engineId === "prod-c");
+        // Unknown, not zero: a row of 0s would read as an idle, healthy engine.
+        expect(silent).toEqual({
+            engineId: "prod-c",
+            reporting: false,
+            runningInstances: null,
+            openIncidents: null,
+            failedJobs: null,
+            executableJobs: null,
+            suspendedJobs: null,
+            jobsDueFuture: null,
+            openExternalTasks: null,
+            deployedDefinitionKeys: null,
+            exclusiveDefinitionKeys: null,
+        });
+        // The totals add up the engines that report.
+        expect(res.totals).toMatchObject({
+            engineCount: 3,
+            reportingEngineCount: 2,
+            runningInstances: 18,
+            openIncidents: 7,
+        });
+    });
+    it("scopes every query by the engine filter", async () => {
+        const { ch, instant } = mockClient();
+        await engineLandscape(ch, { engine: ["prod-a", "prod-b"] });
+        const queries = instant.mock.calls.map((c) => c[0]);
+        expect(queries).toHaveLength(8);
+        expect(queries.every((q) => q.includes('{engine_id=~"prod-a|prod-b"}'))).toBe(true);
+        // The four process-scoped metrics group by both labels, the four
+        // engine-owned gauges by engine_id only.
+        expect(queries.filter((q) => q.includes("by (engine_id, process_definition_key)"))).toHaveLength(4);
+    });
+    it("returns an empty landscape instead of failing when nothing reports", async () => {
+        const res = await engineLandscape({ instant: async () => [] });
+        expect(res.engines).toEqual([]);
+        expect(res.processes).toEqual([]);
+        expect(res.totals).toMatchObject({
+            engineCount: 0,
+            processKeyCount: 0,
+            runningInstances: null,
+            openIncidents: null,
+            failedJobs: null,
+        });
+    });
+});
+//# sourceMappingURL=engine-landscape.test.js.map

package/dist/queries/engine-landscape.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-landscape.test.js","sourceRoot":"","sources":["../../src/queries/engine-landscape.test.ts"],"names":[],"mappings":"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"}

package/dist/queries/failures.d.ts

@@ -0,0 +1,33 @@
+import { type EngineFilterInput, type PrometheusClient } from "../prometheus.js";
+/**
+ * One group of currently-open incidents. Only what the `camunda_incidents_open`
+ * gauge carries: no message, activity, timestamps or instance ids exist on it.
+ */
+export interface ErrorPatternRow {
+    incident_type: string;
+    process_definition_key: string;
+    incident_count: number;
+}
+export interface FailedInstancesResult {
+    /** The engine ids covered; `null` = every engine Prometheus holds (unscoped library call). */
+    engines: string[] | null;
+    /** Open-incident groups, largest first, capped at `maxResults`. */
+    patterns: ErrorPatternRow[];
+}
+/**
+ * Currently-open incident groups, from the `camunda_incidents_open` state
+ * gauge — grouped by `incident_type` + definition. Point-in-time ("what is
+ * failing now"), so it is robust regardless of how the data arrived (live or
+ * a backdated/bulk import, which no counter window sees).
+ *
+ * The gauge carries no incident message, activity id, timestamps or instance
+ * ids, so the rows carry none either. For the actual failed instances drill
+ * in with `camunda7_list_incidents` / `camunda7_query_historic_incidents`.
+ */
+export declare function findFailedInstances(ch: PrometheusClient, params: {
+    processDefinitionKey?: string;
+    incidentType?: string;
+    maxResults: number;
+    engine?: EngineFilterInput;
+}): Promise<FailedInstancesResult>;
+//# sourceMappingURL=failures.d.ts.map

package/dist/queries/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../../src/queries/failures.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AAIzB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACxB,mEAAmE;IACnE,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE;IACN,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B,GACA,OAAO,CAAC,qBAAqB,CAAC,CAwBhC"}

package/dist/queries/failures.js

@@ -0,0 +1,31 @@
+import { engineIdsOf, engineMatcher, escapeLabelValue, selector, } from "../prometheus.js";
+import { METRIC_NAMES as M } from "../metric-names.js";
+import { engineState } from "./helpers.js";
+/**
+ * Currently-open incident groups, from the `camunda_incidents_open` state
+ * gauge — grouped by `incident_type` + definition. Point-in-time ("what is
+ * failing now"), so it is robust regardless of how the data arrived (live or
+ * a backdated/bulk import, which no counter window sees).
+ *
+ * The gauge carries no incident message, activity id, timestamps or instance
+ * ids, so the rows carry none either. For the actual failed instances drill
+ * in with `camunda7_list_incidents` / `camunda7_query_historic_incidents`.
+ */
+export async function findFailedInstances(ch, params) {
+    const limit = Math.max(1, Math.floor(params.maxResults));
+    const sel = selector(params.processDefinitionKey
+        ? `process_definition_key="${escapeLabelValue(params.processDefinitionKey)}"`
+        : undefined, params.incidentType ? `incident_type="${escapeLabelValue(params.incidentType)}"` : undefined, engineMatcher(params.engine));
+    const samples = await ch.instant(`sum by (process_definition_key, incident_type)(${engineState(M.incidentsOpen, sel)})`);
+    const patterns = samples
+        .map((s) => ({
+        incident_type: s.metric.incident_type ?? "",
+        process_definition_key: s.metric.process_definition_key ?? "",
+        incident_count: Math.round(s.value),
+    }))
+        .filter((r) => r.incident_count > 0)
+        .sort((a, b) => b.incident_count - a.incident_count)
+        .slice(0, limit);
+    return { engines: engineIdsOf(params.engine), patterns };
+}
+//# sourceMappingURL=failures.js.map

package/dist/queries/failures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.js","sourceRoot":"","sources":["../../src/queries/failures.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,QAAQ,GAGT,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,IAAI,CAAC,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAmB1C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,EAAoB,EACpB,MAKC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;IACxD,MAAM,GAAG,GAAG,QAAQ,CAClB,MAAM,CAAC,oBAAoB;QACzB,CAAC,CAAC,2BAA2B,gBAAgB,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG;QAC7E,CAAC,CAAC,SAAS,EACb,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,gBAAgB,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAC5F,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAC7B,CAAA;IAED,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAC9B,kDAAkD,WAAW,CAAC,CAAC,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG,CACvF,CAAA;IAED,MAAM,QAAQ,GAAG,OAAO;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE;QAC3C,sBAAsB,EAAE,CAAC,CAAC,MAAM,CAAC,sBAAsB,IAAI,EAAE;QAC7D,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;KACpC,CAAC,CAAC;SACF,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC;SACnC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;SACnD,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IAClB,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;AAC1D,CAAC"}

package/dist/queries/health.d.ts

@@ -0,0 +1,77 @@
+import { type EngineFilterInput, type PrometheusClient } from "../prometheus.js";
+export interface HealthCount {
+    label: string;
+    count: number;
+}
+export interface HealthAlert {
+    name: string;
+    severity: string;
+    scope: string;
+}
+/**
+ * Name pattern (RE2) of the alert rules this module ships
+ * (`playground/docker/prometheus/alerts.yml`). An alert WITHOUT an
+ * `engine_id` label — a pipeline-level rule such as `CibSevenEngineNoMetrics`
+ * — only counts when it matches this pattern: in a shared Prometheus every
+ * other engine-less alert belongs to somebody else.
+ */
+export declare const ENGINE_ALERT_NAME_PATTERN = "CibSeven.+";
+/**
+ * How {@link engineHealth} decides `status`, in words — carried in every
+ * result (`statusRule`) and the tool description, so no reader mistakes this
+ * alert-based verdict for camunda7_show_engine_health's incident-count one:
+ * the two judge different data by different rules and may disagree for the
+ * same engine (500 open incidents without a firing critical alert stay
+ * "degraded" here).
+ */
+export declare const ENGINE_HEALTH_STATUS_RULE = "From Prometheus, over the engines in scope: unknown when none of them reports metrics; critical only while a severity=critical alert fires for them (fleet-wide also an engine-less CibSeven* alert); degraded with any such firing alert, dead job, open incident or an engine in scope that reports nothing; else healthy.";
+export interface EngineHealthResult {
+    status: "healthy" | "degraded" | "critical" | "unknown";
+    /** How `status` was decided ({@link ENGINE_HEALTH_STATUS_RULE}). */
+    statusRule: string;
+    /** The engine ids judged; `null` = every engine Prometheus holds (unscoped library call). */
+    engines: string[] | null;
+    /**
+     * Engines with a live engine-state gauge — Prometheus' 5-minute staleness
+     * window makes "present" mean "reported within the last minutes".
+     */
+    reportingEngines: string[];
+    /**
+     * Engines in scope that report nothing: the metrics plugin or collector is
+     * down, or the engine's `ENGINE_ID` does not match. Every count below reads
+     * 0 for them — not because they are idle.
+     */
+    silentEngines: string[];
+    runningInstances: number;
+    runningByDefinition: HealthCount[];
+    openIncidents: number;
+    openIncidentsByType: HealthCount[];
+    deadJobs: number;
+    executableJobs: number;
+    suspendedJobs: number;
+    openUserTasks: number;
+    unassignedUserTasks: number;
+    openExternalTasks: number;
+    deployedDefinitionKeys: number;
+    firingAlerts: HealthAlert[];
+    pendingAlerts: HealthAlert[];
+}
+/**
+ * Live operational health of the engine(s), from the point-in-time gauges plus
+ * Prometheus' own `ALERTS` series. A one-call ops snapshot: running WIP, open
+ * incidents, dead jobs, job/task/external-task backlog, and which alert rules
+ * are firing/pending.
+ *
+ * Absence is not health: the engine-only gauges (`jobs_executable`,
+ * `external_tasks_open`) double as the presence probe, so an engine that
+ * sends nothing — or an id that matches no series — reads `unknown` (none in
+ * scope reports) or lands in `silentEngines` (degrading the verdict), never
+ * `healthy`. `includeFleetAlerts` (default: exactly when `engine` is
+ * omitted) adds the module's engine-less alerts — set it when `engine` lists
+ * the whole configured fleet.
+ */
+export declare function engineHealth(ch: PrometheusClient, params: {
+    engine?: EngineFilterInput;
+    includeFleetAlerts?: boolean;
+}): Promise<EngineHealthResult>;
+//# sourceMappingURL=health.d.ts.map

package/dist/queries/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/queries/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAEtB,MAAM,kBAAkB,CAAA;AAIzB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAA;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,iUAC0R,CAAA;AAEhU,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAA;IACvD,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAClB,6FAA6F;IAC7F,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACxB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,EAAE,WAAW,EAAE,CAAA;IAClC,aAAa,EAAE,MAAM,CAAA;IACrB,mBAAmB,EAAE,WAAW,EAAE,CAAA;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,iBAAiB,EAAE,MAAM,CAAA;IACzB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,aAAa,EAAE,WAAW,EAAE,CAAA;CAC7B;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GACnE,OAAO,CAAC,kBAAkB,CAAC,CAqF7B"}