@naturalcycles/backend-lib 9.84.1 → 9.84.2

package/dist/server/eventLoop.util.d.ts

@@ -11,8 +11,10 @@ import type { Integer, NonNegativeInteger, NumberOfMilliseconds, NumberOfPercent
  * reported by older interval-based sampling.
  *
  * Beware of CPU-throttled processes (e.g. idle CloudRun instances with request-based billing):
- * the interval timer fires late there, and the time the process spent runnable-but-unscheduled
- * is recorded as event loop delay. Use `intervalMs` to detect such intervals.
+ * the time the process spent runnable-but-unscheduled is recorded as event loop delay,
+ * and the interval timer fires late (see `intervalMs`).
+ * Use `pause()` / `resume()` to keep such periods out of the delay samples,
+ * e.g. pause when the last in-flight request finishes and resume when the next one arrives.
  */
 export declare class EventLoopMonitor {
     constructor(cfg?: EventLoopMonitorCfg);
@@ -20,6 +22,7 @@ export declare class EventLoopMonitor {
     private eld;
     private lastElu;
     private lastReportedAt;
+    private paused;
     /**
      * Undefined until the first interval has completed.
      */
@@ -28,6 +31,22 @@ export declare class EventLoopMonitor {
     gcCount: number;
     gcTotalTime: number;
     stop(): void;
+    /**
+     * Stops sampling event loop delay until `resume()` is called.
+     * GC and ELU keep being tracked, and the samples recorded so far are kept.
+     *
+     * Meant for periods when the process is known to be CPU-throttled, e.g. a CloudRun instance
+     * (request-based billing) with no request in flight: a delay recorded there measures
+     * the throttling, not the application.
+     */
+    pause(): void;
+    /**
+     * Resumes sampling event loop delay after `pause()`.
+     * Safe to call from within the event that ended the throttled period (e.g. the middleware of
+     * the request that woke the instance): the histogram restarts its clock from this moment,
+     * so the stall that preceded it in the same loop iteration is not sampled.
+     */
+    resume(): void;
 }
 export interface EventLoopMonitorCfg {
     /**

package/dist/server/eventLoop.util.js

@@ -27,8 +27,10 @@ import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:pe
  * reported by older interval-based sampling.
  *
  * Beware of CPU-throttled processes (e.g. idle CloudRun instances with request-based billing):
- * the interval timer fires late there, and the time the process spent runnable-but-unscheduled
- * is recorded as event loop delay. Use `intervalMs` to detect such intervals.
+ * the time the process spent runnable-but-unscheduled is recorded as event loop delay,
+ * and the interval timer fires late (see `intervalMs`).
+ * Use `pause()` / `resume()` to keep such periods out of the delay samples,
+ * e.g. pause when the last in-flight request finishes and resume when the next one arrives.
  */
 export class EventLoopMonitor {
     constructor(cfg = {}) {
@@ -92,6 +94,7 @@ export class EventLoopMonitor {
     eld;
     lastElu;
     lastReportedAt;
+    paused = false;
     /**
      * Undefined until the first interval has completed.
      */
@@ -104,4 +107,28 @@ export class EventLoopMonitor {
         this.eld.disable();
         this.po.disconnect();
     }
+    /**
+     * Stops sampling event loop delay until `resume()` is called.
+     * GC and ELU keep being tracked, and the samples recorded so far are kept.
+     *
+     * Meant for periods when the process is known to be CPU-throttled, e.g. a CloudRun instance
+     * (request-based billing) with no request in flight: a delay recorded there measures
+     * the throttling, not the application.
+     */
+    pause() {
+        this.paused = true;
+        this.eld.disable();
+    }
+    /**
+     * Resumes sampling event loop delay after `pause()`.
+     * Safe to call from within the event that ended the throttled period (e.g. the middleware of
+     * the request that woke the instance): the histogram restarts its clock from this moment,
+     * so the stall that preceded it in the same loop iteration is not sampled.
+     */
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        this.eld.enable();
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.84.1",
+  "version": "9.84.2",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",

package/src/server/eventLoop.util.ts

@@ -36,8 +36,10 @@ import type {
  * reported by older interval-based sampling.
  *
  * Beware of CPU-throttled processes (e.g. idle CloudRun instances with request-based billing):
- * the interval timer fires late there, and the time the process spent runnable-but-unscheduled
- * is recorded as event loop delay. Use `intervalMs` to detect such intervals.
+ * the time the process spent runnable-but-unscheduled is recorded as event loop delay,
+ * and the interval timer fires late (see `intervalMs`).
+ * Use `pause()` / `resume()` to keep such periods out of the delay samples,
+ * e.g. pause when the last in-flight request finishes and resume when the next one arrives.
  */
 export class EventLoopMonitor {
   constructor(cfg: EventLoopMonitorCfg = {}) {
@@ -113,6 +115,7 @@ export class EventLoopMonitor {
   private eld: ELDHistogram
   private lastElu: EventLoopUtilization
   private lastReportedAt: NumberOfMilliseconds
+  private paused = false
   /**
    * Undefined until the first interval has completed.
    */
@@ -127,6 +130,31 @@ export class EventLoopMonitor {
     this.po.disconnect()
   }
 
+  /**
+   * Stops sampling event loop delay until `resume()` is called.
+   * GC and ELU keep being tracked, and the samples recorded so far are kept.
+   *
+   * Meant for periods when the process is known to be CPU-throttled, e.g. a CloudRun instance
+   * (request-based billing) with no request in flight: a delay recorded there measures
+   * the throttling, not the application.
+   */
+  pause(): void {
+    this.paused = true
+    this.eld.disable()
+  }
+
+  /**
+   * Resumes sampling event loop delay after `pause()`.
+   * Safe to call from within the event that ended the throttled period (e.g. the middleware of
+   * the request that woke the instance): the histogram restarts its clock from this moment,
+   * so the stall that preceded it in the same loop iteration is not sampled.
+   */
+  resume(): void {
+    if (!this.paused) return
+    this.paused = false
+    this.eld.enable()
+  }
+
   // cfg: Required<EventLoopMonitorCfg>
 }