Histogram `exceeds` metric 1 hour threshold

[Bamieh]

📗 API Reference Docs Problem

• Version: v11.10.0+

Location

Section of the site where the content exists

Performance measurement APIs

Affected URL(s):

• https://nodejs.org/api/perf_hooks.html#perf_hooks_histogram_exceeds

Description

The histogram exceeds metric description might be incorrect or at least vague in explaining what is being measured.

histogram.exceeds
The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.

---

I havent seen any code implementation of the mentioned maximum 1 hour event loop delay threshold..

My walkthrough in the code:

1. Histogram::RecordDelta tracks the delta time between now and the last time it was called. (code)

2. exceeds is incremented when hdr_record_value(,delta) returns true (code)

3. The hdr_record_values function is what determines this metric (code)
   a. value is always bigger than 0 in our case.
   b. exceeds is incremented if this condition is true:

counts_index = counts_index_for(h, value);

if (counts_index < 0 || h->counts_len <= counts_index) { ... }

counts_index is the index of the last counts that happened in the delta duration. Hence exceeds will increment whenever there is no counts during the last resolution time.

Is my understanding corrent here? CC @jasnell as I believe he's implemented this feature

---

• I would like to work on this issue and
  submit a pull request.

[TinaHeiligers]

Has there been any further progress here? It's still unclear if exceeds is a counter (i.e. a numeric incrementation from 0) or a measure of time.

[rudolf]

Nodejs uses an High Dynamic Range Histogram. An HDR histogram can be configured with a minimum and maximum value which determines the buckets used by the histogram and ultimately the accuracy of the histogram. The documentation seem to suggest that the event loop delay histogram is configured with a maximum value of an event loop delay of 1 hour. exceeds is the amount of times a value was recorded that exceeded the maximum histogram value.

const { createHistogram } = require('node:perf_hooks');
const hist = createHistogram({highest: 1000});
hist.record(1);
console.log(hist.exceeds) // outputs "0"
hist.record(2500);
console.log(hist.exceeds) // outputs "1"

The event loop delay histogram gets created here:

node/src/node_perf.cc

Lines 236 to 255 in 386c7e1

	void CreateELDHistogram(const FunctionCallbackInfo<Value>& args) {
	Environment* env = Environment::GetCurrent(args);
	int64_t interval = args[0].As<Integer>()->Value();
	CHECK_GT(interval, 0);
	BaseObjectPtr<IntervalHistogram> histogram =
	IntervalHistogram::Create(env, interval, [](Histogram& histogram) {
	uint64_t delta = histogram.RecordDelta();
	TRACE_COUNTER1(TRACING_CATEGORY_NODE2(perf, event_loop),
	"delay", delta);
	TRACE_COUNTER1(TRACING_CATEGORY_NODE2(perf, event_loop),
	"min", histogram.Min());
	TRACE_COUNTER1(TRACING_CATEGORY_NODE2(perf, event_loop),
	"max", histogram.Max());
	TRACE_COUNTER1(TRACING_CATEGORY_NODE2(perf, event_loop),
	"mean", histogram.Mean());
	TRACE_COUNTER1(TRACING_CATEGORY_NODE2(perf, event_loop),
	"stddev", histogram.Stddev());
	}, Histogram::Options { 1000 });
	args.GetReturnValue().Set(histogram->object());
	}

But given that the Histogram:Options struct's first member is lowest Nodejs seems to only initialize the histogram lowest value which means the highest defaults to Number.MAX_SAFE_INTEGER which is the equivalent of 2500 hours of delay.

node/src/histogram.h

Lines 25 to 31 in 386c7e1

	class Histogram : public MemoryRetainer {
	public:
	struct Options {
	int64_t lowest = 1;
	int64_t highest = std::numeric_limits<int64_t>::max();
	int figures = kDefaultHistogramFigures;
	};

This would mean the histogram accuracy isn't as high as it could be.