feat(metrics) histograms with user-defined bins

[casimiro]

This feature is only available through the FFI.

If a user provides a list of numbers when defining a histogram, those numbers will be used as the upper-bounds of the histogram's bins.

For instance, the following code:

shm.metrics:define("h", shm.metrics.HISTOGRAM, { bins = { 1, 3, 5 } })

Creates a histogram with bins [0, 1], (1, 3], (3, 5] and (5, Inf+].

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.83281%. Comparing base (ea1475c) to head (353bc71).
Report is 7 commits behind head on main.

Additional details and impacted files

@@                 Coverage Diff                 @@
##                main        #608         +/-   ##
===================================================
+ Coverage   90.73673%   90.83281%   +0.09608%     
===================================================
  Files             52          52                 
  Lines          11076       11203        +127     
===================================================
+ Hits           10050       10176        +126     
- Misses          1026        1027          +1     

Files with missing lines	Coverage Δ
src/common/lua/ngx_wasm_lua_ffi.c	95.91837% <100.00000%> (+0.02092%)	⬆️
src/common/lua/ngx_wasm_lua_ffi.h	100.00000% <100.00000%> (ø)
src/common/metrics/ngx_wa_histogram.c	99.35065% <100.00000%> (+0.21272%)	⬆️
src/common/metrics/ngx_wa_metrics.c	92.21790% <100.00000%> (+0.03040%)	⬆️
src/common/metrics/ngx_wa_metrics.h	100.00000% <ø> (ø)
src/common/proxy_wasm/ngx_proxy_wasm_host.c	93.91206% <100.00000%> (+0.00686%)	⬆️

... and 27 files with indirect coverage changes

Flag	Coverage Δ
unit	90.58177% <100.00000%> (+0.13453%)	⬆️
valgrind	82.44410% <100.00000%> (+0.01354%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

[thibaultcha]

One last thing before merge: a logarithmic histogram can contain up to 18 bins as per the existing design, but this specific condition and the extra bin on line 197 mean that a custom binning histogram can contain up to 19 bins (18 defined + the MAX_UINT32 bin). Is this analysis correct? If so, is the behavior correct or could the number of bins difference cause problems?

[casimiro]

Yeah, that was a deliberate decision.

Although it is an inconsistent application of the limit of bins, this seemed like an implementation detail that the FFI layer could be spared from; since the limit of bins is rather arbitrary.

In retrospective, though, I admit that having a check for #bins > HISTOGRAM_MAX_BINS - 1 accompanied by a comment in shm.lua seems like a low price to pay to achieve consistence between logarithmic and standard histograms.

[thibaultcha]

I made this change in the merge PR. The change makes the documentation easier to read and understand: "all histograms can only have 18 bins"

[casimiro]

Thanks for addressing it in the merge PR.