Runtime Payload Histogram Tracking

[YiwenZhang12]

Motivation

Today, operators lack a bounded and structured way to understand real traffic payload distributions (small vs large requests/replies). Existing signals such as buffer sizes or isolated counters do not provide insight into distribution shape or proximity to configured limits.

This proposal introduces a time bounded, sampling aware payload tracking mechanism that allows operators to temporarily quantify traffic size distributions without permanently expanding the server’s metrics surface area.

The design intentionally avoids always on instrumentation and keeps steady state overhead at zero when disabled.

Design Principles

• No permanent metrics growth (no new INFO fields).
• Zero hot-path overhead when tracking is OFF.
• Operator initiated and time bounded.
• Sampling support to limit runtime cost.
• Runtime configurable bucket views.
• Explicit reset for fresh diagnostic windows.

Command Surface

PAYLOAD TRACKING

Controls runtime data collection.

PAYLOAD TRACKING ON [seconds] [SAMPLE <rate>] [READ|WRITE|BOTH]
PAYLOAD TRACKING OFF
PAYLOAD TRACKING STATUS

Defaults:

Duration: 60 seconds
Sample rate: 1 (every command)
Mode: BOTH directions

Tracking automatically expires after the configured duration.

STATUS reports:

• enabled state
• remaining seconds
• sample rate
• mode

Invalid/expired state reports cleanly.

STATUS Example

> PAYLOAD TRACKING STATUS
1) "enabled"
2) (integer) 1
3) "remaining_seconds"
4) (integer) 117
5) "sample_rate"
6) (integer) 10
7) "mode"
8) "read"

PAYLOAD HISTOGRAM

PAYLOAD HISTOGRAM [read|write]
PAYLOAD HISTOGRAM RESET

Returns per view bucket distributions.
RESET clears accumulated samples for a new observation window.

Bucketing Model

Each configured view represents a base payload size.
Buckets grow multiplicatively by payload-histogram-factor.

Runtime Config

• payload-histogram-views
  Default: 32kb 64kb 128kb 256kb 512kb

• payload-histogram-factor
  Default: 2

• payload-tracking (bool)
  Global enable/disable guard.

Buckets are non cumulative. Output includes:

calls: total recorded samples

histogram_bytes: upper-bound → count pairs

This keeps memory bounded and predictable.

Operational Example

> PAYLOAD TRACKING ON 120 SAMPLE 10 READ
OK

Tracks read payload sizes for 120 seconds, sampling 1 out of every 10 commands.

> PAYLOAD HISTOGRAM RESET
OK

Clears counters for a fresh observation window.

> PAYLOAD HISTOGRAM read
...

Returns per-bucket distribution for sampled reads.

Example:

> PAYLOAD HISTOGRAM read
1) "read"
2) 1) "32768"
   2) 1) "calls"
      2) (integer) 1200
      3) "histogram_bytes"
      4) 1) (integer) 32768
         2) (integer) 480
         3) (integer) 65536
         4) (integer) 310
         5) (integer) 131072
         6) (integer) 180

Explanation:

• "read" indicates direction.
• "32768" represents the configured base view (32KB).
• "calls" is total samples recorded for that direction.
• "histogram_bytes" maps bucket upper bounds to per-bucket counts (non-cumulative).

In this example:

• 480 samples were ≤ 32KB
• 310 samples were in (32KB, 64KB]
• 180 samples were in (64KB, 128KB]

Performance & Overhead

• When tracking is OFF:
  No additional instrumentation executed on command path.

• When ON:
  Overhead is proportional to sampling rate and duration.

• Memory usage is bounded by:
  Number of configured views
  Multiplicative bucket expansion factor

[codecov]

Codecov Report

❌ Patch coverage is 54.50450% with 101 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.88%. Comparing base (839d0c6) to head (cfb77d6).
⚠️ Report is 15 commits behind head on unstable.

Files with missing lines	Patch %	Lines
src/payload_histogram.c	41.25%	84 Missing ⚠️
src/config.c	73.33%	12 Missing ⚠️
src/server.c	85.29%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           unstable    #3191      +/-   ##
============================================
- Coverage     74.96%   74.88%   -0.09%     
============================================
  Files           129      130       +1     
  Lines         71318    71550     +232     
============================================
+ Hits          53467    53583     +116     
- Misses        17851    17967     +116     

Files with missing lines	Coverage Δ
src/commands.def	100.00% <ø> (ø)
src/server.h	100.00% <ø> (ø)
src/server.c	89.42% <85.29%> (-0.02%)	⬇️
src/config.c	78.41% <73.33%> (-0.15%)	⬇️
src/payload_histogram.c	41.25% <41.25%> (ø)

... and 18 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.