Put the HTTP telemetry middleware and signals in the service kit (#14)

OP OpenVibers committed 5 Oct 2026 · tag v0.31. · 0 files, +0 −0
* Put the HTTP telemetry middleware and signals in the service kit

**Files changed**
- `src/service/telemetry.js` (new): the HTTP telemetry kit lifted from Network's `server/telemetry.js` + the telemetry half of `server/observability.js` — `createHttpTelemetry` (collector with `middleware()`, `requestStarted`/`requestFinished`/`observeRequest`, `flush`, `stop`), `createTelemetryMiddleware`, `telemetrySkipped`, `defaultRouteLabel`, `registerSignals`, the event-loop monitor (`start`/`stop`/`eventLoopLagMs`/`eventLoopMonitorEnabled`), the `telemetry.{init,record,gauge,count,requestStarted,requestFinished,flush,stop}` singleton + `telemetryMiddleware`, and re-exported `telemetrySample`/`validateTelemetrySample`. Aggregation is per `route|method|status_class` per flush (one `http.request` sample/key, mean in `latency_ms`, count/sum/max/p95 in `extra`), plus active-requests/p95/lag gauges once per flush; `init` starts the monitor and timer, `stop` stops both and flushes once, requiring the module starts nothing.
- `src/service/index.js`: merged `...telemetry` into the kit export (line 23) and documented the middleware/init/stop wiring in the header.
- `esm/service.mjs`: regenerated with `node scripts/esm.js` for the new names (checked in, tested for staleness).
- `types/service.d.ts`: declarations for every new runtime export (`TelemetrySample`, `HttpTelemetry`, options, signals, singleton, constants).
- `test/service-telemetry.test.js` (new): skips/probes, per-key aggregation with every sample validated against `platform.telemetry-sample@1`, one-flush batches, gauges once per flush, stop-flushes-once/idempotent, real-http middleware route-template + health skip, `registerSignals` injection, and the singleton monitor lifecycle.
- `docs/service.md`: new “The telemetry” section (adoption recipe, field mapping, skip defaults, Network/Community migration).
- `README.md`: service-kit module-table row and the “Service kit (server)” prose now cover the telemetry kit.
- `STATUS.json`: feature line for the HTTP telemetry kit.
- `CHANGELOG.md`: bullet under the in-flight `0.29.0` section.

**Tests run**
- `ov test service-telemetry.test.js esm.test.js types.test.js telemetry.test.js version.test.js` → ✅ `5 passed in 2 s`
- `node test/run.js service-telemetry esm types telemetry version browser-entries` → ✅ `6/6 test files passed`
- `node test/service.test.js` → ✅ all 13 cases ok

**Not done / deliberate deviations**
- Did not run `test/pack.test.js`: it `npm pack`s and installs the tarball into a temp project, and the brief says not to install packages. `src/` is in the package `files` list, so the new module ships; `types`/`esm` checks pass.
- No version bump: appended to the current `0.29.0` entry (the repo’s precedent for a feature landing during an in-flight release, cf. PR #10) instead of touching `package.json`/`package-lock.json`/the browser bundle.
- No `instance` field is emitted: `platform.telemetry-sample@1` is `additionalProperties: false` and has no `instance`, so samples carrying it fail validation. Network only emitted it when configured (production `init({ analytics })` passes none), so this is not a behavior regression. Network’s analytics-specific `analyticsSink`/`eventName` were intentionally not lifted — the SDK collector takes a generic `sink`.
- Not committed/pushed, per instructions.

* Telemetry: unmatched routes and a key cap, /shared skipped by default, bounded latencies, init stops the old collector; release 0.31.0 (review)

**Changes**

- `src/service/telemetry.js:142` — `defaultRouteLabel` now returns `'unmatched'` when `req.route` is absent (404s/scanners no longer leak raw paths); routed requests keep the `baseUrl + req.route.path` template.
- `src/service/telemetry.js:45,159-160,186` — per-flush key cap `DEFAULT_MAX_ROUTE_KEYS = 500` (overridable `maxRouteKeys`): a new key past the cap folds its route label to `'other'`, so the map is bounded.
- `src/service/telemetry.js:47,65,182,232` — each bucket's latencies and the flush-wide `allLatencies` are fixed-capacity reservoirs (`LATENCY_SAMPLE_CAP = 10000`); count/sum/max stay exact, p95 comes from the sample.
- `src/service/telemetry.js:204,270` — added `collector.bufferStats()` (keys/latencies/maxKeyLatencies) for diagnostics/tests.
- `src/service/telemetry.js:49,130,159` — `skipPrefixes` defaults to `['/shared']` (pass `[]` to disable); header documents that OpenVibe.Network passes `['/shared','/api/chrome']`.
- `src/service/telemetry.js:322` — `init` clears the old flush timer and calls `previous.stop()` (emit + flush) before replacing `current`.
- `src/service/telemetry.js:360-364` + `types/service.d.ts:170,184,211,223,248-250` — declared the new option/exports/method; `esm/service.mjs:7` regenerated.
- `test/service-telemetry.test.js:181,189,203,214,236,251` — new cases: unmatched label, 1000 distinct 404s → one key, cap overflow → `other`, default skip prefix, 50k requests capped/exact, double-init flush.
- `package.json:3`, `package-lock.json:3,9`, `src/core/index.js:11`, `STATUS.json:6,31`, `browser/openvibe-sdk.mjs:1,45` — version 0.31.0 / updated 2026-10-05 / regenerated bundle.
- `CHANGELOG.md:10` — new `## 0.31.0 (2026-10-05)` section; telemetry entry moved out of `## 0.29.0` (kept verbatim plus the hardening notes).
- `README.md:5,12,396,400` and `docs/service.md:170,179` — current version named 0.31.0; skip-prefix default/Network prefixes and bounded-memory/unmatched documented.

**Tests**

`ov test test/service-telemetry.test.js test/service.test.js test/types.test.js test/version.test.js test/bundle.test.js test/pack.test.js test/esm.test.js test/browser-entries.test.js` → **8 passed in 4 s**. Direct `node test/service-telemetry.test.js` → 14/14 cases ok (including the 50k-request buffer-cap and double-init cases).
This commit has no diff to show.