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

package/lib/esm/session-replay.js

@@ -14,6 +14,7 @@ import { SessionIdentifiers } from './identifiers';
 import { SafeLoggerProvider } from './logger';
 import { getOrInitReplayStartTime, pruneStaleReplayStartTimes, removeReplayStartTime, setReplayStartTime, } from './replay-start-time-store';
 import { evaluateTargetingAndStore } from './targeting/targeting-manager';
+import { SrDiagnostic } from './diagnostics';
 import { isSessionInSample } from './sampling';
 import { VERSION } from './version';
 import { createUrlTrackingPlugin, subscribeToUrlChanges } from './plugins/url-tracking-plugin';
@@ -25,6 +26,10 @@ var SessionReplay = /** @class */ (function () {
         this.recordCancelCallback = null;
         this.eventCount = 0;
         this.sessionTargetingMatch = false;
+        // Session for which the one-per-session TRC diagnostic event was already emitted. The
+        // diagnostics client caps in-memory events, so per-call signals go through counters and only
+        // a single rich snapshot event is recorded per session.
+        this.trcDiagnosticSessionId = undefined;
         // Public on purpose. `pageLeaveFns` is iterated by `pageLeaveListener`,
         // `rrwebEventManager` is dereferenced in `asyncSetSessionId` to drop the beacon buffer
         // at a session boundary, and `sessionStartTime` drives `isBelowMinSessionDuration()`.
@@ -115,12 +120,23 @@ var SessionReplay = /** @class */ (function () {
             if (forceRestart === void 0) { forceRestart = false; }
             if (forceTargetingReevaluation === void 0) { forceTargetingReevaluation = false; }
             return __awaiter(_this, void 0, void 0, function () {
-                var targetingConfig, shouldReEvaluate, urlChangeEvaluationId, eventForTargeting, pageUrl, pageForTargeting, targetingMatch;
-                var _a, _b, _c, _d, _e, _f;
-                return __generator(this, function (_g) {
-                    switch (_g.label) {
+                var targetingConfig, shouldReEvaluate, urlChangeEvaluationId, eventForTargeting, pageUrl, pageForTargeting, evalStart, targetingMatch, evalDurationMs, trigger;
+                var _a, _b, _c, _d, _e, _f, _g;
+                return __generator(this, function (_h) {
+                    switch (_h.label) {
                         case 0:
+                            // What triggered this evaluation (init vs SPA URL change vs analytics event) — shows in
+                            // DataDog how often re-evaluation actually runs.
+                            this.incrementDiagnostic(SrDiagnostic.evalTrigger(isInit ? 'init' : forceTargetingReevaluation ? 'urlchange' : 'event'));
                             if (!this.identifiers || !this.identifiers.sessionId || !this.config) {
+                                // Q4: eval can't run because a prerequisite is missing — record exactly which one.
+                                this.incrementDiagnostic(SrDiagnostic.evalMissingPrereq);
+                                this.recordDiagnosticEvent(SrDiagnostic.evalMissingPrereq, {
+                                    hasIdentifiers: !!this.identifiers,
+                                    hasSessionId: !!((_a = this.identifiers) === null || _a === void 0 ? void 0 : _a.sessionId),
+                                    hasConfig: !!this.config,
+                                    hasDeviceId: !!this.getDeviceId(),
+                                });
                                 if (this.identifiers && !this.identifiers.sessionId) {
                                     this.loggerProvider.log('Session ID has not been set yet, cannot evaluate targeting for Session Replay.');
                                 }
@@ -131,6 +147,7 @@ var SessionReplay = /** @class */ (function () {
                             }
                             // Handle cases where there's no targeting config
                             if (!this.config.targetingConfig) {
+                                this.incrementDiagnostic(SrDiagnostic.evalNoConfig);
                                 if (isInit) {
                                     this.loggerProvider.log('Targeting config has not been set yet, cannot evaluate targeting.');
                                 }
@@ -150,8 +167,9 @@ var SessionReplay = /** @class */ (function () {
                                 Object.values(SpecialEventType).includes(eventForTargeting.event_type)) {
                                 eventForTargeting = undefined;
                             }
-                            pageUrl = (_e = (_b = (_a = targetingParams.page) === null || _a === void 0 ? void 0 : _a.url) !== null && _b !== void 0 ? _b : (_d = (_c = getGlobalScope()) === null || _c === void 0 ? void 0 : _c.location) === null || _d === void 0 ? void 0 : _d.href) !== null && _e !== void 0 ? _e : '';
-                            pageForTargeting = (_f = targetingParams.page) !== null && _f !== void 0 ? _f : (pageUrl !== '' ? { url: pageUrl } : undefined);
+                            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);
+                            evalStart = Date.now();
                             return [4 /*yield*/, evaluateTargetingAndStore({
                                     sessionId: this.identifiers.sessionId,
                                     targetingConfig: targetingConfig,
@@ -163,38 +181,76 @@ var SessionReplay = /** @class */ (function () {
                                         page: pageForTargeting,
                                     },
                                     urlChange: forceTargetingReevaluation,
+                                    diagnosticsClient: this.config.diagnosticsClient,
+                                    deviceId: this.getDeviceId(),
                                 })];
                         case 1:
-                            targetingMatch = _g.sent();
+                            targetingMatch = _h.sent();
+                            evalDurationMs = Date.now() - evalStart;
+                            trigger = isInit ? 'init' : forceTargetingReevaluation ? 'urlchange' : 'event';
+                            // Evaluation latency — surfaces the slow-network residual gap (SR-4234) in DataDog as
+                            // sdk.diagnostics.sr.trc.eval.duration_ms.{avg,max,...}.
+                            this.recordDiagnosticHistogram(SrDiagnostic.evalDurationMs, evalDurationMs);
                             if (forceTargetingReevaluation &&
                                 urlChangeEvaluationId !== undefined &&
                                 urlChangeEvaluationId !== this.latestUrlChangeTargetingEvaluationId) {
+                                this.incrementDiagnostic(SrDiagnostic.evalStaleDiscarded);
+                                this.recordDiagnosticEvent(SrDiagnostic.evalStaleDiscarded, {
+                                    sessionId: this.identifiers.sessionId,
+                                    pageUrl: pageForTargeting === null || pageForTargeting === void 0 ? void 0 : pageForTargeting.url,
+                                    evaluationId: urlChangeEvaluationId,
+                                    latestEvaluationId: this.latestUrlChangeTargetingEvaluationId,
+                                    evalDurationMs: evalDurationMs,
+                                });
                                 this.loggerProvider.debug("Ignoring stale URL-change targeting result #".concat(urlChangeEvaluationId, "; latest is #").concat(this.latestUrlChangeTargetingEvaluationId, "."));
                                 return [2 /*return*/];
                             }
+                            // Per-evaluation outcome (distinct from the per-session sr.gate.* gate counters).
+                            this.incrementDiagnostic(targetingMatch ? SrDiagnostic.evalMatch : SrDiagnostic.evalNoMatch);
                             // Keep targeting match monotonic within a session: once true, always true.
                             // This avoids races where an older in-flight evaluation resolves false after
                             // a newer evaluation already resolved true.
                             this.sessionTargetingMatch = this.sessionTargetingMatch || targetingMatch;
+                            // Q5: record ALL evaluation params (→ DataDog Logs) so a single evaluation can be fully
+                            // reconstructed by URL, identifiers, inputs, outcome, trigger and latency. userProperties
+                            // values are intentionally reduced to keys to avoid logging PII.
+                            this.recordDiagnosticEvent(SrDiagnostic.evalEvent, {
+                                // sessionId + deviceId are stamped by recordDiagnosticEvent.
+                                trigger: trigger,
+                                matched: targetingMatch,
+                                sessionTargetingMatch: this.sessionTargetingMatch,
+                                pageUrl: pageForTargeting === null || pageForTargeting === void 0 ? void 0 : pageForTargeting.url,
+                                hasDeviceId: !!this.getDeviceId(),
+                                hasEvent: !!eventForTargeting,
+                                eventType: eventForTargeting === null || eventForTargeting === void 0 ? void 0 : eventForTargeting.event_type,
+                                userPropertyKeys: targetingParams.userProperties ? Object.keys(targetingParams.userProperties) : [],
+                                evalDurationMs: evalDurationMs,
+                            });
                             this.loggerProvider.debug(JSON.stringify({
                                 name: 'targeted replay capture config',
                                 sessionTargetingMatch: this.sessionTargetingMatch,
                                 event: eventForTargeting,
                                 targetingParams: targetingParams,
                             }, null, 2));
-                            _g.label = 2;
+                            return [3 /*break*/, 3];
                         case 2:
-                            if (!isInit) return [3 /*break*/, 3];
-                            void this.initialize(true);
-                            return [3 /*break*/, 5];
+                            if (targetingConfig && this.sessionTargetingMatch) {
+                                // Already matched earlier this session — recording continues without re-evaluation.
+                                this.incrementDiagnostic(SrDiagnostic.evalSkippedAlreadyMatched);
+                            }
+                            _h.label = 3;
                         case 3:
-                            if (!(forceRestart || !this.recordCancelCallback)) return [3 /*break*/, 5];
+                            if (!isInit) return [3 /*break*/, 4];
+                            void this.initialize(true);
+                            return [3 /*break*/, 6];
+                        case 4:
+                            if (!(forceRestart || !this.recordCancelCallback)) return [3 /*break*/, 6];
                             this.loggerProvider.log('Recording events for session due to forceRestart or no ongoing recording.');
                             return [4 /*yield*/, this.recordEvents()];
-                        case 4:
-                            _g.sent();
-                            _g.label = 5;
-                        case 5: return [2 /*return*/];
+                        case 5:
+                            _h.sent();
+                            _h.label = 6;
+                        case 6: return [2 /*return*/];
                     }
                 });
             });
@@ -281,6 +337,15 @@ var SessionReplay = /** @class */ (function () {
         var hasTargeting = !!((_b = this.config) === null || _b === void 0 ? void 0 : _b.targetingConfig);
         var onUrlChange = function (href) {
             _this.currentPageUrl = href;
+            // Team-visible signal that an SPA navigation was detected at all (covers the "is the SDK
+            // even seeing route changes in this framework?" question — counter + a log with the href
+            // and whether it triggered a targeting re-eval).
+            _this.incrementDiagnostic(SrDiagnostic.urlChange);
+            _this.recordDiagnosticEvent(SrDiagnostic.urlChangeEvent, {
+                href: href,
+                hasTargeting: hasTargeting,
+                alreadyMatched: _this.sessionTargetingMatch,
+            });
             if (hasTargeting) {
                 var evaluationId = ++_this.latestUrlChangeTargetingEvaluationId;
                 void _this.evaluateTargetingAndCapture({
@@ -321,13 +386,13 @@ var SessionReplay = /** @class */ (function () {
         return currentUrl != null ? { url: currentUrl } : undefined;
     };
     SessionReplay.prototype._init = function (apiKey, options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
         return __awaiter(this, void 0, void 0, function () {
-            var now, _q, _r, joinedConfig, localConfig, remoteConfig, scrollWatcher, managers, storeType, compressionWorkerScript, trackDestinationWorkerScript, globalScope, _s, compressionScript, trackDestinationScript, rrwebEventManager, error_1, typedError, payloadBatcher, interactionEventManager, error_2, typedError, onFullSnapshotProcessed, pending_2, pending_1, pending_1_1, _t, event_1, sessionId, messenger, needsUrlTracking;
-            var e_2, _u;
+            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 _this = this;
-            return __generator(this, function (_v) {
-                switch (_v.label) {
+            return __generator(this, function (_w) {
+                switch (_w.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.
@@ -343,13 +408,13 @@ var SessionReplay = /** @class */ (function () {
                             options.sessionId !== undefined
                                 ? (_b = getOrInitReplayStartTime(apiKey, options.sessionId, now, this.loggerProvider)) !== null && _b !== void 0 ? _b : now
                                 : now;
-                        _q = this;
+                        _r = this;
                         return [4 /*yield*/, createSessionReplayJoinedConfigGenerator(apiKey, options)];
                     case 1:
-                        _q.joinedConfigGenerator = _v.sent();
+                        _r.joinedConfigGenerator = _w.sent();
                         return [4 /*yield*/, this.joinedConfigGenerator.generateJoinedConfig()];
                     case 2:
-                        _r = _v.sent(), joinedConfig = _r.joinedConfig, localConfig = _r.localConfig, remoteConfig = _r.remoteConfig;
+                        _s = _w.sent(), joinedConfig = _s.joinedConfig, localConfig = _s.localConfig, remoteConfig = _s.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 = [];
@@ -373,12 +438,12 @@ var SessionReplay = /** @class */ (function () {
                         if (!(this.config.useWebWorker && globalScope && globalScope.Worker)) return [3 /*break*/, 4];
                         return [4 /*yield*/, import('./worker')];
                     case 3:
-                        _s = _v.sent(), compressionScript = _s.compressionScript, trackDestinationScript = _s.trackDestinationScript;
+                        _t = _w.sent(), compressionScript = _t.compressionScript, trackDestinationScript = _t.trackDestinationScript;
                         compressionWorkerScript = compressionScript;
                         trackDestinationWorkerScript = trackDestinationScript;
-                        _v.label = 4;
+                        _w.label = 4;
                     case 4:
-                        _v.trys.push([4, 6, , 7]);
+                        _w.trys.push([4, 6, , 7]);
                         return [4 /*yield*/, createEventsManager({
                                 config: this.config,
                                 type: 'replay',
@@ -390,21 +455,21 @@ var SessionReplay = /** @class */ (function () {
                                 shouldSend: function () { return !_this.isBelowMinSessionDuration(); },
                             })];
                     case 5:
-                        rrwebEventManager = _v.sent();
+                        rrwebEventManager = _w.sent();
                         this.rrwebEventManager = rrwebEventManager;
                         managers.push({ name: 'replay', manager: rrwebEventManager });
                         return [3 /*break*/, 7];
                     case 6:
-                        error_1 = _v.sent();
+                        error_1 = _w.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;
-                        _v.label = 8;
+                        _w.label = 8;
                     case 8:
-                        _v.trys.push([8, 10, , 11]);
+                        _w.trys.push([8, 10, , 11]);
                         return [4 /*yield*/, createEventsManager({
                                 config: this.config,
                                 type: 'interaction',
@@ -416,11 +481,11 @@ var SessionReplay = /** @class */ (function () {
                                 trackDestinationWorkerScript: trackDestinationWorkerScript,
                             })];
                     case 9:
-                        interactionEventManager = _v.sent();
+                        interactionEventManager = _w.sent();
                         managers.push({ name: 'interaction', manager: interactionEventManager });
                         return [3 /*break*/, 11];
                     case 10:
-                        error_2 = _v.sent();
+                        error_2 = _w.sent();
                         typedError = error_2;
                         this.loggerProvider.warn("Error occurred while creating interaction events manager: ".concat(typedError.toString()));
                         return [3 /*break*/, 11];
@@ -438,14 +503,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()) {
-                                    _t = pending_1_1.value, event_1 = _t.event, sessionId = _t.sessionId;
+                                    _u = pending_1_1.value, event_1 = _u.event, sessionId = _u.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 && (_u = pending_1.return)) _u.call(pending_1);
+                                    if (pending_1_1 && !pending_1_1.done && (_v = pending_1.return)) _v.call(pending_1);
                                 }
                                 finally { if (e_2) throw e_2.error; }
                             }
@@ -482,7 +547,7 @@ var SessionReplay = /** @class */ (function () {
                         ], false);
                         return [4 /*yield*/, this.initializeNetworkObservers()];
                     case 12:
-                        _v.sent();
+                        _w.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.
@@ -493,10 +558,22 @@ var SessionReplay = /** @class */ (function () {
                         }
                         this.loggerProvider.log('Installing @amplitude/session-replay-browser.');
                         this.teardownEventListeners(false);
+                        // Q1 "did init happen?": its presence in DataDog proves init() ran to completion for this
+                        // session; the props show whether the prerequisites (session/device id, config) were present.
+                        this.incrementDiagnostic(SrDiagnostic.init);
+                        this.recordDiagnosticEvent(SrDiagnostic.init, {
+                            // sessionId is always stamped by recordDiagnosticEvent, so no separate hasSessionId here.
+                            hasDeviceId: !!this.getDeviceId(),
+                            captureEnabled: this.config.captureEnabled,
+                            hasTargetingConfig: !!this.config.targetingConfig,
+                            sampleRate: this.config.sampleRate,
+                            optOut: this.shouldOptOut(),
+                            currentUrl: (_m = this.getCurrentPageForTargeting()) === null || _m === void 0 ? void 0 : _m.url,
+                        });
                         return [4 /*yield*/, this.evaluateTargetingAndCapture({ userProperties: options.userProperties, page: this.getCurrentPageForTargeting() }, true)];
                     case 13:
-                        _v.sent();
-                        needsUrlTracking = this.config.targetingConfig || ((_p = (_o = (_m = this.config.privacyConfig) === null || _m === void 0 ? void 0 : _m.urlMaskLevels) === null || _o === void 0 ? void 0 : _o.length) !== null && _p !== void 0 ? _p : 0) > 0;
+                        _w.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;
                         if (needsUrlTracking) {
                             this.setupUrlChangeListener();
                         }
@@ -509,17 +586,29 @@ var SessionReplay = /** @class */ (function () {
         return returnWrapper(this.asyncSetSessionId(sessionId, deviceId));
     };
     SessionReplay.prototype.asyncSetSessionId = function (sessionId, deviceId, options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         return __awaiter(this, void 0, void 0, function () {
-            var previousSessionId, isSessionChange, deviceIdForReplayId, joinedConfig;
-            return __generator(this, function (_d) {
-                switch (_d.label) {
+            var previousSessionId, currentDeviceId, isSessionChange, deviceIdForReplayId, joinedConfig;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
                     case 0:
+                        previousSessionId = (_a = this.identifiers) === null || _a === void 0 ? void 0 : _a.sessionId;
+                        currentDeviceId = this.getDeviceId();
+                        // Standalone SDK callers may poll setSessionId with a stable bucket id (e.g. hour-aligned
+                        // timestamps) and only need a no-op when the bucket hasn't rolled. Without this guard,
+                        // the rest of asyncSetSessionId still runs: sendEvents, targeting reset, config refetch,
+                        // and recordEvents (stop + restart rrweb). Proceed when deviceId changes or
+                        // non-empty userProperties are passed so targeting can re-evaluate on Identify.
+                        if (previousSessionId !== undefined &&
+                            previousSessionId === sessionId &&
+                            (deviceId === undefined || deviceId === currentDeviceId) &&
+                            ((options === null || options === void 0 ? void 0 : options.userProperties) === undefined || Object.keys(options.userProperties).length === 0)) {
+                            return [2 /*return*/];
+                        }
                         // Invalidate any in-flight URL-change re-evaluations from the previous session.
                         this.latestUrlChangeTargetingEvaluationId++;
                         this.sessionTargetingMatch = false;
                         this.lastShouldRecordDecision = undefined; // Reset targeting decision for new session
-                        previousSessionId = this.identifiers && this.identifiers.sessionId;
                         if (previousSessionId) {
                             this.sendEvents(previousSessionId);
                         }
@@ -530,7 +619,7 @@ var SessionReplay = /** @class */ (function () {
                         // would compute the wrong elapsed duration. Skip on a redundant same-sessionId call —
                         // the buffer belongs to the *continuing* session and should ship via beacon as normal.
                         if (isSessionChange) {
-                            (_a = this.rrwebEventManager) === null || _a === void 0 ? void 0 : _a.dropPendingBeaconEvents();
+                            (_b = this.rrwebEventManager) === null || _b === void 0 ? void 0 : _b.dropPendingBeaconEvents();
                         }
                         deviceIdForReplayId = deviceId || this.getDeviceId();
                         this.identifiers = new SessionIdentifiers({
@@ -545,7 +634,7 @@ var SessionReplay = /** @class */ (function () {
                             this.sessionStartTime = Date.now();
                             this.suppressedSendCount = 0;
                             this.hasEmittedGateDecision = false;
-                            if ((_b = this.config) === null || _b === void 0 ? void 0 : _b.apiKey) {
+                            if ((_c = this.config) === null || _c === void 0 ? void 0 : _c.apiKey) {
                                 setReplayStartTime(this.config.apiKey, sessionId, this.sessionStartTime, this.loggerProvider);
                                 if (previousSessionId !== undefined) {
                                     removeReplayStartTime(this.config.apiKey, previousSessionId, this.loggerProvider);
@@ -555,19 +644,19 @@ var SessionReplay = /** @class */ (function () {
                         if (!(this.joinedConfigGenerator && previousSessionId)) return [3 /*break*/, 2];
                         return [4 /*yield*/, this.joinedConfigGenerator.generateJoinedConfig()];
                     case 1:
-                        joinedConfig = (_d.sent()).joinedConfig;
+                        joinedConfig = (_e.sent()).joinedConfig;
                         this.config = joinedConfig;
-                        _d.label = 2;
+                        _e.label = 2;
                     case 2:
-                        if (!((_c = this.config) === null || _c === void 0 ? void 0 : _c.targetingConfig)) return [3 /*break*/, 4];
+                        if (!((_d = this.config) === null || _d === void 0 ? void 0 : _d.targetingConfig)) return [3 /*break*/, 4];
                         return [4 /*yield*/, this.evaluateTargetingAndCapture({ userProperties: options === null || options === void 0 ? void 0 : options.userProperties, page: this.getCurrentPageForTargeting() }, false, true)];
                     case 3:
-                        _d.sent();
+                        _e.sent();
                         return [3 /*break*/, 6];
                     case 4: return [4 /*yield*/, this.recordEvents()];
                     case 5:
-                        _d.sent();
-                        _d.label = 6;
+                        _e.sent();
+                        _e.label = 6;
                     case 6: return [2 /*return*/];
                 }
             });
@@ -620,6 +709,9 @@ var SessionReplay = /** @class */ (function () {
                 // Cross-session leak is prevented in asyncSetSessionId, which drops the buffer
                 // at the session transition. The page-leave path also gates independently.
                 this.suppressedSendCount++;
+                // gap #1: recording but events held back by min_session_duration — another "recording yet
+                // no replay in Amplitude" cause.
+                this.incrementDiagnostic(SrDiagnostic.sendSuppressedMinDuration);
                 return;
             }
             // On the first send-after-pass for the session, emit a custom rrweb event so the
@@ -676,17 +768,111 @@ var SessionReplay = /** @class */ (function () {
         }
         return identityStoreOptOut !== undefined ? identityStoreOptOut : (_b = this.config) === null || _b === void 0 ? void 0 : _b.optOut;
     };
+    /**
+     * Increment a diagnostics counter so the team can see the distribution of recording decisions
+     * across a customer's sessions (e.g. lots of sr.gate.trc_no_match => rule isn't matching).
+     * Ships via the analytics SDK's DiagnosticsClient. No-op when there's no client or diagnostics
+     * isn't sampled in; never throws — diagnostics must never interfere with recording.
+     */
+    SessionReplay.prototype.incrementDiagnostic = function (counter) {
+        var _a, _b;
+        try {
+            (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.diagnosticsClient) === null || _b === void 0 ? void 0 : _b.increment(counter);
+        }
+        catch (_c) {
+            // swallow — diagnostics is best-effort
+        }
+    };
+    /**
+     * Record a diagnostics histogram value (min/max/avg/count in DataDog). Same best-effort, never-
+     * throws contract as incrementDiagnostic. Use for latencies/sizes, not per-call counts.
+     */
+    SessionReplay.prototype.recordDiagnosticHistogram = function (name, value) {
+        var _a, _b;
+        try {
+            // 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.
+            /* istanbul ignore next */
+            (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.diagnosticsClient) === null || _b === void 0 ? void 0 : _b.recordHistogram(name, value);
+        }
+        catch (_c) {
+            // swallow — diagnostics is best-effort
+        }
+    };
+    /**
+     * Record a diagnostics EVENT with properties. Events are forwarded to DataDog Logs, so the
+     * properties become queryable fields (e.g. @matched, @pageUrl). Use sparingly vs counters: the
+     * client caps in-memory events (~10 per save interval), so this is for context-rich signals at
+     * meaningful decision points, not per-call tallies. Best-effort, never throws.
+     */
+    SessionReplay.prototype.recordDiagnosticEvent = function (name, properties) {
+        var _a, _b, _c, _d, _e, _f;
+        try {
+            var sessionId = (_a = this.identifiers) === null || _a === void 0 ? void 0 : _a.sessionId;
+            var deviceId = this.getDeviceId();
+            // 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));
+            // 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.
+            void ((_f = (_e = (_d = this.config) === null || _d === void 0 ? void 0 : _d.diagnosticsClient) === null || _e === void 0 ? void 0 : _e._flush) === null || _f === void 0 ? void 0 : _f.call(_e));
+        }
+        catch (_g) {
+            // swallow — diagnostics is best-effort
+        }
+    };
+    /**
+     * Emit a single rich TRC decision snapshot per session to diagnostics — surfaced even when
+     * nothing records (the exact case customers can't reproduce locally).
+     */
+    SessionReplay.prototype.recordTrcDecisionDiagnostic = function (shouldRecord) {
+        var _a, _b;
+        var config = this.config;
+        // Every caller is past getShouldRecord's `!this.identifiers`/`!this.config` guard, so both are
+        // defined here; the `?.` arms below are unreachable defensive narrowing and excluded from
+        // coverage. The reachable guards (no diagnosticsClient, undefined/duplicate sessionId) are tested.
+        /* istanbul ignore next */
+        if (!config) {
+            return;
+        }
+        /* istanbul ignore next */
+        var sessionId = (_a = this.identifiers) === null || _a === void 0 ? void 0 : _a.sessionId;
+        // Once past this guard, config.diagnosticsClient is truthy, so the fields below read config
+        // directly rather than re-asserting with `?.` on every access.
+        if (!config.diagnosticsClient || sessionId === undefined || sessionId === this.trcDiagnosticSessionId) {
+            return;
+        }
+        this.trcDiagnosticSessionId = sessionId;
+        // Goes through recordDiagnosticEvent so it carries sessionId + deviceId like every other event.
+        this.recordDiagnosticEvent(SrDiagnostic.decision, {
+            shouldRecord: shouldRecord,
+            captureEnabled: config.captureEnabled,
+            hasTargetingConfig: !!config.targetingConfig,
+            sessionTargetingMatch: this.sessionTargetingMatch,
+            sampleRate: config.sampleRate,
+            pageUrl: (_b = this.getCurrentPageForTargeting()) === null || _b === void 0 ? void 0 : _b.url,
+            sdkVersion: VERSION,
+        });
+    };
     SessionReplay.prototype.getShouldRecord = function () {
         if (!this.identifiers || !this.config || !this.identifiers.sessionId) {
             this.loggerProvider.warn("Session is not being recorded due to lack of config, please call sessionReplay.init.");
+            this.incrementDiagnostic(SrDiagnostic.gateNoIdentifiers);
             return false;
         }
         if (!this.config.captureEnabled) {
             this.loggerProvider.log("Session ".concat(this.identifiers.sessionId, " not being captured due to capture being disabled for project or because the remote config could not be fetched."));
+            this.incrementDiagnostic(SrDiagnostic.gateCaptureDisabled);
+            this.recordTrcDecisionDiagnostic(false);
             return false;
         }
         if (this.shouldOptOut()) {
             this.loggerProvider.log("Opting session ".concat(this.identifiers.sessionId, " out of recording due to optOut config."));
+            this.incrementDiagnostic(SrDiagnostic.gateOptOut);
+            this.recordTrcDecisionDiagnostic(false);
             return false;
         }
         var shouldRecord = false;
@@ -700,12 +886,14 @@ var SessionReplay = /** @class */ (function () {
                 this.loggerProvider.log(message);
                 shouldRecord = false;
                 matched = false;
+                this.incrementDiagnostic(SrDiagnostic.gateTrcNoMatch);
             }
             else {
                 message = "Capturing replays for session ".concat(this.identifiers.sessionId, " due to matching targeting conditions.");
                 this.loggerProvider.log(message);
                 shouldRecord = true;
                 matched = true;
+                this.incrementDiagnostic(SrDiagnostic.gateTrcMatch);
             }
         }
         else {
@@ -715,10 +903,12 @@ var SessionReplay = /** @class */ (function () {
                 this.loggerProvider.log(message);
                 shouldRecord = false;
                 matched = false;
+                this.incrementDiagnostic(SrDiagnostic.gateSampleOut);
             }
             else {
                 shouldRecord = true;
                 matched = true;
+                this.incrementDiagnostic(SrDiagnostic.gateSampleIn);
             }
         }
         // Only send custom rrweb event for targeting decision when the decision changes
@@ -731,6 +921,7 @@ var SessionReplay = /** @class */ (function () {
             });
             this.lastShouldRecordDecision = shouldRecord;
         }
+        this.recordTrcDecisionDiagnostic(shouldRecord);
         return shouldRecord;
     };
     SessionReplay.prototype.getBlockSelectors = function () {
@@ -895,6 +1086,9 @@ var SessionReplay = /** @class */ (function () {
                         recordFunction = _o.sent();
                         // May be undefined if cannot import rrweb-record
                         if (!recordFunction) {
+                            // gap #1: gate said record, but rrweb couldn't load → no replay despite shouldRecord=true.
+                            this.incrementDiagnostic(SrDiagnostic.recordNoRecordFn);
+                            this.recordDiagnosticEvent(SrDiagnostic.recordNoRecordFn, {});
                             return [2 /*return*/];
                         }
                         return [4 /*yield*/, this.initializeNetworkObservers()];
@@ -925,6 +1119,11 @@ var SessionReplay = /** @class */ (function () {
                             : {};
                         ugcFilterRules = (interactionConfig === null || interactionConfig === void 0 ? void 0 : interactionConfig.enabled) && interactionConfig.ugcFilterRules ? interactionConfig.ugcFilterRules : [];
                         this.loggerProvider.log("Session Replay capture beginning for ".concat(sessionId, "."));
+                        // gap #1: rrweb is actually starting. Closes the "gate said yes but no replay" blind spot,
+                        // and its srId is the id the replay uploads under (compare with analytics events to catch the
+                        // device-id mismatch that breaks stitching).
+                        this.incrementDiagnostic(SrDiagnostic.recordStarted);
+                        this.recordDiagnosticEvent(SrDiagnostic.recordStarted, {});
                         _o.label = 3;
                     case 3:
                         _o.trys.push([3, 5, , 6]);