@observtech/rum 0.1.32 → 0.1.34

package/README.md

@@ -13,8 +13,18 @@ A single `observ.init()` wires all of the following, each stamped with the same
 - **Session replay** — `@rrweb/record` DOM capture, sent as gzip chunks.
 - **Traces** — `http.client` spans for `fetch`/`XHR` + page load, over OTLP/HTTP,
   with W3C `traceparent` propagation (so front and backend traces stitch).
+- **Session lifecycle** — `session.start` / `session.end` events with
+  `previous_id` chaining, a 30 min inactivity window + 4 h hard cap, and an
+  activity sweep (per-tab `sessionStorage` by default; opt-in cross-tab).
+- **End-user identity** — `enduser.pseudo.id` (anonymous, persistent) on every
+  signal, plus `enduser.id` once you call `setUser()`.
 - **Semantic events** — `click`, `rage_click`, `navigate` as OTel log records.
+- **Page views** — rich `app.page_view` (referrer, time-on-page, navigation type).
 - **JS errors** — uncaught errors and unhandled promise rejections, observe-only.
+- **Console forwarding** — optionally mirror `console.*` to the logs pipeline.
+- **User-interaction spans** — optional click/submit/keydown spans with
+  `ZoneContextManager` (opt-in; pulls in `zone.js`).
+- **Consent gate** — optionally hold ALL telemetry until GDPR analytics consent.
 - **PII masking** — input values are masked by default (safe-by-default).
 
 `observ.init()` is **idempotent** and **never throws**: any setup failure
@@ -45,13 +55,26 @@ observ.init({
 
 Main options:
 
-| Option                         | Type                   | Default | Role                                                                   |
-| ------------------------------ | ---------------------- | ------- | ---------------------------------------------------------------------- |
-| `endpoint`                     | `string`               | —       | Base URL of the Observ backend (`/v1/...` paths are appended).         |
-| `key`                          | `string`               | —       | API key sent as `x-observ-key` (empty ⇒ header omitted).               |
-| `propagateTraceHeaderCorsUrls` | `(string \| RegExp)[]` | `[]`    | Cross-origin backends allowed to receive the W3C `traceparent` header. |
-| `disableReplay`                | `boolean`              | `false` | Keep tracing/events but turn off the heavy rrweb replay.               |
-| `privacy`                      | `PrivacyOptions`       | masked  | PII masking of the replay stream (see below).                          |
+| Option                                           | Type                        | Default                                                 | Role                                                                   |
+| ------------------------------------------------ | --------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `endpoint`                                       | `string`                    | —                                                       | Base URL of the Observ backend (`/v1/...` paths are appended).         |
+| `key`                                            | `string`                    | —                                                       | API key sent as `x-observ-key` (empty ⇒ header omitted).               |
+| `propagateTraceHeaderCorsUrls`                   | `(string \| RegExp)[]`      | `[]`                                                    | Cross-origin backends allowed to receive the W3C `traceparent` header. |
+| `disableReplay`                                  | `boolean`                   | `false`                                                 | Keep tracing/events but turn off the heavy rrweb replay.               |
+| `privacy`                                        | `PrivacyOptions`            | masked                                                  | PII masking of the replay stream (see below).                          |
+| `serviceName` / `serviceVersion` / `environment` | `string`                    | —                                                       | Resource attributes (`service.name`, …) stamped on every signal.       |
+| `sampleRate`                                     | `number`                    | `1`                                                     | Head-based trace sampling ratio in `[0,1)` (ParentBased).              |
+| `propagateBaggage`                               | `boolean`                   | `false`                                                 | Send `session.id` to allowed backends via the W3C `baggage` header.    |
+| `disableMetrics`                                 | `boolean`                   | `false`                                                 | Turn off Core Web Vitals + OTLP metrics.                               |
+| `sessionInactivityMs`                            | `number`                    | 30 min                                                  | Inactivity window before the `session.id` rotates.                     |
+| `sessionMaxDurationMs`                           | `number`                    | 4 h                                                     | Hard cap on a single session's duration (rotates even while active).   |
+| `crossTabSessions`                               | `boolean`                   | `false`                                                 | Share one session across tabs (`localStorage`) instead of per-tab.     |
+| `disablePseudoUser`                              | `boolean`                   | `false`                                                 | Disable the persistent pseudonymous `enduser.pseudo.id`.               |
+| `forwardConsole`                                 | `boolean \| ConsoleLevel[]` | `false`                                                 | Mirror `console.*` to the logs pipeline (all levels, or a subset).     |
+| `disablePageViews`                               | `boolean`                   | `false`                                                 | Turn off rich `app.page_view` events.                                  |
+| `userInteraction`                                | `boolean`                   | `false`                                                 | Interaction spans + `ZoneContextManager` (opt-in; pulls in `zone.js`). |
+| `requireConsent`                                 | `boolean`                   | `false`                                                 | Hold ALL telemetry until analytics consent is present (see below).     |
+| `consentKey` / `consentGrantedValues`            | `string` / `string[]`       | `observ.consent` / `['granted','true','1','yes','all']` | Where/what consent is read from.                                       |
 
 ### Privacy / PII masking
 
@@ -74,6 +97,61 @@ observ.init({
 })
 ```
 
+### End-user identity
+
+Every signal carries a pseudonymous `enduser.pseudo.id` (persisted in
+`localStorage`, anonymous). After sign-in, attach the authenticated identity; clear
+it on sign-out:
+
+```ts
+observ.setUser({ id: user.id, role: user.role, name: user.name }) // → enduser.id/role/name
+observ.clearUser() // on logout (the pseudo id persists)
+```
+
+### Sessions
+
+A `session.id` is shared by every signal. It rotates after 30 min of inactivity or
+a 4 h hard cap, emitting `session.start` (with `session.previous_id` on a
+continuation) and a best-effort `session.end` (with `session.duration_ms`). Sessions
+are **per-tab** (`sessionStorage`) by default — two tabs are two visits, by design.
+Set `crossTabSessions: true` to share one session across a visitor's tabs.
+
+### Console forwarding (optional)
+
+```ts
+observ.init({ endpoint, key, forwardConsole: ['warn', 'error'] }) // or `true` for all levels
+```
+
+Off by default — console output can be noisy and may contain PII. The original
+`console.*` is always still called.
+
+### User-interaction spans (optional)
+
+```ts
+observ.init({ endpoint, key, userInteraction: true })
+```
+
+Turns clicks/submits/keydowns into spans with a `ZoneContextManager` so trace
+context survives the async work they trigger. **Opt-in**: it pulls in `zone.js`,
+which monkey-patches the host's global timers/`Promise` on import — so it is
+dynamically loaded only when enabled (the default bundle and host globals stay
+untouched).
+
+### Consent (GDPR)
+
+Hold ALL telemetry until analytics consent is present (no session, no persistent
+id, no network):
+
+```ts
+observ.init({ endpoint, key, requireConsent: true }) // reads cookie/localStorage `observ.consent`
+// …later, from your consent banner:
+observ.grantConsent() // persists consent + starts the waiting SDK
+observ.revokeConsent() // clears consent + shuts the SDK down
+```
+
+The SDK also auto-starts if another tab grants consent (via the `storage` event) or
+the banner writes the key in this tab (a light poll picks it up).
+
 ### Stop (optional)
 
 ```ts

package/dist/chunk-P6VK4P6W.js

@@ -0,0 +1,42 @@
+import { trace, metrics } from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
+
+// node_modules/@opentelemetry/instrumentation/build/esm/autoLoader.js
+
+// node_modules/@opentelemetry/instrumentation/build/esm/autoLoaderUtils.js
+function enableInstrumentations(instrumentations, tracerProvider, meterProvider, loggerProvider) {
+  for (let i = 0, j = instrumentations.length; i < j; i++) {
+    const instrumentation = instrumentations[i];
+    if (tracerProvider) {
+      instrumentation.setTracerProvider(tracerProvider);
+    }
+    if (meterProvider) {
+      instrumentation.setMeterProvider(meterProvider);
+    }
+    if (loggerProvider && instrumentation.setLoggerProvider) {
+      instrumentation.setLoggerProvider(loggerProvider);
+    }
+    if (!instrumentation.getConfig().enabled) {
+      instrumentation.enable();
+    }
+  }
+}
+function disableInstrumentations(instrumentations) {
+  instrumentations.forEach((instrumentation) => instrumentation.disable());
+}
+
+// node_modules/@opentelemetry/instrumentation/build/esm/autoLoader.js
+function registerInstrumentations(options) {
+  const tracerProvider = options.tracerProvider || trace.getTracerProvider();
+  const meterProvider = options.meterProvider || metrics.getMeterProvider();
+  const loggerProvider = options.loggerProvider || logs.getLoggerProvider();
+  const instrumentations = options.instrumentations?.flat() ?? [];
+  enableInstrumentations(instrumentations, tracerProvider, meterProvider, loggerProvider);
+  return () => {
+    disableInstrumentations(instrumentations);
+  };
+}
+
+export { registerInstrumentations };
+//# sourceMappingURL=chunk-P6VK4P6W.js.map
+//# sourceMappingURL=chunk-P6VK4P6W.js.map

package/dist/chunk-P6VK4P6W.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../node_modules/@opentelemetry/instrumentation/src/autoLoaderUtils.ts","../node_modules/@opentelemetry/instrumentation/src/autoLoader.ts"],"names":[],"mappings":";;;;;;AAeM,SAAU,sBAAA,CACd,gBAAA,EACA,cAAA,EACA,aAAA,EACA,cAAA,EAA+B;AAE/B,EAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,iBAAiB,MAAA,EAAQ,CAAA,GAAI,GAAG,CAAA,EAAA,EAAK;AACvD,IAAA,MAAM,eAAA,GAAkB,iBAAiB,CAAC,CAAA;AAC1C,IAAA,IAAI,cAAA,EAAgB;AAClB,MAAA,eAAA,CAAgB,kBAAkB,cAAc,CAAA;;AAElD,IAAA,IAAI,aAAA,EAAe;AACjB,MAAA,eAAA,CAAgB,iBAAiB,aAAa,CAAA;;AAEhD,IAAA,IAAI,cAAA,IAAkB,gBAAgB,iBAAA,EAAmB;AACvD,MAAA,eAAA,CAAgB,kBAAkB,cAAc,CAAA;;AAMlD,IAAA,IAAI,CAAC,eAAA,CAAgB,SAAA,EAAS,CAAG,OAAA,EAAS;AACxC,MAAA,eAAA,CAAgB,MAAA,EAAM;;;AAG5B;AAMM,SAAU,wBACd,gBAAA,EAAmC;AAEnC,EAAA,gBAAA,CAAiB,OAAA,CAAQ,CAAA,eAAA,KAAmB,eAAA,CAAgB,OAAA,EAAS,CAAA;AACvE;;;AC/BM,SAAU,yBACd,OAAA,EAA0B;AAE1B,EAAA,MAAM,cAAA,GAAiB,OAAA,CAAQ,cAAA,IAAkB,KAAA,CAAM,iBAAA,EAAiB;AACxE,EAAA,MAAM,aAAA,GAAgB,OAAA,CAAQ,aAAA,IAAiB,OAAA,CAAQ,gBAAA,EAAgB;AACvE,EAAA,MAAM,cAAA,GAAiB,OAAA,CAAQ,cAAA,IAAkB,IAAA,CAAK,iBAAA,EAAiB;AACvE,EAAA,MAAM,gBAAA,GAAmB,OAAA,CAAQ,gBAAA,EAAkB,IAAA,MAAU,EAAA;AAE7D,EAAA,sBAAA,CACE,gBAAA,EACA,cAAA,EACA,aAAA,EACA,cAAc,CAAA;AAGhB,EAAA,OAAO,MAAK;AACV,IAAA,uBAAA,CAAwB,gBAAgB,CAAA;AAC1C,EAAA,CAAA;AACF","file":"chunk-P6VK4P6W.js","sourcesContent":["/*\n * Copyright The OpenTelemetry Authors\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { TracerProvider, MeterProvider } from '@opentelemetry/api';\nimport type { Instrumentation } from './types';\nimport type { LoggerProvider } from '@opentelemetry/api-logs';\n\n/**\n * Enable instrumentations\n * @param instrumentations\n * @param tracerProvider\n * @param meterProvider\n */\nexport function enableInstrumentations(\n  instrumentations: Instrumentation[],\n  tracerProvider?: TracerProvider,\n  meterProvider?: MeterProvider,\n  loggerProvider?: LoggerProvider\n): void {\n  for (let i = 0, j = instrumentations.length; i < j; i++) {\n    const instrumentation = instrumentations[i];\n    if (tracerProvider) {\n      instrumentation.setTracerProvider(tracerProvider);\n    }\n    if (meterProvider) {\n      instrumentation.setMeterProvider(meterProvider);\n    }\n    if (loggerProvider && instrumentation.setLoggerProvider) {\n      instrumentation.setLoggerProvider(loggerProvider);\n    }\n    // instrumentations have been already enabled during creation\n    // so enable only if user prevented that by setting enabled to false\n    // this is to prevent double enabling but when calling register all\n    // instrumentations should be now enabled\n    if (!instrumentation.getConfig().enabled) {\n      instrumentation.enable();\n    }\n  }\n}\n\n/**\n * Disable instrumentations\n * @param instrumentations\n */\nexport function disableInstrumentations(\n  instrumentations: Instrumentation[]\n): void {\n  instrumentations.forEach(instrumentation => instrumentation.disable());\n}\n","/*\n * Copyright The OpenTelemetry Authors\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { trace, metrics } from '@opentelemetry/api';\nimport { logs } from '@opentelemetry/api-logs';\nimport {\n  disableInstrumentations,\n  enableInstrumentations,\n} from './autoLoaderUtils';\nimport type { AutoLoaderOptions } from './types_internal';\n\n/**\n * It will register instrumentations and plugins\n * @param options\n * @return returns function to unload instrumentation and plugins that were\n *   registered\n */\nexport function registerInstrumentations(\n  options: AutoLoaderOptions\n): () => void {\n  const tracerProvider = options.tracerProvider || trace.getTracerProvider();\n  const meterProvider = options.meterProvider || metrics.getMeterProvider();\n  const loggerProvider = options.loggerProvider || logs.getLoggerProvider();\n  const instrumentations = options.instrumentations?.flat() ?? [];\n\n  enableInstrumentations(\n    instrumentations,\n    tracerProvider,\n    meterProvider,\n    loggerProvider\n  );\n\n  return () => {\n    disableInstrumentations(instrumentations);\n  };\n}\n"]}

package/dist/index.d.ts

@@ -1,3 +1,23 @@
+/** Console methods we can forward, in increasing severity. */
+type ConsoleLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';
+
+/**
+ * Authenticated end-user identity passed to {@link setUser}. `id` is required; the
+ * label/role are optional. Numbers are accepted for `id` and stringified.
+ */
+interface ObservUser {
+    /** Stable application user id → `enduser.id`. */
+    id: string | number;
+    /** Optional role/permission tag → `enduser.role`. */
+    role?: string;
+    /** Optional display name → `enduser.name` (avoid storing raw PII if sensitive). */
+    name?: string;
+}
+/** Attach the authenticated user to all subsequent telemetry. */
+declare function setUser(user: ObservUser): void;
+/** Clear the authenticated identity (call on sign-out). The pseudo id persists. */
+declare function clearUser(): void;
+
 /**
  * PII masking / privacy controls for the heavy rrweb replay flux
  * (Epic 4 — Confidentialité, story 4.1).
@@ -37,6 +57,7 @@ interface PrivacyOptions {
      */
     ignoreClass?: string;
 }
+
 /**
  * Public option bag for {@link observ.init}.
  *
@@ -96,6 +117,72 @@ interface ObservInitOptions {
      * (AlwaysOn). Use under heavy traffic to bound RUM volume.
      */
     sampleRate?: number;
+    /**
+     * Inactivity window (ms) after which the `session.id` rotates. A fresh session
+     * is chained to the prior one via `session.previous_id`. Default: 30 min.
+     */
+    sessionInactivityMs?: number;
+    /**
+     * Hard cap (ms) on a single session's total duration, regardless of activity —
+     * a session older than this rotates even under continuous use. Default: 4 h.
+     */
+    sessionMaxDurationMs?: number;
+    /**
+     * Share one session across the visitor's tabs by backing it with `localStorage`
+     * + the `storage` event, instead of the default per-tab `sessionStorage`
+     * (where two tabs are deliberately two visits). Opt-in: the historical per-tab
+     * model is preserved unless this is `true`. Default: `false`.
+     */
+    crossTabSessions?: boolean;
+    /**
+     * Disable the pseudonymous, persistent `enduser.pseudo.id` (a random id kept in
+     * `localStorage` that ties a visitor's sessions together without authenticated
+     * PII). Default: enabled. The authenticated `enduser.id` (via {@link ObservSdk.setUser})
+     * is unaffected by this flag.
+     */
+    disablePseudoUser?: boolean;
+    /**
+     * Mirror `console.*` calls to the OTLP logs pipeline (each record carries
+     * `session.id` + end-user identity, severity-mapped). The original console is
+     * always still called. `true` forwards `debug`/`log`/`info`/`warn`/`error`; an
+     * array restricts to specific levels (e.g. `['warn', 'error']`). Opt-in
+     * (default off) — console output can be noisy and may contain PII.
+     */
+    forwardConsole?: boolean | ConsoleLevel[];
+    /**
+     * Disable rich `app.page_view` events (initial load + SPA route changes, with
+     * referrer, time-on-previous-page and navigation type). The lightweight
+     * `observ.session.navigate` marker is unaffected. Default: page views ON.
+     */
+    disablePageViews?: boolean;
+    /**
+     * Turn DOM interactions (click / submit / keydown / change / dblclick) into
+     * spans, with a `ZoneContextManager` so trace context survives the async work
+     * an interaction triggers (e.g. a fetch fired from a click becomes its child).
+     *
+     * **Opt-in (default off).** It pulls in `zone.js`, which monkey-patches the
+     * host's global timers / `Promise` on import; the SDK won't impose that unless
+     * asked. The dependency is dynamically imported, so leaving this off keeps both
+     * the bundle and the host globals untouched. Enabling it attaches a microtask
+     * after `init()` (the zone.js chunk loads asynchronously).
+     */
+    userInteraction?: boolean;
+    /**
+     * Gate ALL telemetry behind analytics consent. When `true`, `init()` does
+     * nothing — no session, no persistent id, no providers, no network — until
+     * consent is present (a cookie or `localStorage` value written by the site's
+     * banner, or {@link ObservSdk.grantConsent}). Default: `false` (telemetry driven
+     * solely by operator config, the historical behaviour).
+     */
+    requireConsent?: boolean;
+    /** Cookie / `localStorage` key the consent banner writes. Default `observ.consent`. */
+    consentKey?: string;
+    /**
+     * Stored values that count as "granted" (case-insensitive). Default:
+     * `['granted', 'true', '1', 'yes', 'all']`. The first entry is what
+     * {@link ObservSdk.grantConsent} persists.
+     */
+    consentGrantedValues?: string[];
 }
 /** Public SDK handle returned/exposed by the package entry point. */
 interface ObservSdk {
@@ -111,6 +198,25 @@ interface ObservSdk {
      * flushes on `visibilitychange`/`pagehide` on its own.
      */
     shutdown(): Promise<void>;
+    /**
+     * Attach the authenticated end-user identity to every subsequent span and log
+     * (`enduser.id`, + optional `enduser.role`/`enduser.name`). Call after sign-in.
+     */
+    setUser(user: ObservUser): void;
+    /** Clear the authenticated identity (call on sign-out). The pseudo id persists. */
+    clearUser(): void;
+    /**
+     * Grant analytics consent at runtime (e.g. from a consent-banner callback):
+     * persists the consent value and immediately starts a `requireConsent` init that
+     * was waiting. No-op when nothing is gated. See {@link ObservInitOptions.requireConsent}.
+     */
+    grantConsent(): void;
+    /**
+     * Revoke analytics consent: clears the stored consent and shuts the SDK down so
+     * it stops emitting (already-sent data cannot be recalled). A later `init()` /
+     * {@link ObservSdk.grantConsent} re-arms it.
+     */
+    revokeConsent(): void;
 }
 
 /**
@@ -143,8 +249,24 @@ declare const SESSION_ID_ATTRIBUTE: 'session.id';
  * Idempotent (a second call re-registers nothing) and never throws — any setup
  * failure is swallowed so the SDK can never break the host page; it degrades to
  * "no tracing / no replay / no semantic events".
+ *
+ * When `requireConsent` is set, init becomes a GDPR consent barrier: it does
+ * nothing (no session, no persistent id, no providers, no network) until consent
+ * is present, then auto-starts — watching for a banner that grants consent later
+ * (cross-tab via `storage`, same-tab via a light poll) or {@link grantConsent}.
  */
 declare function init(options: ObservInitOptions): void;
+/**
+ * Grant analytics consent at runtime: persist the consent value and immediately
+ * start a `requireConsent` init that was waiting. No-op when nothing is gated.
+ */
+declare function grantConsent(): void;
+/**
+ * Revoke analytics consent: clear the stored consent (so future inits gate again)
+ * and shut the SDK down. Already-sent data cannot be recalled. A later `init()` /
+ * {@link grantConsent} re-arms it.
+ */
+declare function revokeConsent(): void;
 /**
  * Stop replay capture (flushing the residual chunk), the semantic-event tap, and
  * tear down OTel tracing + logs. Best-effort and never throws (resolves the
@@ -155,4 +277,4 @@ declare function shutdown(): Promise<void>;
 /** Singleton SDK handle. Usage: `observ.init({ endpoint, key })`. */
 declare const observ: ObservSdk;
 
-export { type ObservInitOptions, type ObservSdk, SESSION_ID_ATTRIBUTE, observ as default, init, observ, shutdown };
+export { type ObservInitOptions, type ObservSdk, type ObservUser, SESSION_ID_ATTRIBUTE, clearUser, observ as default, grantConsent, init, observ, revokeConsent, setUser, shutdown };