Events README: request telemetry (telemetry_samples, one-minute aggregates, 14 days) (#86)

OP OpenVibers committed 29 days ago · ad094138de · 1 file, +2 −0

Changes

ddiff --git a/README.md b/README.md
iindex d891c4b..5c96092 100644
---- a/README.md
++++ b/README.md
@@@ -28,6 +28,8 @@ Node 22 in production (`fnm exec --using=22.22.1 npm test`). Production: `/opt/o
  
  `GET /metrics` (Prometheus text, direct loopback callers only — a request carrying `X-Forwarded-For` gets 404, and nginx refuses the path): HTTP golden signals by route template (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`; SSE sessions excluded), process metrics, `release_info`, and `events_deliveries{status}`, `events_dlq_depth`, `events_latest_seq`, `events_realtime_connections`, `events_delivery_latency_seconds{priority}` (acceptance → successful delivery, retries included), `events_delivery_attempts_total{outcome}`. `GET /release.json` is the deployed release (ADR-016, `release.mount` from openvibe-shared 1.5.0, with the manifest 1.1.0 fields under openvibe-contracts 0.32.0); its `POST /release-metrics` would count open tabs' update reports as `release_client_updates_total`, but Events has no pages and nginx does not proxy that path. `GET /limits.json` lists the developer limits enforced here (per project and environment), read from the running config; [openvibe.services/docs/limits](https://openvibe.services/docs/limits) renders it.
  
++Requests are also recorded for this service's own use (openvibe-sdk 0.46 telemetry, the `platform.telemetry-sample@1` shape): each HTTP request is aggregated by route template, method and status class, never by raw URL, and once a minute one `http.request` sample per key, plus the active-requests, p95 latency and event-loop-lag gauges, is written to the `telemetry_samples` table, with rows older than 14 days deleted daily. `/shared` files, static assets, health, readiness and `/metrics` are not counted. `server/app.js` mounts openvibe-sdk's `telemetryMiddleware` (a no-op until init) and `server/index.js` calls `telemetry.init()` at production start, runs the 14-day retention and flushes on stop; the table comes from migration 0009 (`migrations/0009_telemetry.sql`).
++
  ## Auth
  
  Services call with an OpenVibe.Network client-credentials token (`POST /oauth/token`, `audience=openvibe.events`), verified offline against the Network JWKS (openvibe-sdk/auth `verifyServiceToken` with the pinned openvibe-contracts rules; people's tokens with `verifyUserToken`, which refuses service principals and typed tokens). Each route checks one capability:

diff --git a/README.md b/README.md

index d891c4b..5c96092 100644

--- a/README.md

+++ b/README.md

@@ -28,6 +28,8 @@ Node 22 in production (`fnm exec --using=22.22.1 npm test`). Production: `/opt/o

`GET /metrics` (Prometheus text, direct loopback callers only — a request carrying `X-Forwarded-For` gets 404, and nginx refuses the path): HTTP golden signals by route template (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`; SSE sessions excluded), process metrics, `release_info`, and `events_deliveries{status}`, `events_dlq_depth`, `events_latest_seq`, `events_realtime_connections`, `events_delivery_latency_seconds{priority}` (acceptance → successful delivery, retries included), `events_delivery_attempts_total{outcome}`. `GET /release.json` is the deployed release (ADR-016, `release.mount` from openvibe-shared 1.5.0, with the manifest 1.1.0 fields under openvibe-contracts 0.32.0); its `POST /release-metrics` would count open tabs' update reports as `release_client_updates_total`, but Events has no pages and nginx does not proxy that path. `GET /limits.json` lists the developer limits enforced here (per project and environment), read from the running config; [openvibe.services/docs/limits](https://openvibe.services/docs/limits) renders it.

+Requests are also recorded for this service's own use (openvibe-sdk 0.46 telemetry, the `platform.telemetry-sample@1` shape): each HTTP request is aggregated by route template, method and status class, never by raw URL, and once a minute one `http.request` sample per key, plus the active-requests, p95 latency and event-loop-lag gauges, is written to the `telemetry_samples` table, with rows older than 14 days deleted daily. `/shared` files, static assets, health, readiness and `/metrics` are not counted. `server/app.js` mounts openvibe-sdk's `telemetryMiddleware` (a no-op until init) and `server/index.js` calls `telemetry.init()` at production start, runs the 14-day retention and flushes on stop; the table comes from migration 0009 (`migrations/0009_telemetry.sql`).

## Auth

Services call with an OpenVibe.Network client-credentials token (`POST /oauth/token`, `audience=openvibe.events`), verified offline against the Network JWKS (openvibe-sdk/auth `verifyServiceToken` with the pinned openvibe-contracts rules; people's tokens with `verifyUserToken`, which refuses service principals and typed tokens). Each route checks one capability: