92 lines
2.0 KiB
Markdown
92 lines
2.0 KiB
Markdown
# 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
|
||
|
||
```js
|
||
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:
|
||
|
||
```js
|
||
{
|
||
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()`
|
||
|
||
```js
|
||
{ 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
|
||
|
||
```bash
|
||
npm install && npm test
|
||
```
|