Subs batch: hyper-instrument + hyper-multisig-cli (2026-02-19_10:28)

modules/hyper-instrument.md

@@ -0,0 +1,169 @@
+# Hyper-Instrument Research
+
+## Overview
+
+Hyper-instrument (v3.0.1) is a lightweight instrumentation library for Hypercore ecosystem services. It enables Prometheus-compatible metrics collection and decentralized scraping via DHT-Prometheus. Supports Node.js and Bare runtimes from Holepunch.
+
+**Key Features:**
+- Auto-instruments HyperDHT/Hyperswarm/Corestore using dedicated stats modules.
+- Registers service instance with DHT-based Prometheus scraper (pub/secret keys, alias).
+- Exposes prom-client for custom metrics.
+- Tracks versions of core Holepunch modules.
+- Integrates with Grafana dashboard for visualization.
+
+**Links:**
+- [GitHub](https://github.com/holepunchto/hyper-instrument)
+- [NPM](https://www.npmjs.com/package/hyper-instrument)
+- [Grafana Dashboard](https://grafana.com/grafana/dashboards/22313-hypercore-hyperswarm/)
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph "P2P App/Service"
+        UserApp[User App] --> DHTSwarm[HyperDHT / Hyperswarm]
+        UserApp --> CS[Corestore opt]
+    end
+    HI[HyperInstrument] -- instruments stats --> DHTSwarm
+    HI -- instruments stats --> CS
+    HI -- collects --> Prom[prom-client]
+    HI -- manages --> DHTProm[DHTPromClient]
+    DHTProm -- P2P register/scrape --> DHTScraper[DHT Prometheus]
+    Prom -- HTTP /metrics --> Grafana[Grafana / Prometheus]
+```
+
+## Package.json Highlights
+
+**Dependencies Table:**
+
+| Type | Name | Version | Purpose |
+|------|------|---------|---------|
+| Stats | hypercore-stats | ^2.0.0 | Corestore/Hypercore metrics |
+| | hyperdht-stats | ^1.1.0 | DHT node stats |
+| | hyperswarm-stats | ^1.1.3 | Swarm connections/handshakes |
+| Prom | bare-prom-client | ^15.1.4 | Bare-compatible Prometheus client |
+| | dht-prom-client | ^2.0.1 | P2P Prometheus over DHT |
+| Bare | bare-os, bare-path, etc. | Latest | Runtime polyfills |
+| Utils | ready-resource | ^1.1.1 | Async resource mgmt |
+| | which-runtime | ^1.3.0 | Detect Bare/Node |
+
+Dev deps: hypercore@^11, hyperswarm@^4.8.4, etc. for testing.
+
+Imports: Polyfills path/process for Bare.
+
+## Usage Examples
+
+### Minimal DHT Instrumentation
+
+```javascript
+const HyperInstrument = require('hyper-instrument')
+const HyperDHT = require('hyperdht')
+const { version } = require('./package.json')
+
+const dht = new HyperDHT()
+
+const inst = new HyperInstrument({
+  dht,
+  scraperPublicKey: Buffer.from('...', 'hex'), // or z32/hex str
+  scraperSecret: Buffer.from('...', 'hex'),
+  prometheusAlias: 'my-service-instance-123',
+  prometheusServiceName: 'my-p2p-app',
+  version: version
+})
+
+await inst.ready()  // Starts DHT registration & metrics
+
+// Custom metric example
+const customGauge = new inst.promClient.Gauge({
+  name: 'custom_user_count',
+  help: 'Active users',
+  collect() {
+    return Math.random() * 100  // Example
+  }
+})
+
+inst.registerLogger(console)  // Optional logging
+```
+
+### Full Swarm + Corestore
+
+```javascript
+const Hyperswarm = require('hyperswarm')
+const Corestore = require('corestore')
+
+const swarm = new Hyperswarm()
+const corestore = new Corestore('./mystorage')
+
+const inst = new HyperInstrument({
+  swarm,  // auto-uses swarm.dht
+  corestore,
+  // ... scraper config
+})
+
+await inst.ready()
+await inst.close()  // Cleanup
+```
+
+## Deep Code Analysis (index.js)
+
+Single ~3.4k char file. Clean, modular.
+
+**Class Structure:**
+```javascript
+class HyperInstrumentation extends ReadyResource {
+  constructor(opts) { /* validate, init stats, promClient */ }
+  get promClient() { return this.dhtPromClient.promClient }
+  async _open() { await this.dhtPromClient.ready() }
+  async _close() { await this.dhtPromClient.close() }
+  registerLogger(logger = console) { /* log setup */ }
+}
+```
+
+**Init Flow:**
+1. Validate: exactly one of `dht`/`swarm`.
+2. Default `moduleVersions`: ['udx-native', 'dht-rpc', 'hyperdht', ... 'hyperdb']
+3. `promClient.collectDefaultMetrics()`
+4. Register gauges:
+   - `package_version{version=}"1"` (label)
+   - `{module}_version` for each module (try require(pkg)/package.json)
+   - `process_pid`
+5. Instantiate/register stats:
+   - `HyperswarmStats(swarm)` or `HyperDhtStats(dht)`
+   - `HypercoreStats.fromCorestore(corestore)` if provided
+6. `DhtPromClient(dht, promClient, pubKey, alias, secret, service)`
+
+**Error Handling:** Logs internal errors from hypercore-stats.
+
+## Exposed Metrics (Examples)
+
+| Metric | Labels | Source | Description |
+|--------|--------|--------|-------------|
+| hyperswarm_connections_total | - | hyperswarm-stats | Total swarm connections |
+| hyperdht_lookup_time_seconds | topic, success | hyperdht-stats | DHT lookup latency |
+| hypercore_blocks_downloaded_total | core_id | hypercore-stats | Replicated blocks |
+| process_cpu_seconds_total | mode | prom-client default | CPU usage |
+| hypercore_version | hypercore_version | hyper-instrument | "11.0.0"=1 |
+| process_pid | - | hyper-instrument | OS PID |
+
+Full list via stats modules + defaults.
+
+## Use Cases & Integrations
+
+1. **Swarm Health Monitoring:** Track peer counts, handshake fails in Hyperswarm apps (e.g., Keet file sharing).
+2. **Replication Dashboard:** Visualize Hypercore sync progress, bitfield completion in distributed DBs (Hyperbee/Autobase).
+3. **Decentralized Ops:** DHT-scraped metrics; no central server vuln.
+4. **Pear Runtime Apps:** Bare-compatible for desktop/mobile P2P apps.
+5. **Custom Prod Metrics:** Gauge app KPIs alongside P2P primitives.
+6. **Fleet Scaling:** Unique `prometheusAlias` per node (e.g., Docker swarm).
+
+**Example Prod Setup:** Pear app with hyperswarm for discovery, hyper-instrument for Grafana export.
+
+## Relations in Holepunch Ecosystem
+
+- Builds on: hypercore-stats (Corestore metrics), hyperswarm-stats (swarm), hyperdht-stats (DHT).
+- Enables: Grafana-hypercore-stats dashboard.
+- Used in: Production Holepunch services for observability.
+
+**Status:** Complete analysis. Added ~4500 chars. Ready for integration.
+
+**Sources:** GitHub raw, NPM, web searches, code review.