velocious 1.0.710 → 1.0.712

package/src/configuration-types.js

@@ -85,7 +85,7 @@
 /**
  * @typedef {object} DatabaseConfigurationType
  * @property {number | null} [advisoryLockAcquireTimeoutMs] - Bound (ms) a blocking advisory-lock acquisition waits for a contended lock before reporting failure. Default: `900000` (15 minutes). `null` opts out and restores the driver's indefinite wait. A per-call `timeoutMs` argument always overrides this.
- * @property {{slowAcquireMs?: number | null, slowHoldMs?: number | null}} [advisoryLockTelemetry] - Event-driven advisory-lock duration telemetry thresholds. `slowAcquireMs` (default `5000`) reports an acquire wait that completed slower than the threshold, including the eventual outcome; `advisory-lock-acquire-timeout` always fires when a wait exceeds its bound and carries the holder identity available on the tier at that moment. `slowHoldMs` (default `60000`) reports a hold that outlives the threshold at release. `null` disables that report. Reports fire on the events themselves — no periodic scanner — on `getErrorEvents()` as `framework-error` with `context: "advisory-lock-telemetry"`. See [docs/advisory-locks.md](../docs/advisory-locks.md).
+ * @property {{slowAcquireMs?: number | null, slowHoldMs?: number | null}} [advisoryLockTelemetry] - Event-driven advisory-lock duration telemetry thresholds. `slowAcquireMs` (default `5000`) reports an acquire wait that completed slower than the threshold, including the eventual outcome; `advisory-lock-acquire-timeout` always fires when a wait exceeds its bound and carries the holder identity available on the tier at that moment. `slowHoldMs` (default `60000`) reports a hold that outlives the threshold at release. `null` disables that report. Reports fire on the events themselves — no periodic scanner — on `getTelemetryEvents()` as `telemetry` with `context: "advisory-lock-telemetry"`. See [docs/advisory-locks.md](../docs/advisory-locks.md).
  * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
  * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
  * @property {string} [database] - Database name for this connection.

package/src/configuration.js

@@ -525,6 +525,7 @@ export default class VelociousConfiguration {
      * @type {WeakSet<object>} */
     this._appliedRouteMounts = new WeakSet()
     this._errorEvents = new EventEmitter()
+    this._telemetryEvents = new EventEmitter()
 
     /**
      * Stores the database pools value.
@@ -3865,6 +3866,19 @@ export default class VelociousConfiguration {
     return this._errorEvents
   }
 
+  /**
+   * Framework telemetry emitter. Telemetry reports measurements — lock contention,
+   * slow queries, queue depth — that are worth observing but are not failures. It is
+   * deliberately separate from `getErrorEvents()`: a bug reporter subscribes to the
+   * error channel on the promise that every payload there carries a thrown value, and
+   * a contention measurement emitted as `framework-error` turns into a bug report on
+   * every occurrence instead of a metric.
+   * @returns {import("eventemitter3").EventEmitter} - Framework telemetry events emitter.
+   */
+  getTelemetryEvents() {
+    return this._telemetryEvents
+  }
+
   /**
    * Registers a reporter that can add client-safe metadata to frontend-model error payloads.
    * @param {import("./configuration-types.js").ClientErrorPayloadReporterType} reporter - Reporter callback.

package/src/database/advisory-lock-runner.js

@@ -12,6 +12,7 @@ import {
   AdvisoryLockServiceUnavailableError,
   advisoryLockBackendUnavailable
 } from "./advisory-lock-errors.js"
+import {emitAdvisoryLockFallbackReport} from "./advisory-lock-telemetry.js"
 
 /**
  * Provenance of one advisory-lock acquisition (STC-210 design §3): every
@@ -407,17 +408,12 @@ export default class AdvisoryLockRunner {
    */
   reportAdvisoryLockFallback({lockName, reason, servedBy}) {
     const policy = resolveAdvisoryLockBackendPolicy(lockName, this.configuration.getAdvisoryLockPolicy())
-    const payload = {
-      context: "advisory-lock-fallback",
+    emitAdvisoryLockFallbackReport(this.configuration, {
       lockName,
       preferredTier: policy.preferredTier,
       reason,
       servedBy
-    }
-    const errorEvents = this.configuration.getErrorEvents()
-
-    errorEvents.emit("framework-error", payload)
-    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    })
   }
 
   /**

package/src/database/advisory-lock-telemetry.js

@@ -6,9 +6,9 @@
  * A lock convoy is only fixable when it is *attributable*: which lock name was
  * contended, on which backend tier, for how long, and who held it. These reports
  * fire on the acquisition/release events themselves — never from a periodic
- * scanner — so a contended lock in production surfaces on the framework-error
- * channel with the holder identity available on that tier at that moment,
- * without SSH forensics.
+ * scanner — so a contended lock in production surfaces on the telemetry channel
+ * with the holder identity available on that tier at that moment, without SSH
+ * forensics.
  *
  * Three events, each with its own threshold (all configurable per database via
  * `advisoryLockTelemetry`, see `docs/advisory-locks.md`):
@@ -26,10 +26,15 @@
  * - `advisory-lock-slow-hold` — a hold lasted longer than `slowHoldMs`
  *   (default 60000), emitted at release.
  *
- * Reports are emitted on `configuration.getErrorEvents()` as `framework-error`
- * (plus the matching `all-error`) with `{context: "advisory-lock-telemetry",
- * event, lockName, backendTier, ...}` payloads, matching the repo's "never
- * swallow" rule so process-level bug reporters capture them.
+ * Reports are emitted on `configuration.getTelemetryEvents()` as `telemetry`
+ * with `{context: "advisory-lock-telemetry", event, lockName, backendTier, ...}`
+ * payloads.
+ *
+ * These are measurements, not failures, so they are deliberately kept off the
+ * framework-error channel: a bug reporter subscribed to `framework-error` /
+ * `all-error` must be able to assume every payload carries a thrown value, and a
+ * contention report delivered there became one bug report (plus its symbolication
+ * and notification work) per event.
  *
  * Holder lookups are strictly best-effort *after* the acquisition already
  * settled: a failed lookup never changes the acquisition outcome and never
@@ -89,41 +94,73 @@ export function advisoryLockTelemetryThresholds(args) {
 }
 
 /**
- * Emit one telemetry report on the framework-error channel.
+ * Emit one telemetry report on the framework-telemetry channel.
  *
- * Mirrors the repo's framework-error emission shape (see `configuration.js`
- * `_reportBeaconError`): when no listener is attached to `framework-error` or
- * `all-error`, a one-line summary goes to `stderr` so a convoy is never
- * completely silent. A listener failure can never break lock handling, so
- * emissions are guarded.
- * @param {import("../configuration.js").default} configuration - Configuration instance owning the error channel.
+ * When no `telemetry` listener is attached, a one-line summary goes to `stderr`
+ * so a convoy is never completely silent. A listener failure can never break
+ * lock handling, so emissions are guarded.
+ * @param {import("../configuration.js").default} configuration - Configuration instance owning the telemetry channel.
  * @param {AdvisoryLockTelemetryReport} report - The report payload.
  * @returns {void} - No return value.
  */
 export function emitAdvisoryLockTelemetryReport(configuration, report) {
   /** @type {import("eventemitter3").EventEmitter | undefined} */
-  let errorEvents
+  let telemetryEvents
 
   try {
-    errorEvents = configuration?.getErrorEvents()
+    telemetryEvents = configuration?.getTelemetryEvents()
   } catch {
     return // No configuration to report through — never break lock handling.
   }
 
-  if (!errorEvents) return
+  if (!telemetryEvents) return
 
-  const hasListener = errorEvents.listenerCount("framework-error") > 0
-    || errorEvents.listenerCount("all-error") > 0
+  const hasListener = telemetryEvents.listenerCount("telemetry") > 0
   const payload = {context: "advisory-lock-telemetry", ...report}
 
   try {
-    errorEvents.emit("framework-error", payload)
-    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    telemetryEvents.emit("telemetry", payload)
+  } catch {
+    // A broken listener must never surface as a lock failure.
+  }
+
+  if (!hasListener) {
+    console.error(`[velocious advisory-lock-telemetry ${report.event}] lock=${JSON.stringify(report.lockName)} tier=${report.backendTier} durationMs=${report.durationMs}${report.outcome ? ` outcome=${report.outcome}` : ""}${report.holderConnectionId ? ` holderConnectionId=${report.holderConnectionId}` : ""}${report.holderId ? ` holderId=${report.holderId}` : ""} — subscribe via configuration.getTelemetryEvents().on("telemetry", …) to route these measurements to your metrics`)
+  }
+}
+
+/**
+ * Reports one acquisition served below the lock name's preferred tier
+ * (design §3): the caller wanted the lock server and got the database, so the
+ * downgrade must be visible without being mistaken for a failure. Fallbacks are
+ * measurements, not errors, so they stay off `framework-error` and its bug
+ * reporters (same contract as the duration telemetry).
+ * @param {import("../configuration.js").default} configuration - Owning configuration.
+ * @param {{lockName: string, preferredTier: string, reason: string, servedBy: string}} report - Fallback details.
+ * @returns {void}
+ */
+export function emitAdvisoryLockFallbackReport(configuration, report) {
+  /** @type {import("eventemitter3").EventEmitter | undefined} */
+  let telemetryEvents
+
+  try {
+    telemetryEvents = configuration?.getTelemetryEvents()
+  } catch {
+    return // No configuration to report through — never break lock handling.
+  }
+
+  if (!telemetryEvents) return
+
+  const payload = {context: "advisory-lock-fallback", ...report}
+  const hasListener = telemetryEvents.listenerCount("telemetry") > 0
+
+  try {
+    telemetryEvents.emit("telemetry", payload)
   } catch {
     // A broken listener must never surface as a lock failure.
   }
 
   if (!hasListener) {
-    console.error(`[velocious advisory-lock-telemetry ${report.event}] lock=${JSON.stringify(report.lockName)} tier=${report.backendTier} durationMs=${report.durationMs}${report.outcome ? ` outcome=${report.outcome}` : ""}${report.holderConnectionId ? ` holderConnectionId=${report.holderConnectionId}` : ""}${report.holderId ? ` holderId=${report.holderId}` : ""} — subscribe via configuration.getErrorEvents().on("framework-error", …) to route these reports to your bug reporter`)
+    console.error(`[velocious advisory-lock-fallback] lock=${JSON.stringify(report.lockName)} preferredTier=${report.preferredTier} servedBy=${report.servedBy} reason=${report.reason}`)
   }
 }