velocious 1.0.710 → 1.0.711

package/build/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/build/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/build/database/advisory-lock-telemetry.js

@@ -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,37 @@ 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.getErrorEvents().on("framework-error", …) to route these reports to your bug reporter`)
+    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`)
   }
 }

package/build/src/configuration-types.d.ts

@@ -170,7 +170,7 @@ export type DatabaseConfigurationType = {
      */
     advisoryLockAcquireTimeoutMs?: number | null;
     /**
-     * - 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).
+     * - 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).
      */
     advisoryLockTelemetry?: {
         slowAcquireMs?: number | null;
@@ -2083,7 +2083,7 @@ export type ConfigurationArgsType = {
 /**
  * @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.