@toa.io/atomicity 1.0.0-alpha.301 → 1.0.0-alpha.303

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.303](https://github.com/toa-io/toa/compare/v1.0.0-alpha.302...v1.0.0-alpha.303) (2026-09-12)
+
+### Features
+
+* **metrics:** count what no span reaches ([efabf89](https://github.com/toa-io/toa/commit/efabf89e78f98a604bb939f476a937fc9ee106b3))
+
+
+# [1.0.0-alpha.302](https://github.com/toa-io/toa/compare/v1.0.0-alpha.301...v1.0.0-alpha.302) (2026-09-11)
+
+**Note:** Version bump only for package @toa.io/atomicity
+
+
+
+
+
 # [1.0.0-alpha.301](https://github.com/toa-io/toa/compare/v1.0.0-alpha.300...v1.0.0-alpha.301) (2026-09-11)
 
 **Note:** Version bump only for package @toa.io/atomicity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/atomicity",
-  "version": "1.0.0-alpha.301",
+  "version": "1.0.0-alpha.303",
   "type": "module",
   "description": "Toa Atomicity Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,14 +18,14 @@
   },
   "dependencies": {
     "@sesamecare-oss/redlock": "1.4.0",
-    "@toa.io/core": "1.0.0-alpha.301",
+    "@toa.io/core": "1.0.0-alpha.303",
     "@toa.io/generic": "1.0.0-alpha.301",
     "ioredis": "6.0.0",
     "n-and-i": "0.3.4",
-    "openspan": "1.0.0-alpha.301"
+    "openspan": "1.0.0-alpha.303"
   },
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
-  "gitHead": "cc49bc90efd35464b2ad7803246786c607a44685"
+  "gitHead": "b8e9dd89f6d49756944687a95dfc786f12947286"
 }

package/src/atom.js

@@ -1,6 +1,7 @@
 import { console } from 'openspan'
 import { Connector } from '@toa.io/core'
 import { environment } from '@toa.io/generic'
+import { holding, waited } from './measurements.js'
 
 /**
  * What one group of replicas decides together, in one place: which of them owns what, what they
@@ -119,7 +120,26 @@ export class Atom extends Connector {
     if (redlock === undefined)
       throw new Error('Locking requires atomicity. Set TOA_ATOMICITY_REDIS.')
 
-    return redlock.using(this.#keys(LOCK, keys), LEASE, routine)
+    const started = performance.now()
+    let acquired = false
+
+    return redlock
+      .using(this.#keys(LOCK, keys), LEASE, async (signal) => {
+        // the wait is over once the routine is entered, and what follows it is the work
+        acquired = true
+        waited(this.#name, (performance.now() - started) / 1000)
+        holding(this.#name, 1)
+
+        try {
+          return await routine(signal)
+        } finally {
+          holding(this.#name, -1)
+        }
+      })
+      .finally(() => {
+        // a lock never acquired waited for however long it was refused
+        if (!acquired) waited(this.#name, (performance.now() - started) / 1000)
+      })
   }
 
   /**

package/src/measurements.js

@@ -0,0 +1,30 @@
+import { registry } from 'openspan'
+
+/**
+ * What locking measures.
+ *
+ * `lock()` waits for as long as it takes to acquire its keys, and that wait is inside the
+ * operation that asked for it — so a replica starving on a lock another replica will not release
+ * looks exactly like a busy component. The distribution is the signal, because a mean over waits
+ * that are usually zero says nothing.
+ */
+const meters = registry()
+
+/** From a lock taken at once to one waited out for a minute. */
+const WAITS = [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 15, 60]
+
+const wait = meters.histogram(
+  'toa.atomicity.lock.wait',
+  { buckets: WAITS, unit: 's' },
+  { group: null }
+)
+
+const held = meters.gauge('toa.atomicity.locks', { group: null })
+
+export function waited(group, seconds) {
+  wait.record(seconds, { group })
+}
+
+export function holding(group, delta) {
+  held.add(delta, { group })
+}