@amplitude/session-replay-browser 1.47.0-sr-trc-debug-log.1 → 1.47.0-sr-trc-debug-log.3

package/lib/esm/session-replay.js

@@ -52,6 +52,9 @@ var SessionReplay = /** @class */ (function () {
         this.recordEventsPendingShouldLogMetadata = null;
         /** Cleanup for URL change listener used to re-evaluate targeting on SPA route changes */
         this.urlChangeCleanup = null;
+        // Ensures the url_poll.first_tick diagnostic event is emitted at most once per listener setup
+        // (the per-tick counter still increments every tick; only the rich event is one-shot).
+        this.urlPollFirstTickRecorded = false;
         this.crossOriginIframeCoordinator = null;
         this.crossOriginParentSignalCleanup = null;
         /** Monotonic counter to ignore stale URL-change targeting results */
@@ -169,6 +172,17 @@ var SessionReplay = /** @class */ (function () {
                             }
                             pageUrl = (_f = (_c = (_b = targetingParams.page) === null || _b === void 0 ? void 0 : _b.url) !== null && _c !== void 0 ? _c : (_e = (_d = getGlobalScope()) === null || _d === void 0 ? void 0 : _d.location) === null || _e === void 0 ? void 0 : _e.href) !== null && _f !== void 0 ? _f : '';
                             pageForTargeting = (_g = targetingParams.page) !== null && _g !== void 0 ? _g : (pageUrl !== '' ? { url: pageUrl } : undefined);
+                            // Record the targeting trigger event
+                            this.recordDiagnosticEvent(SrDiagnostic.targetingTrigger, {
+                                sessionId: this.identifiers.sessionId,
+                                deviceId: this.getDeviceId(),
+                                targetingConfig: this.config.targetingConfig,
+                                targetingParams: {
+                                    userProperties: targetingParams.userProperties,
+                                    event: eventForTargeting,
+                                    page: pageForTargeting,
+                                },
+                            });
                             evalStart = Date.now();
                             return [4 /*yield*/, evaluateTargetingAndStore({
                                     sessionId: this.identifiers.sessionId,
@@ -326,12 +340,17 @@ var SessionReplay = /** @class */ (function () {
      */
     SessionReplay.prototype.setupUrlChangeListener = function () {
         var _this = this;
-        var _a, _b;
+        var _a, _b, _c, _d, _e, _f;
         // If init() runs multiple times, remove the previous URL-change subscription first
         // so we don't leak callbacks and trigger duplicate targeting evaluations.
         (_a = this.urlChangeCleanup) === null || _a === void 0 ? void 0 : _a.call(this);
         var globalScope = getGlobalScope();
         if (!(globalScope === null || globalScope === void 0 ? void 0 : globalScope.location)) {
+            // No window/location (SSR, worker, or pre-render) — the listener can't attach, so TRC will
+            // never re-evaluate on navigation. Surface it rather than failing silently.
+            this.incrementDiagnostic(SrDiagnostic.urlListenerSkipped);
+            this.recordDiagnosticEvent(SrDiagnostic.urlListenerSkipped, { reason: 'no_global_scope' });
+            this.loggerProvider.debug('URL-change listener not attached: no global scope/location.');
             return;
         }
         var hasTargeting = !!((_b = this.config) === null || _b === void 0 ? void 0 : _b.targetingConfig);
@@ -356,7 +375,39 @@ var SessionReplay = /** @class */ (function () {
                 _this.loggerProvider.debug("Queued URL-change targeting re-evaluation #".concat(evaluationId, " for ").concat(href, "."));
             }
         };
-        var unsubscribe = subscribeToUrlChanges(globalScope, onUrlChange);
+        // Pass the polling options so targeting re-evaluation also respects `enableUrlChangePolling`.
+        // Without this, the targeting listener only sees history.pushState/replaceState + popstate +
+        // hashchange — so SPA navigations that bypass the history API never re-evaluate TRC and
+        // recording never starts on the new URL (enableUrlChangePolling previously only affected the
+        // rrweb URL-tracking plugin, which runs only once recording is already active).
+        var enablePolling = (_d = (_c = this.config) === null || _c === void 0 ? void 0 : _c.enableUrlChangePolling) !== null && _d !== void 0 ? _d : false;
+        this.urlPollFirstTickRecorded = false;
+        var unsubscribe = subscribeToUrlChanges(globalScope, onUrlChange, {
+            enablePolling: enablePolling,
+            pollingInterval: (_e = this.config) === null || _e === void 0 ? void 0 : _e.urlChangePollingInterval,
+            // Mirror each poll tick to the console (Debug level) so we can confirm polling is firing.
+            log: this.loggerProvider.debug.bind(this.loggerProvider),
+            // Prove in DataDog that polling actually FIRES (not just that it was scheduled). Per-tick is a
+            // cheap aggregated counter; the rich event is emitted once (with href) to avoid flooding the
+            // diagnostics endpoint with one capture POST per second.
+            onPoll: function (href, changed) {
+                _this.incrementDiagnostic(SrDiagnostic.urlPollTick);
+                if (!_this.urlPollFirstTickRecorded) {
+                    _this.urlPollFirstTickRecorded = true;
+                    // pollingInterval is already on url_listener.attached, so it's omitted here.
+                    _this.recordDiagnosticEvent(SrDiagnostic.urlPollFirstTick, { href: href, changed: changed });
+                }
+            },
+        });
+        // Confirm the listener is actually live, and under what settings — if recording never starts on
+        // navigation, this tells us whether the listener existed and whether polling (the fallback for
+        // SPAs that bypass the History API) was on.
+        this.recordDiagnosticEvent(SrDiagnostic.urlListenerAttached, {
+            hasTargeting: hasTargeting,
+            enablePolling: enablePolling,
+            pollingInterval: (_f = this.config) === null || _f === void 0 ? void 0 : _f.urlChangePollingInterval,
+        });
+        this.loggerProvider.debug("URL-change listener attached (polling: ".concat(String(enablePolling), ")."));
         this.urlChangeCleanup = function () {
             unsubscribe();
             _this.urlChangeCleanup = null;
@@ -385,14 +436,34 @@ var SessionReplay = /** @class */ (function () {
         var currentUrl = (_b = (_a = getGlobalScope()) === null || _a === void 0 ? void 0 : _a.location) === null || _b === void 0 ? void 0 : _b.href;
         return currentUrl != null ? { url: currentUrl } : undefined;
     };
+    /**
+     * Best-effort navigation type from the Navigation Timing API: 'reload' | 'navigate' |
+     * 'back_forward' | 'prerender'. Surfaced in the init diagnostic so a page refresh ('reload')
+     * is distinguishable from a fresh load ('navigate') — neither changes the session id, so this
+     * is the only way to tell them apart. Returns undefined when the API is unavailable.
+     */
+    SessionReplay.prototype.getNavigationType = function () {
+        try {
+            var globalScope = getGlobalScope();
+            var performance_1 = globalScope && globalScope.performance;
+            if (!performance_1 || typeof performance_1.getEntriesByType !== 'function') {
+                return undefined;
+            }
+            var navEntries = performance_1.getEntriesByType('navigation');
+            return navEntries.length > 0 ? navEntries[0].type : undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    };
     SessionReplay.prototype._init = function (apiKey, options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
         return __awaiter(this, void 0, void 0, function () {
-            var now, _r, _s, joinedConfig, localConfig, remoteConfig, scrollWatcher, managers, storeType, compressionWorkerScript, trackDestinationWorkerScript, globalScope, _t, compressionScript, trackDestinationScript, rrwebEventManager, error_1, typedError, payloadBatcher, interactionEventManager, error_2, typedError, onFullSnapshotProcessed, pending_2, pending_1, pending_1_1, _u, event_1, sessionId, messenger, needsUrlTracking;
-            var e_2, _v;
+            var now, _u, _v, joinedConfig, localConfig, remoteConfig, scrollWatcher, managers, storeType, compressionWorkerScript, trackDestinationWorkerScript, globalScope, _w, compressionScript, trackDestinationScript, rrwebEventManager, error_1, typedError, payloadBatcher, interactionEventManager, error_2, typedError, onFullSnapshotProcessed, pending_2, pending_1, pending_1_1, _x, event_1, sessionId, messenger, needsUrlTracking;
+            var e_2, _y;
             var _this = this;
-            return __generator(this, function (_w) {
-                switch (_w.label) {
+            return __generator(this, function (_z) {
+                switch (_z.label) {
                     case 0:
                         // Re-init should always tear down any previous URL-change subscription, even when the
                         // next config has no targeting config and we don't subscribe again.
@@ -408,13 +479,13 @@ var SessionReplay = /** @class */ (function () {
                             options.sessionId !== undefined
                                 ? (_b = getOrInitReplayStartTime(apiKey, options.sessionId, now, this.loggerProvider)) !== null && _b !== void 0 ? _b : now
                                 : now;
-                        _r = this;
+                        _u = this;
                         return [4 /*yield*/, createSessionReplayJoinedConfigGenerator(apiKey, options)];
                     case 1:
-                        _r.joinedConfigGenerator = _w.sent();
+                        _u.joinedConfigGenerator = _z.sent();
                         return [4 /*yield*/, this.joinedConfigGenerator.generateJoinedConfig()];
                     case 2:
-                        _s = _w.sent(), joinedConfig = _s.joinedConfig, localConfig = _s.localConfig, remoteConfig = _s.remoteConfig;
+                        _v = _z.sent(), joinedConfig = _v.joinedConfig, localConfig = _v.localConfig, remoteConfig = _v.remoteConfig;
                         this.config = joinedConfig;
                         this.setMetadata(options.sessionId, joinedConfig, localConfig, remoteConfig, (_c = options.version) === null || _c === void 0 ? void 0 : _c.version, VERSION, (_d = options.version) === null || _d === void 0 ? void 0 : _d.type);
                         this.pageLeaveFns = [];
@@ -438,12 +509,12 @@ var SessionReplay = /** @class */ (function () {
                         if (!(this.config.useWebWorker && globalScope && globalScope.Worker)) return [3 /*break*/, 4];
                         return [4 /*yield*/, import('./worker')];
                     case 3:
-                        _t = _w.sent(), compressionScript = _t.compressionScript, trackDestinationScript = _t.trackDestinationScript;
+                        _w = _z.sent(), compressionScript = _w.compressionScript, trackDestinationScript = _w.trackDestinationScript;
                         compressionWorkerScript = compressionScript;
                         trackDestinationWorkerScript = trackDestinationScript;
-                        _w.label = 4;
+                        _z.label = 4;
                     case 4:
-                        _w.trys.push([4, 6, , 7]);
+                        _z.trys.push([4, 6, , 7]);
                         return [4 /*yield*/, createEventsManager({
                                 config: this.config,
                                 type: 'replay',
@@ -455,21 +526,21 @@ var SessionReplay = /** @class */ (function () {
                                 shouldSend: function () { return !_this.isBelowMinSessionDuration(); },
                             })];
                     case 5:
-                        rrwebEventManager = _w.sent();
+                        rrwebEventManager = _z.sent();
                         this.rrwebEventManager = rrwebEventManager;
                         managers.push({ name: 'replay', manager: rrwebEventManager });
                         return [3 /*break*/, 7];
                     case 6:
-                        error_1 = _w.sent();
+                        error_1 = _z.sent();
                         typedError = error_1;
                         this.loggerProvider.warn("Error occurred while creating replay events manager: ".concat(typedError.toString()));
                         return [3 /*break*/, 7];
                     case 7:
                         if (!((_j = this.config.interactionConfig) === null || _j === void 0 ? void 0 : _j.enabled)) return [3 /*break*/, 11];
                         payloadBatcher = this.config.interactionConfig.batch ? clickBatcher : clickNonBatcher;
-                        _w.label = 8;
+                        _z.label = 8;
                     case 8:
-                        _w.trys.push([8, 10, , 11]);
+                        _z.trys.push([8, 10, , 11]);
                         return [4 /*yield*/, createEventsManager({
                                 config: this.config,
                                 type: 'interaction',
@@ -481,11 +552,11 @@ var SessionReplay = /** @class */ (function () {
                                 trackDestinationWorkerScript: trackDestinationWorkerScript,
                             })];
                     case 9:
-                        interactionEventManager = _w.sent();
+                        interactionEventManager = _z.sent();
                         managers.push({ name: 'interaction', manager: interactionEventManager });
                         return [3 /*break*/, 11];
                     case 10:
-                        error_2 = _w.sent();
+                        error_2 = _z.sent();
                         typedError = error_2;
                         this.loggerProvider.warn("Error occurred while creating interaction events manager: ".concat(typedError.toString()));
                         return [3 /*break*/, 11];
@@ -503,14 +574,14 @@ var SessionReplay = /** @class */ (function () {
                             pending_2 = this.pendingEmitEvents.splice(0);
                             try {
                                 for (pending_1 = __values(pending_2), pending_1_1 = pending_1.next(); !pending_1_1.done; pending_1_1 = pending_1.next()) {
-                                    _u = pending_1_1.value, event_1 = _u.event, sessionId = _u.sessionId;
+                                    _x = pending_1_1.value, event_1 = _x.event, sessionId = _x.sessionId;
                                     this.eventCompressor.enqueueEvent(event_1, sessionId);
                                 }
                             }
                             catch (e_2_1) { e_2 = { error: e_2_1 }; }
                             finally {
                                 try {
-                                    if (pending_1_1 && !pending_1_1.done && (_v = pending_1.return)) _v.call(pending_1);
+                                    if (pending_1_1 && !pending_1_1.done && (_y = pending_1.return)) _y.call(pending_1);
                                 }
                                 finally { if (e_2) throw e_2.error; }
                             }
@@ -547,7 +618,7 @@ var SessionReplay = /** @class */ (function () {
                         ], false);
                         return [4 /*yield*/, this.initializeNetworkObservers()];
                     case 12:
-                        _w.sent();
+                        _z.sent();
                         // Enable background capture when this page is opened by the Amplitude app
                         // (window.opener exists). Uses the shared messenger singleton so that if
                         // autocapture is also loaded, both share a single messenger and script load.
@@ -569,11 +640,27 @@ var SessionReplay = /** @class */ (function () {
                             sampleRate: this.config.sampleRate,
                             optOut: this.shouldOptOut(),
                             currentUrl: (_m = this.getCurrentPageForTargeting()) === null || _m === void 0 ? void 0 : _m.url,
+                            // 'reload' tells a page refresh apart from a fresh load ('navigate') or back/forward
+                            // ('back_forward'). New tabs and refreshes keep the same session id, so this is the only
+                            // way to distinguish a refresh from a brand-new init within a session.
+                            navigationType: this.getNavigationType(),
                         });
                         return [4 /*yield*/, this.evaluateTargetingAndCapture({ userProperties: options.userProperties, page: this.getCurrentPageForTargeting() }, true)];
                     case 13:
-                        _w.sent();
+                        _z.sent();
                         needsUrlTracking = this.config.targetingConfig || ((_q = (_p = (_o = this.config.privacyConfig) === null || _o === void 0 ? void 0 : _o.urlMaskLevels) === null || _p === void 0 ? void 0 : _p.length) !== null && _q !== void 0 ? _q : 0) > 0;
+                        // Record whether we even attempt to wire up the URL-change listener, and the inputs behind that
+                        // decision. If `needsUrlTracking` is false the listener is never attached, so SPA navigations are
+                        // invisible to TRC — this is the first thing to check when "TRC is on but never re-evaluates".
+                        this.recordDiagnosticEvent(SrDiagnostic.urlListenerSetup, {
+                            needsUrlTracking: !!needsUrlTracking,
+                            hasTargetingConfig: !!this.config.targetingConfig,
+                            urlMaskLevels: (_t = (_s = (_r = this.config.privacyConfig) === null || _r === void 0 ? void 0 : _r.urlMaskLevels) === null || _s === void 0 ? void 0 : _s.length) !== null && _t !== void 0 ? _t : 0,
+                            // config always defaults this to a boolean (see local-config), so no `?? false` needed here.
+                            enableUrlChangePolling: this.config.enableUrlChangePolling,
+                            urlChangePollingInterval: this.config.urlChangePollingInterval,
+                        });
+                        this.loggerProvider.debug("URL-change listener needed: ".concat(String(!!needsUrlTracking), "."));
                         if (needsUrlTracking) {
                             this.setupUrlChangeListener();
                         }
@@ -613,6 +700,18 @@ var SessionReplay = /** @class */ (function () {
                             this.sendEvents(previousSessionId);
                         }
                         isSessionChange = previousSessionId !== sessionId;
+                        // A real session transition (not the first set): recording stops/restarts and targeting is
+                        // re-evaluated here, so session churn (timeout, multi-tab custom ids, explicit setSessionId)
+                        // is a prime suspect for "sometimes records, sometimes not". recordDiagnosticEvent ships to
+                        // DataDog AND mirrors to loggerProvider.debug. New tabs / refreshes keep the same id and won't
+                        // hit this — use the init diagnostic's navigationType for those.
+                        if (isSessionChange && previousSessionId !== undefined) {
+                            this.recordDiagnosticEvent(SrDiagnostic.sessionChanged, {
+                                from: previousSessionId,
+                                to: sessionId,
+                                deviceIdChanged: deviceId !== undefined && deviceId !== currentDeviceId,
+                            });
+                        }
                         // Drop any beacon-buffered events from the previous session BEFORE installing the
                         // new identifiers / start time. Otherwise the page-leave beacon path could attribute
                         // old-session events to the new session id, and the gate (using the new start time)
@@ -777,6 +876,9 @@ var SessionReplay = /** @class */ (function () {
     SessionReplay.prototype.incrementDiagnostic = function (counter) {
         var _a, _b;
         try {
+            // Mirror to the console (Debug level) so the full set of diagnostics is visible in the
+            // browser, not only in DataDog — helps debugging when a customer can't share a repro env.
+            this.loggerProvider.debug("[SR diagnostics] ".concat(counter));
             (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.diagnosticsClient) === null || _b === void 0 ? void 0 : _b.increment(counter);
         }
         catch (_c) {
@@ -790,6 +892,8 @@ var SessionReplay = /** @class */ (function () {
     SessionReplay.prototype.recordDiagnosticHistogram = function (name, value) {
         var _a, _b;
         try {
+            // Mirror to the console (Debug level) — see incrementDiagnostic.
+            this.loggerProvider.debug("[SR diagnostics] ".concat(name, "=").concat(value));
             // The only caller runs inside evaluateTargetingAndCapture's `this.config` guard, so the
             // `config == null` arm of this optional chain is unreachable here (kept as defensive parity
             // with recordDiagnosticEvent). The diagnosticsClient-absent arm IS exercised by no-client tests.
@@ -814,7 +918,11 @@ var SessionReplay = /** @class */ (function () {
             // Always stamp sessionId, deviceId and srId so every diagnostics event (→ DataDog Logs) can
             // be correlated to a single session/device — and to the actual replay, since the Session
             // Replay ID is `${deviceId}/${sessionId}`. Caller props override if they pass their own.
-            (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.diagnosticsClient) === null || _c === void 0 ? void 0 : _c.recordEvent(name, __assign({ sessionId: sessionId, deviceId: deviceId, srId: deviceId != null && sessionId != null ? "".concat(deviceId, "/").concat(sessionId) : undefined }, properties));
+            var enriched = __assign({ sessionId: sessionId, deviceId: deviceId, srId: deviceId != null && sessionId != null ? "".concat(deviceId, "/").concat(sessionId) : undefined }, properties);
+            // Mirror to the console (Debug level) so the full event + props are visible in the browser,
+            // not only in DataDog — see incrementDiagnostic.
+            this.loggerProvider.debug("[SR diagnostics] ".concat(name, " ").concat(JSON.stringify(enriched)));
+            (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.diagnosticsClient) === null || _c === void 0 ? void 0 : _c.recordEvent(name, enriched);
             // Flush immediately so the event ships now rather than on the client's ~5-min timer (and so
             // short sessions that never reach the timer aren't lost). NOTE: this sends one capture POST
             // per event — higher request volume; revisit/gate before production.