@naturalcycles/backend-lib 9.26.0 → 9.27.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './sentry/sentry.shared.service.js';
 export * from './server/asyncLocalStorageMiddleware.js';
 export * from './server/basicAuthMiddleware.js';
 export * from './server/bodyParserTimeoutMiddleware.js';
+export * from './server/eventLoop.util.js';
 export * from './server/genericErrorMiddleware.js';
 export * from './server/logMiddleware.js';
 export * from './server/methodOverrideMiddleware.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './sentry/sentry.shared.service.js';
 export * from './server/asyncLocalStorageMiddleware.js';
 export * from './server/basicAuthMiddleware.js';
 export * from './server/bodyParserTimeoutMiddleware.js';
+export * from './server/eventLoop.util.js';
 export * from './server/genericErrorMiddleware.js';
 export * from './server/logMiddleware.js';
 export * from './server/methodOverrideMiddleware.js';

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

@@ -0,0 +1,46 @@
+import type { NumberOfMilliseconds, NumberOfPercent } from '@naturalcycles/js-lib/types';
+/**
+ * @experimental
+ */
+export declare class EventLoopMonitor {
+    constructor(cfg?: EventLoopMonitorCfg);
+    private interval;
+    private eld;
+    private lastElu;
+    /**
+     * Undefined until the first interval has completed.
+     */
+    lastStats?: EventLoopStats;
+    stop(): void;
+}
+export interface EventLoopMonitorCfg {
+    /**
+     * Defaults to 20.
+     */
+    resolution?: NumberOfMilliseconds;
+    /**
+     * Defaults to 60_000 ms
+     */
+    measureInterval?: NumberOfMilliseconds;
+    /**
+     * Callback to be invoked with EventLoopStats.
+     * Called every `measureInterval` milliseconds.
+     */
+    onStats?: (stats: EventLoopStats) => void;
+}
+export interface EventLoopStats {
+    p50: NumberOfMilliseconds;
+    p90: NumberOfMilliseconds;
+    p99: NumberOfMilliseconds;
+    max: NumberOfMilliseconds;
+    mean: NumberOfMilliseconds;
+    /**
+     * EventLoopUtilization in percent.
+     *
+     * Calculated as:
+     *   idle: <nanoseconds event loop was idle>,
+     *   active: <nanoseconds event loop was busy>,
+     *   utilization: active / (idle + active)
+     */
+    elu: NumberOfPercent;
+}

package/dist/server/eventLoop.util.js

@@ -0,0 +1,46 @@
+import { monitorEventLoopDelay, performance } from 'node:perf_hooks';
+/**
+ * @experimental
+ */
+export class EventLoopMonitor {
+    constructor(cfg = {}) {
+        const { resolution = 20, measureInterval = 60_000 } = cfg;
+        this.eld = monitorEventLoopDelay({ resolution });
+        this.eld.enable();
+        this.lastElu = performance.eventLoopUtilization();
+        this.interval = setInterval(() => {
+            // Delay stats are reported in **nanoseconds**
+            const { eld } = this;
+            const p50 = Math.round(eld.percentile(50) / 1e6);
+            const p90 = Math.round(eld.percentile(90) / 1e6);
+            const p99 = Math.round(eld.percentile(99) / 1e6);
+            const max = Math.round(eld.max / 1e6);
+            const mean = Math.round(eld.mean / 1e6);
+            const currentElu = performance.eventLoopUtilization();
+            const deltaElu = performance.eventLoopUtilization(this.lastElu, currentElu);
+            this.lastElu = currentElu;
+            const elu = Math.round(deltaElu.utilization * 100);
+            this.lastStats = {
+                p50,
+                p90,
+                p99,
+                max,
+                mean,
+                elu,
+            };
+            cfg.onStats?.(this.lastStats);
+            eld.reset();
+        }, measureInterval);
+    }
+    interval;
+    eld;
+    lastElu;
+    /**
+     * Undefined until the first interval has completed.
+     */
+    lastStats;
+    stop() {
+        this.interval.close();
+        this.eld.disable();
+    }
+}

package/dist/server/serverStatusMiddleware.js

@@ -10,9 +10,11 @@ export function serverStatusMiddleware(projectDir, extra) {
     };
 }
 export function getServerStatusData(projectDir = process.cwd(), extra) {
-    const { ts } = getDeployInfo(projectDir);
-    const t = localTime(ts);
-    const deployBuildTime = DEPLOY_BUILD_TIME || t.toPretty();
+    let deployBuildTime = DEPLOY_BUILD_TIME;
+    if (!deployBuildTime) {
+        const { ts } = getDeployInfo(projectDir);
+        deployBuildTime = localTime(ts).toPretty();
+    }
     return _filterNullishValues({
         nodeProcessStarted: getStartedStr(),
         deployBuildTime,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.26.0",
+  "version": "9.27.0",
   "peerDependencies": {
     "@sentry/node": "^10"
   },

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './sentry/sentry.shared.service.js'
 export * from './server/asyncLocalStorageMiddleware.js'
 export * from './server/basicAuthMiddleware.js'
 export * from './server/bodyParserTimeoutMiddleware.js'
+export * from './server/eventLoop.util.js'
 export * from './server/genericErrorMiddleware.js'
 export * from './server/logMiddleware.js'
 export * from './server/methodOverrideMiddleware.js'

package/src/server/eventLoop.util.ts

@@ -0,0 +1,95 @@
+import type { EventLoopUtilization, IntervalHistogram } from 'node:perf_hooks'
+import { monitorEventLoopDelay, performance } from 'node:perf_hooks'
+import type { NumberOfMilliseconds, NumberOfPercent } from '@naturalcycles/js-lib/types'
+
+/**
+ * @experimental
+ */
+export class EventLoopMonitor {
+  constructor(cfg: EventLoopMonitorCfg = {}) {
+    const { resolution = 20, measureInterval = 60_000 } = cfg
+
+    this.eld = monitorEventLoopDelay({ resolution })
+    this.eld.enable()
+
+    this.lastElu = performance.eventLoopUtilization()
+
+    this.interval = setInterval(() => {
+      // Delay stats are reported in **nanoseconds**
+      const { eld } = this
+      const p50 = Math.round(eld.percentile(50) / 1e6)
+      const p90 = Math.round(eld.percentile(90) / 1e6)
+      const p99 = Math.round(eld.percentile(99) / 1e6)
+      const max = Math.round(eld.max / 1e6)
+      const mean = Math.round(eld.mean / 1e6)
+
+      const currentElu = performance.eventLoopUtilization()
+      const deltaElu = performance.eventLoopUtilization(this.lastElu, currentElu)
+      this.lastElu = currentElu
+
+      const elu = Math.round(deltaElu.utilization * 100)
+
+      this.lastStats = {
+        p50,
+        p90,
+        p99,
+        max,
+        mean,
+        elu,
+      }
+
+      cfg.onStats?.(this.lastStats)
+
+      eld.reset()
+    }, measureInterval)
+  }
+
+  private interval: NodeJS.Timeout
+  private eld: IntervalHistogram
+  private lastElu: EventLoopUtilization
+  /**
+   * Undefined until the first interval has completed.
+   */
+  lastStats?: EventLoopStats
+
+  stop(): void {
+    this.interval.close()
+    this.eld.disable()
+  }
+
+  // cfg: Required<EventLoopMonitorCfg>
+}
+
+export interface EventLoopMonitorCfg {
+  /**
+   * Defaults to 20.
+   */
+  resolution?: NumberOfMilliseconds
+
+  /**
+   * Defaults to 60_000 ms
+   */
+  measureInterval?: NumberOfMilliseconds
+  /**
+   * Callback to be invoked with EventLoopStats.
+   * Called every `measureInterval` milliseconds.
+   */
+  onStats?: (stats: EventLoopStats) => void
+}
+
+export interface EventLoopStats {
+  p50: NumberOfMilliseconds
+  p90: NumberOfMilliseconds
+  p99: NumberOfMilliseconds
+  max: NumberOfMilliseconds
+  mean: NumberOfMilliseconds
+  /**
+   * EventLoopUtilization in percent.
+   *
+   * Calculated as:
+   *   idle: <nanoseconds event loop was idle>,
+   *   active: <nanoseconds event loop was busy>,
+   *   utilization: active / (idle + active)
+   */
+  elu: NumberOfPercent
+}

package/src/server/serverStatusMiddleware.ts

@@ -28,9 +28,11 @@ export function getServerStatusData(
   projectDir: string = process.cwd(),
   extra?: any,
 ): Record<string, any> {
-  const { ts } = getDeployInfo(projectDir)
-  const t = localTime(ts)
-  const deployBuildTime = DEPLOY_BUILD_TIME || t.toPretty()
+  let deployBuildTime = DEPLOY_BUILD_TIME
+  if (!deployBuildTime) {
+    const { ts } = getDeployInfo(projectDir)
+    deployBuildTime = localTime(ts).toPretty()
+  }
 
   return _filterNullishValues({
     nodeProcessStarted: getStartedStr(),