SDK docs: createHttpTelemetry needs the caller's flush timer (#48)

OP OpenVibers committed 29 days ago · aa210566c0 · 1 file, +8 −1

* SDK docs: createHttpTelemetry needs the caller's flush timer

Documentation only. The usage example for `createHttpTelemetry()` showed the middleware plus a `stop()` at shutdown, but a collector built that way never ticks. Its aggregation map is emitted only by `flush()` or `stop()`, and the inner buffer's timer flushes only samples that were already emitted. Followed literally, the example writes request samples only when the process stops. That happened in Blog and the services wired on 2026-10-15; each now runs its own 15 s tick.

The example now shows the caller's timer, and a paragraph explains when a timer is needed (the singleton `init()` already has one). No behaviour change: making the collector tick by default would double-tick every service that now runs its own timer.

* SDK docs: eight services, not nine

Changes

ddiff --git a/src/service/telemetry.js b/src/service/telemetry.js
iindex 61c1183..b944379 100644
---- a/src/service/telemetry.js
++++ b/src/service/telemetry.js
@@@ -12,7 +12,14 @@
   *       routeLabel: (req) => metrics.routeLabel(req),              // optional; the default reads req.route.path
   *   });
   *   app.use(collector.middleware());
-- *   svc.gracefulStop({ name: 'Blog', server, stop: [() => collector.stop()] });   // one flush at shutdown
++ *   const tick = setInterval(() => { collector.flush().catch(() => {}); }, 15000);   // the caller's timer, see below
++ *   tick.unref();
++ *   svc.gracefulStop({ name: 'Blog', server, stop: [() => { clearInterval(tick); return collector.stop(); }] });
++ *
++ * A collector made with createHttpTelemetry() has NO timer of its own: each interval's requests stay in its
++ * aggregation map until flush() or stop() emits them (the inner buffer's timer only flushes samples already
++ * emitted). Call flush() on a timer, as above, or use the singleton below, whose init() runs that timer; with
++ * neither, a service writes its request samples only when it stops (Blog and eight services did, 2026-10-15).
   *
   * The process-wide singleton keeps Network's shape, for services that just want it wired at boot:
   * `svc.telemetry.init({ service, sink, … })` starts the flush timer and the event-loop monitor,