src,lib: add performance.uvMetricsInfo

doc/api/perf_hooks.md

@@ -444,6 +444,40 @@ If the wrapped function returns a promise, a finally handler will be attached
 to the promise and the duration will be reported once the finally handler is
 invoked.
 
+### `performance.uvMetricsInfo()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object}
+  * `loopCount` {number} Number of event loop iterations.
+  * `events` {number} Number of events that have been processed by the event handler.
+  * `eventsWaiting` {number} Number of events that were waiting to be processed when the event provider was called.
+
+This is a wrapper to the `uv_metrics_info` function.
+It returns the current set of event loop metrics.
+
+It is recommended to use this function inside a function whose execution was
+scheduled using `setImmediate` to avoid collecting metrics before finishing all
+operations scheduled during the current loop iteration.
+
+```cjs
+const { performance } = require('node:perf_hooks');
+
+setImmediate(() => {
+  console.log(performance.uvMetricsInfo());
+});
+```
+
+```mjs
+import { performance } from 'node:perf_hooks';
+
+setImmediate(() => {
+  console.log(performance.uvMetricsInfo());
+});
+```
+
 ### `performance.toJSON()`
 
 <!-- YAML

lib/internal/perf/nodetiming.js

@@ -28,6 +28,7 @@ const {
     NODE_PERFORMANCE_MILESTONE_ENVIRONMENT,
   },
   loopIdleTime,
+  uvMetricsInfo,
 } = internalBinding('performance');
 
 class PerformanceNodeTiming {
@@ -122,6 +123,13 @@ class PerformanceNodeTiming {
         configurable: true,
         get: loopIdleTime,
       },
+
+      uvMetricsInfo: {
+        __proto__: null,
+        enumerable: true,
+        configurable: true,
+        get: uvMetricsInfo,
+      },
     });
   }
 

lib/internal/perf/performance.js

@@ -191,6 +191,7 @@ ObjectDefineProperties(Performance.prototype, {
     writable: true,
     value: eventLoopUtilization,
   },
+
   nodeTiming: {
     __proto__: null,
     configurable: true,

src/env_properties.h

@@ -143,6 +143,8 @@
   V(env_var_settings_string, "envVarSettings")                                 \
   V(errno_string, "errno")                                                     \
   V(error_string, "error")                                                     \
+  V(events, "events")                                                          \
+  V(events_waiting, "eventsWaiting")                                           \
   V(exchange_string, "exchange")                                               \
   V(expire_string, "expire")                                                   \
   V(exponent_string, "exponent")                                               \
@@ -212,6 +214,7 @@
   V(kind_string, "kind")                                                       \
   V(length_string, "length")                                                   \
   V(library_string, "library")                                                 \
+  V(loop_count, "loopCount")                                                   \
   V(mac_string, "mac")                                                         \
   V(max_buffer_string, "maxBuffer")                                            \
   V(max_concurrent_streams_string, "maxConcurrentStreams")                     \

src/node_perf.cc

@@ -261,6 +261,30 @@ void LoopIdleTime(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(1.0 * idle_time / NANOS_PER_MILLIS);
 }
 
+void UvMetricsInfo(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  uv_metrics_t metrics;
+
+  // uv_metrics_info always return 0
+  uv_metrics_info(env->event_loop(), &metrics);
+
+  Local<Object> obj = Object::New(env->isolate());
+  obj->Set(env->context(),
+           env->loop_count(),
+           Integer::NewFromUnsigned(env->isolate(), metrics.loop_count))
+      .Check();
+  obj->Set(env->context(),
+           env->events(),
+           Integer::NewFromUnsigned(env->isolate(), metrics.events))
+      .Check();
+  obj->Set(env->context(),
+           env->events_waiting(),
+           Integer::NewFromUnsigned(env->isolate(), metrics.events_waiting))
+      .Check();
+
+  args.GetReturnValue().Set(obj);
+}
+
 void CreateELDHistogram(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   int64_t interval = args[0].As<Integer>()->Value();
@@ -324,6 +348,7 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
   SetMethod(isolate, target, "loopIdleTime", LoopIdleTime);
   SetMethod(isolate, target, "createELDHistogram", CreateELDHistogram);
   SetMethod(isolate, target, "markBootstrapComplete", MarkBootstrapComplete);
+  SetMethod(isolate, target, "uvMetricsInfo", UvMetricsInfo);
   SetFastMethodNoSideEffect(
       isolate, target, "now", SlowPerformanceNow, &fast_performance_now);
 }
@@ -390,6 +415,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(LoopIdleTime);
   registry->Register(CreateELDHistogram);
   registry->Register(MarkBootstrapComplete);
+  registry->Register(UvMetricsInfo);
   registry->Register(SlowPerformanceNow);
   registry->Register(FastPerformanceNow);
   registry->Register(fast_performance_now.GetTypeInfo());

test/parallel/test-performance-nodetiming-uvmetricsinfo.js

@@ -0,0 +1,74 @@
+'use strict';
+
+require('../common');
+
+const fixtures = require('../common/fixtures');
+
+const filepath = fixtures.path('x.txt');
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const { performance } = require('node:perf_hooks');
+
+const { nodeTiming } = performance;
+
+function safeMetricsInfo(cb) {
+  setImmediate(() => {
+    const info = nodeTiming.uvMetricsInfo;
+    cb(info);
+  });
+}
+
+{
+  const info = nodeTiming.uvMetricsInfo;
+  assert.strictEqual(info.loopCount, 0);
+  assert.strictEqual(info.events, 0);
+  // This is the only part of the test that we test events waiting
+  // Adding checks for this property will make the test flaky
+  // as it can be highly influenced by race conditions.
+  assert.strictEqual(info.eventsWaiting, 0);
+}
+
+{
+  // The synchronous call should obviously not affect the uv metrics
+  const fd = fs.openSync(filepath, 'r');
+  fs.readFileSync(fd);
+  const info = nodeTiming.uvMetricsInfo;
+  assert.strictEqual(info.loopCount, 0);
+  assert.strictEqual(info.events, 0);
+  assert.strictEqual(info.eventsWaiting, 0);
+}
+
+{
+  function openFile(info) {
+    assert.strictEqual(info.loopCount, 1);
+    // 1. ? event
+    assert.strictEqual(info.events, 1);
+
+    fs.open(filepath, 'r', (err) => {
+      assert.ifError(err);
+      safeMetricsInfo(afterOpenFile);
+    });
+  }
+
+  function afterOpenFile(info) {
+    assert.strictEqual(info.loopCount, 2);
+    // 1. ? event
+    // 2. uv_fs_open
+    assert.strictEqual(info.events, 2);
+
+    fs.readFile(filepath, (err) => {
+      assert.ifError(err);
+      safeMetricsInfo(afterReadFile);
+    });
+  }
+
+  function afterReadFile(info) {
+    assert.strictEqual(info.loopCount, 6);
+    // 1. ? event
+    assert.strictEqual(info.events, 6);
+    // 1. ?
+  }
+
+  safeMetricsInfo(openFile);
+}