src: add event loop based metrics into node

doc/api/perf_hooks.md

@@ -1707,20 +1707,23 @@ added: v11.10.0
 -->
 
 * `options` {Object}
-  * `resolution` {number} The sampling rate in milliseconds. Must be greater
-    than zero. **Default:** `10`.
+  * `samplePerIteration` {boolean} When `true`, samples are taken once per
+    event loop iteration. **Default:** `false`.
+  * `resolution` {number} The sampling rate in milliseconds for interval-based
+    sampling. Must be greater than zero. This option is ignored when
+    `samplePerIteration` is `true`. **Default:** `10`.
 * Returns: {IntervalHistogram}
 
 _This property is an extension by Node.js. It is not available in Web browsers._
 
 Creates an `IntervalHistogram` object that samples and reports the event loop
 delay over time. The delays will be reported in nanoseconds.
 
-Using a timer to detect approximate event loop delay works because the
-execution of timers is tied specifically to the lifecycle of the libuv
-event loop. That is, a delay in the loop will cause a delay in the execution
-of the timer, and those delays are specifically what this API is intended to
-detect.
+By default, the histogram is updated by a timer using the configured
+`resolution`. When `samplePerIteration` is `true`, samples are taken once per
+event loop iteration using `uv_prepare_t` and `uv_check_t` hooks. In that mode,
+the histogram does not keep the loop alive or force additional iterations when
+the application is idle.
 
 ```mjs
 import { monitorEventLoopDelay } from 'node:perf_hooks';
@@ -1999,7 +2002,7 @@ The standard deviation of the recorded event loop delays.
 
 ## Class: `IntervalHistogram extends Histogram`
 
-A `Histogram` that is periodically updated on a given interval.
+A `Histogram` that records event loop delay.
 
 ### `histogram.disable()`
 
@@ -2009,7 +2012,7 @@ added: v11.10.0
 
 * Returns: {boolean}
 
-Disables the update interval timer. Returns `true` if the timer was
+Disables event loop delay sampling. Returns `true` if sampling was
 stopped, `false` if it was already stopped.
 
 ### `histogram.enable()`
@@ -2020,7 +2023,7 @@ added: v11.10.0
 
 * Returns: {boolean}
 
-Enables the update interval timer. Returns `true` if the timer was
+Enables event loop delay sampling. Returns `true` if sampling was
 started, `false` if it was already started.
 
 ### `histogram[Symbol.dispose]()`
@@ -2029,7 +2032,7 @@ started, `false` if it was already started.
 added: v24.2.0
 -->
 
-Disables the update interval timer when the histogram is disposed.
+Disables event loop delay sampling when the histogram is disposed.
 
 ```js
 const { monitorEventLoopDelay } = require('node:perf_hooks');

lib/internal/perf/event_loop_delay.js

@@ -18,6 +18,7 @@ const {
 } = internalBinding('performance');
 
 const {
+  validateBoolean,
   validateInteger,
   validateObject,
 } = require('internal/validators');
@@ -74,21 +75,23 @@ class ELDHistogram extends Histogram {
 
 /**
  * @param {{
+ *   samplePerIteration : boolean,
  *   resolution : number
  * }} [options]
  * @returns {ELDHistogram}
  */
 function monitorEventLoopDelay(options = kEmptyObject) {
   validateObject(options, 'options');
 
-  const { resolution = 10 } = options;
+  const { samplePerIteration = false, resolution = 10 } = options;
+  validateBoolean(samplePerIteration, 'options.samplePerIteration');
   validateInteger(resolution, 'options.resolution', 1);
 
   return ReflectConstruct(
     function() {
       markTransferMode(this, true, false);
       this[kEnabled] = false;
-      this[kHandle] = createELDHistogram(resolution);
+      this[kHandle] = createELDHistogram(resolution, samplePerIteration);
       this[kMap] = new SafeMap();
     }, [], ELDHistogram);
 }

src/env_properties.h

@@ -431,6 +431,7 @@
   V(http2ping_constructor_template, v8::ObjectTemplate)                        \
   V(i18n_converter_template, v8::ObjectTemplate)                               \
   V(intervalhistogram_constructor_template, v8::FunctionTemplate)              \
+  V(eldhistogram_constructor_template, v8::FunctionTemplate)                   \
   V(iter_template, v8::DictionaryTemplate)                                     \
   V(js_transferable_constructor_template, v8::FunctionTemplate)                \
   V(libuv_stream_wrap_ctor_template, v8::FunctionTemplate)                     \

src/histogram.cc

@@ -68,6 +68,8 @@ CFunction IntervalHistogram::fast_start_(
     CFunction::Make(&IntervalHistogram::FastStart));
 CFunction IntervalHistogram::fast_stop_(
     CFunction::Make(&IntervalHistogram::FastStop));
+CFunction ELDHistogram::fast_start_(CFunction::Make(&ELDHistogram::FastStart));
+CFunction ELDHistogram::fast_stop_(CFunction::Make(&ELDHistogram::FastStop));
 
 void HistogramImpl::AddMethods(Isolate* isolate, Local<FunctionTemplate> tmpl) {
   // TODO(@jasnell): The bigint API variations do not yet support fast
@@ -444,6 +446,148 @@ void IntervalHistogram::FastStop(Local<Value> receiver) {
   histogram->OnStop();
 }
 
+Local<FunctionTemplate> ELDHistogram::GetConstructorTemplate(Environment* env) {
+  Local<FunctionTemplate> tmpl = env->eldhistogram_constructor_template();
+  if (tmpl.IsEmpty()) {
+    Isolate* isolate = env->isolate();
+    tmpl = NewFunctionTemplate(isolate, nullptr);
+    tmpl->Inherit(HandleWrap::GetConstructorTemplate(env));
+    tmpl->SetClassName(FIXED_ONE_BYTE_STRING(isolate, "Histogram"));
+    auto instance = tmpl->InstanceTemplate();
+    instance->SetInternalFieldCount(ELDHistogram::kInternalFieldCount);
+    HistogramImpl::AddMethods(isolate, tmpl);
+    SetFastMethod(isolate, instance, "start", Start, &fast_start_);
+    SetFastMethod(isolate, instance, "stop", Stop, &fast_stop_);
+    env->set_eldhistogram_constructor_template(tmpl);
+  }
+  return tmpl;
+}
+
+void ELDHistogram::RegisterExternalReferences(
+    ExternalReferenceRegistry* registry) {
+  registry->Register(Start);
+  registry->Register(Stop);
+  registry->Register(fast_start_);
+  registry->Register(fast_stop_);
+  HistogramImpl::RegisterExternalReferences(registry);
+}
+
+ELDHistogram::ELDHistogram(Environment* env,
+                           Local<Object> wrap,
+                           AsyncWrap::ProviderType type,
+                           const Histogram::Options& options)
+    : HandleWrap(
+          env, wrap, reinterpret_cast<uv_handle_t*>(&check_handle_), type),
+      HistogramImpl(options) {
+  MakeWeak();
+  wrap->SetAlignedPointerInInternalField(
+      HistogramImpl::InternalFields::kImplField,
+      static_cast<HistogramImpl*>(this),
+      EmbedderDataTag::kDefault);
+  uv_check_init(env->event_loop(), &check_handle_);
+  uv_prepare_init(env->event_loop(), &prepare_handle_);
+  uv_unref(reinterpret_cast<uv_handle_t*>(&check_handle_));
+  uv_unref(reinterpret_cast<uv_handle_t*>(&prepare_handle_));
+  prepare_handle_.data = this;
+}
+
+BaseObjectPtr<ELDHistogram> ELDHistogram::Create(
+    Environment* env, const Histogram::Options& options) {
+  Local<Object> obj;
+  if (!GetConstructorTemplate(env)
+           ->InstanceTemplate()
+           ->NewInstance(env->context())
+           .ToLocal(&obj)) {
+    return nullptr;
+  }
+
+  return MakeBaseObject<ELDHistogram>(
+      env, obj, AsyncWrap::PROVIDER_ELDHISTOGRAM, options);
+}
+
+void ELDHistogram::PrepareCB(uv_prepare_t* handle) {
+  ELDHistogram* self = static_cast<ELDHistogram*>(handle->data);
+  if (!self->enabled_) return;
+  self->prepare_time_ = uv_hrtime();
+  self->timeout_ = uv_backend_timeout(handle->loop);
+}
+
+void ELDHistogram::CheckCB(uv_check_t* handle) {
+  ELDHistogram* self = ContainerOf(&ELDHistogram::check_handle_, handle);
+  if (!self->enabled_) return;
+
+  uint64_t check_time = uv_hrtime();
+  uint64_t poll_time = check_time - self->prepare_time_;
+  uint64_t latency = self->prepare_time_ - self->check_time_;
+
+  if (self->timeout_ >= 0) {
+    uint64_t timeout_ns = static_cast<uint64_t>(self->timeout_) * 1000 * 1000;
+    if (poll_time > timeout_ns) {
+      latency += poll_time - timeout_ns;
+    }
+  }
+
+  self->histogram()->Record(latency == 0 ? 1 : latency);
+  self->check_time_ = check_time;
+}
+
+void ELDHistogram::MemoryInfo(MemoryTracker* tracker) const {
+  tracker->TrackField("histogram", histogram());
+}
+
+void ELDHistogram::OnStart(StartFlags flags) {
+  if (enabled_ || IsHandleClosing()) return;
+  enabled_ = true;
+  if (flags == StartFlags::RESET) histogram()->Reset();
+  check_time_ = uv_hrtime();
+  prepare_time_ = check_time_;
+  timeout_ = 0;
+  uv_check_start(&check_handle_, CheckCB);
+  uv_prepare_start(&prepare_handle_, PrepareCB);
+  uv_unref(reinterpret_cast<uv_handle_t*>(&check_handle_));
+  uv_unref(reinterpret_cast<uv_handle_t*>(&prepare_handle_));
+}
+
+void ELDHistogram::OnStop() {
+  if (!enabled_ || IsHandleClosing()) return;
+  enabled_ = false;
+  uv_check_stop(&check_handle_);
+  uv_prepare_stop(&prepare_handle_);
+}
+
+void ELDHistogram::Close(Local<Value> close_callback) {
+  if (IsHandleClosing()) return;
+  OnStop();
+  HandleWrap::Close(close_callback);
+  uv_close(reinterpret_cast<uv_handle_t*>(&prepare_handle_), nullptr);
+}
+
+void ELDHistogram::Start(const FunctionCallbackInfo<Value>& args) {
+  ELDHistogram* histogram;
+  ASSIGN_OR_RETURN_UNWRAP(&histogram, args.This());
+  histogram->OnStart(args[0]->IsTrue() ? StartFlags::RESET : StartFlags::NONE);
+}
+
+void ELDHistogram::FastStart(Local<Value> receiver, bool reset) {
+  TRACK_V8_FAST_API_CALL("histogram.eventLoopDelay.start");
+  ELDHistogram* histogram;
+  ASSIGN_OR_RETURN_UNWRAP(&histogram, receiver);
+  histogram->OnStart(reset ? StartFlags::RESET : StartFlags::NONE);
+}
+
+void ELDHistogram::Stop(const FunctionCallbackInfo<Value>& args) {
+  ELDHistogram* histogram;
+  ASSIGN_OR_RETURN_UNWRAP(&histogram, args.This());
+  histogram->OnStop();
+}
+
+void ELDHistogram::FastStop(Local<Value> receiver) {
+  TRACK_V8_FAST_API_CALL("histogram.eventLoopDelay.stop");
+  ELDHistogram* histogram;
+  ASSIGN_OR_RETURN_UNWRAP(&histogram, receiver);
+  histogram->OnStop();
+}
+
 void HistogramImpl::GetCount(const FunctionCallbackInfo<Value>& args) {
   HistogramImpl* histogram = HistogramImpl::FromJSObject(args.This());
   double value = static_cast<double>((*histogram)->Count());
@@ -607,6 +751,10 @@ HistogramImpl* HistogramImpl::FromJSObject(Local<Value> value) {
       HistogramImpl::kImplField, EmbedderDataTag::kDefault));
 }
 
+std::unique_ptr<worker::TransferData> ELDHistogram::CloneForMessaging() const {
+  return std::make_unique<HistogramBase::HistogramTransferData>(histogram());
+}
+
 std::unique_ptr<worker::TransferData>
 IntervalHistogram::CloneForMessaging() const {
   return std::make_unique<HistogramBase::HistogramTransferData>(histogram());

src/histogram.h

@@ -266,6 +266,63 @@ class IntervalHistogram final : public HandleWrap, public HistogramImpl {
   static v8::CFunction fast_stop_;
 };
 
+class ELDHistogram final : public HandleWrap, public HistogramImpl {
+ public:
+  enum InternalFields {
+    kInternalFieldCount = std::max<uint32_t>(
+        HandleWrap::kInternalFieldCount, HistogramImpl::kInternalFieldCount),
+  };
+
+  enum class StartFlags { NONE, RESET };
+
+  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
+
+  static v8::Local<v8::FunctionTemplate> GetConstructorTemplate(
+      Environment* env);
+
+  static BaseObjectPtr<ELDHistogram> Create(Environment* env,
+                                            const Histogram::Options& options);
+
+  ELDHistogram(Environment* env,
+               v8::Local<v8::Object> wrap,
+               AsyncWrap::ProviderType type,
+               const Histogram::Options& options = Histogram::Options{});
+
+  static void Start(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Stop(const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static void FastStart(v8::Local<v8::Value> receiver, bool reset);
+  static void FastStop(v8::Local<v8::Value> receiver);
+
+  BaseObject::TransferMode GetTransferMode() const override {
+    return TransferMode::kCloneable;
+  }
+  std::unique_ptr<worker::TransferData> CloneForMessaging() const override;
+
+  void Close(
+      v8::Local<v8::Value> close_callback = v8::Local<v8::Value>()) override;
+
+  void MemoryInfo(MemoryTracker* tracker) const override;
+  SET_MEMORY_INFO_NAME(ELDHistogram)
+  SET_SELF_SIZE(ELDHistogram)
+
+ private:
+  static void PrepareCB(uv_prepare_t* handle);
+  static void CheckCB(uv_check_t* handle);
+  void OnStart(StartFlags flags = StartFlags::RESET);
+  void OnStop();
+
+  bool enabled_ = false;
+  uv_prepare_t prepare_handle_;
+  uv_check_t check_handle_;
+  uint64_t prepare_time_ = 0;
+  uint64_t check_time_ = 0;
+  int64_t timeout_ = 0;
+
+  static v8::CFunction fast_start_;
+  static v8::CFunction fast_stop_;
+};
+
 }  // namespace node
 
 #endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

src/node_perf.cc

@@ -282,6 +282,12 @@ void CreateELDHistogram(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   int64_t interval = args[0].As<Integer>()->Value();
   CHECK_GT(interval, 0);
+  if (args[1]->IsTrue()) {
+    BaseObjectPtr<ELDHistogram> histogram =
+        ELDHistogram::Create(env, Histogram::Options{1});
+    args.GetReturnValue().Set(histogram->object());
+    return;
+  }
   BaseObjectPtr<IntervalHistogram> histogram =
       IntervalHistogram::Create(env, interval, [](Histogram& histogram) {
         uint64_t delta = histogram.RecordDelta();
@@ -413,6 +419,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(fast_performance_now);
   HistogramBase::RegisterExternalReferences(registry);
   IntervalHistogram::RegisterExternalReferences(registry);
+  ELDHistogram::RegisterExternalReferences(registry);
 }
 }  // namespace performance
 }  // namespace node

test/parallel/test-perf-hooks-monitor-event-loop-delay-fast-calls.js

@@ -0,0 +1,26 @@
+// Flags: --allow-natives-syntax --expose-internals --no-warnings
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+
+const { internalBinding } = require('internal/test/binding');
+const { createELDHistogram } = internalBinding('performance');
+
+const histogram = createELDHistogram(1, true);
+
+function testFastMethods() {
+  histogram.start(true);
+  histogram.stop();
+}
+
+eval('%PrepareFunctionForOptimization(testFastMethods)');
+testFastMethods();
+eval('%OptimizeFunctionOnNextCall(testFastMethods)');
+testFastMethods();
+
+if (common.isDebug) {
+  const { getV8FastApiCallCount } = internalBinding('debug');
+  assert.strictEqual(getV8FastApiCallCount('histogram.eventLoopDelay.start'), 1);
+  assert.strictEqual(getV8FastApiCallCount('histogram.eventLoopDelay.stop'), 1);
+}