modules/measurement-rate-control/hyper-p2p-histogram-gossip/docs/api.md

API: hyper-p2p-histogram-gossip

Export: { HyperP2PHistogramGossip, PROTOCOL }
Protocol: histogram-gossip/v1

Overview

HyperP2PHistogramGossip maintains per-metric fixed-bucket histograms locally and merges remote bucket snapshots from peers. Each observe updates min/max, increments bucket counts, and gossips histogram-buckets for swarm-wide percentile estimates.

Constructor

const { HyperP2PHistogramGossip } = require('hyper-p2p-histogram-gossip')
const hist = new HyperP2PHistogramGossip(opts)

Option	Type	Default	Description
topic	string | Buffer | null	null	Swarm topic
keyPair	KeyPair	new key pair	peerHex on gossip
buckets	number	10	Bucket count per metric

Methods

observe(metric, value)

• metric non-empty string; value finite number
• Updates histogram, emits observe
• Gossips:

{
  type: 'histogram-buckets',
  metric, min, max, counts: [...],
  peer, at
}

percentile(metric, p)

• p clamped 0–100
• Estimates percentile from merged bucket counts
• Returns: null if no observations

snapshot(metric)

Returns { metric, min, max, counts, total } or null.

metrics()

Sorted metric names.

getStats()

{ observed, gossipIn, gossipOut, metrics, protocol }

ready() / close()

Standard initModuleSwarm lifecycle.

Merge logic _mergeBuckets

• Expands min/max to include remote
• Adds bucket counts element-wise
• Adds remote total from sum of remote counts

Events

Event	Payload
observe	{ metric, value }
remote-buckets	{ metric, peer }
closed	—

Wire messages

type	fields
histogram-buckets	metric, min, max, counts, peer, at

Bucket indexing

When min === max, all mass goes to bucket 0. Otherwise linear bins across [min, max].

Testing

npm install && npm test