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

package/metrics-contract.json

@@ -0,0 +1,174 @@
+{
+  "$comment": "Single source of truth for the Kotlin<->TS metric contract. The Kotlin engine plugin (engine-plugins/cibseven-history-metrics) emits Micrometer meters with these dotted names (otelName - also the OTLP wire name on the push path); the Prometheus normalisation (dots -> underscores, unit suffix `_milliseconds` for unit `ms`, `_total` for monotonic counters) yields promName - identically via the OTEL Collector's Prometheus exporter and via Micrometer's own Prometheus registry - which is what the TS queries (packages/connectors/analytics/analytics-client/src/metric-names.ts), the alert rules (playground/docker/prometheus/alerts.yml) and the Grafana dashboards (playground/docker/grafana/dashboards/*.json) consume. Histograms list the base promName; the `_sum`/`_count`/`_bucket` series are implied. `knownValues` documents label values consumers may rely on. Change a metric HERE first - contract tests on both sides (src/metrics-contract.test.ts, src/metrics-contract-labels.test.ts and MetricsContractTest.kt) enforce consistency. Reading rules every consumer follows (the TS tests check queries, alert rules and dashboards): (1) Durations are whole milliseconds: Micrometer rounds an observation UP to a whole base unit before it picks the bucket, so seconds would empty every sub-second bucket. `buckets` are the explicit bucket bounds in ms the plugin registers. (2) A counter or histogram series is created on its first event, and increase()/rate() never count a series' first sample, so a rare event (the first incident of a type at an activity) would read 0. Read them only as `(increase(X[R]) and present_over_time(X[1h] offset R)) or (max_over_time(X[R]) unless present_over_time(X[1h] offset R))`: a series without a sample in the hour before the window started was born inside it, and its value is the window's count (`increaseIn` in src/queries/helpers.ts). Where the hour before the window lies past the retention, Prometheus deleted it and every series would pass for new: check the window's own first hour instead (a series silent then was born later). (3) Every gauge is an engine-wide figure from an engine query, reported alike by every node of a clustered engine: read it as `max by (<its labels>)(gauge)` before any further aggregation, never a plain sum over nodes. (4) Counters count per node, so every node of an engine exports as its own series: on the OTLP path set a unique `service.instance.id` per node (the Collector's exporter keys series by it), on the Actuator scrape path the target's `instance` label does it.",
+  "metrics": [
+    {
+      "otelName": "camunda.process.instance.started",
+      "promName": "camunda_process_instance_started_total",
+      "type": "counter",
+      "unit": "",
+      "labels": ["process_definition_key", "process_definition_version", "engine_id", "tenant_id"]
+    },
+    {
+      "otelName": "camunda.process.instance.ended",
+      "promName": "camunda_process_instance_ended_total",
+      "type": "counter",
+      "unit": "",
+      "labels": [
+        "process_definition_key",
+        "process_definition_version",
+        "engine_id",
+        "tenant_id",
+        "state"
+      ],
+      "knownValues": {
+        "state": ["COMPLETED", "EXTERNALLY_TERMINATED", "INTERNALLY_TERMINATED"]
+      }
+    },
+    {
+      "otelName": "camunda.process.instance.duration",
+      "promName": "camunda_process_instance_duration_milliseconds",
+      "type": "histogram",
+      "unit": "ms",
+      "labels": ["process_definition_key", "process_definition_version", "engine_id", "tenant_id"],
+      "buckets": [
+        10, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000, 300000, 900000, 3600000,
+        14400000, 43200000, 86400000, 259200000, 604800000, 2592000000
+      ]
+    },
+    {
+      "otelName": "camunda.activity.ended",
+      "promName": "camunda_activity_ended_total",
+      "type": "counter",
+      "unit": "",
+      "labels": ["process_definition_key", "activity_id", "activity_type", "engine_id"]
+    },
+    {
+      "otelName": "camunda.activity.duration",
+      "promName": "camunda_activity_duration_milliseconds",
+      "type": "histogram",
+      "unit": "ms",
+      "labels": ["process_definition_key", "activity_id", "activity_type", "engine_id"],
+      "buckets": [
+        10, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000, 300000, 900000, 3600000,
+        14400000, 43200000, 86400000, 259200000, 604800000, 2592000000
+      ]
+    },
+    {
+      "otelName": "camunda.usertask.created",
+      "promName": "camunda_usertask_created_total",
+      "type": "counter",
+      "unit": "",
+      "labels": ["process_definition_key", "task_definition_key", "engine_id"]
+    },
+    {
+      "otelName": "camunda.usertask.completed",
+      "promName": "camunda_usertask_completed_total",
+      "type": "counter",
+      "unit": "",
+      "labels": ["process_definition_key", "task_definition_key", "engine_id"]
+    },
+    {
+      "otelName": "camunda.usertask.duration",
+      "promName": "camunda_usertask_duration_milliseconds",
+      "type": "histogram",
+      "unit": "ms",
+      "labels": ["process_definition_key", "task_definition_key", "engine_id"],
+      "buckets": [
+        10000, 60000, 300000, 900000, 1800000, 3600000, 14400000, 43200000, 86400000, 259200000,
+        604800000, 1209600000, 2592000000
+      ]
+    },
+    {
+      "otelName": "camunda.incident.created",
+      "promName": "camunda_incident_created_total",
+      "type": "counter",
+      "unit": "",
+      "labels": [
+        "process_definition_key",
+        "process_definition_version",
+        "activity_id",
+        "incident_type",
+        "engine_id"
+      ]
+    },
+    {
+      "otelName": "camunda.incident.resolved",
+      "promName": "camunda_incident_resolved_total",
+      "type": "counter",
+      "unit": "",
+      "labels": [
+        "process_definition_key",
+        "process_definition_version",
+        "activity_id",
+        "incident_type",
+        "engine_id"
+      ]
+    },
+    {
+      "otelName": "camunda.process.instances.running",
+      "promName": "camunda_process_instances_running",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["process_definition_key", "engine_id"]
+    },
+    {
+      "otelName": "camunda.jobs.failed",
+      "promName": "camunda_jobs_failed",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["process_definition_key", "engine_id"]
+    },
+    {
+      "otelName": "camunda.incidents.open",
+      "promName": "camunda_incidents_open",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["process_definition_key", "incident_type", "engine_id"]
+    },
+    {
+      "otelName": "camunda.jobs.executable",
+      "promName": "camunda_jobs_executable",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["engine_id"]
+    },
+    {
+      "otelName": "camunda.jobs.suspended",
+      "promName": "camunda_jobs_suspended",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["engine_id"]
+    },
+    {
+      "otelName": "camunda.jobs.due_future",
+      "promName": "camunda_jobs_due_future",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["engine_id"]
+    },
+    {
+      "otelName": "camunda.usertasks.open",
+      "promName": "camunda_usertasks_open",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["status", "engine_id"],
+      "knownValues": {
+        "status": ["total", "unassigned", "assigned"]
+      }
+    },
+    {
+      "otelName": "camunda.process.definitions.deployed",
+      "promName": "camunda_process_definitions_deployed",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["process_definition_key", "engine_id"]
+    },
+    {
+      "otelName": "camunda.external_tasks.open",
+      "promName": "camunda_external_tasks_open",
+      "type": "gauge",
+      "unit": "",
+      "labels": ["engine_id"]
+    }
+  ]
+}

package/package.json

@@ -1,8 +1,75 @@
 {
   "name": "@miragon/pulse-analytics-client",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder that sets up trusted publishing. The first release of @miragon/pulse-analytics-client is 0.21.0.",
+  "version": "0.21.0",
+  "description": "Prometheus client and PromQL query functions for Camunda process analytics, with Zod schemas.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/Miragon/pulse.git" },
-  "homepage": "https://github.com/Miragon/pulse#readme"
-}
+  "keywords": [
+    "camunda",
+    "prometheus",
+    "promql",
+    "process-analytics",
+    "metrics",
+    "mcp"
+  ],
+  "homepage": "https://github.com/Miragon/pulse/tree/main/packages/connectors/analytics/analytics-client#readme",
+  "bugs": "https://github.com/Miragon/pulse/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Miragon/pulse.git",
+    "directory": "packages/connectors/analytics/analytics-client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "metrics-contract.json"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./queries": {
+      "types": "./dist/queries/index.d.ts",
+      "import": "./dist/queries/index.js"
+    },
+    "./widgets": {
+      "types": "./dist/widgets.d.ts",
+      "import": "./dist/widgets.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.4.0"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@types/node": "26.6.3",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11",
+    "zod": "4.6.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test:mutation": "stryker run"
+  }
+}