Merge pull request #74 from SpeedCurve-Metrics/feature/spa-improvements

Implement "SPA Mode"

Author: josephwynn-sc

docs/debug-parser.html

@@ -102,9 +102,11 @@ <h1>SpeedCurve RUM Debug Parser</h1>
         <h2>Parsed debug output <span id="event-counter"></span></h2>
 
         <div class="event-filters">
-            <label><input type="checkbox" checked class="event-filter" data-event="addData"> LUX.addData()</label>
-            <label><input type="checkbox" checked class="event-filter" data-event="userTiming"> LUX.mark/measure()</label>
-            <label><input type="checkbox" class="event-filter" data-event="beaconUrl"> Show beacon URL</label>
+            <label><input type="checkbox" checked class="event-filter" data-event="metrics"> Metrics Events</label>
+            <label><input type="checkbox" checked class="event-filter" data-event="addData"> <code>LUX.addData()</code></label>
+            <label><input type="checkbox" checked class="event-filter" data-event="userTiming"> <code>LUX.mark/measure()</code></label>
+            <label><input type="checkbox" class="event-filter" data-event="verbose"> Show Verbose Events</label>
+            <label><input type="checkbox" class="event-filter" data-event="beaconUrl"> Show Beacon URL</label>
         </div>
 
         <ul class="mt-1" id="output"></ul>

docs/debug-parser.js

@@ -14,7 +14,23 @@ export function isBeaconEvent(event: LogEvent) {
   ].includes(event);
 }
 
+function isVerboseEvent(event: LogEvent) {
+  return [
+    LogEvent.DataCollectionStart,
+    LogEvent.PostBeaconCancelled,
+    LogEvent.PostBeaconCSPViolation,
+    LogEvent.PostBeaconInitialised,
+    LogEvent.PostBeaconSendCalled,
+    LogEvent.PostBeaconStopRecording,
+    LogEvent.PostBeaconTimeoutReached,
+  ].includes(event);
+}
+
 export function getMessageForEvent(event: LogEventRecord, filters: string[]): string {
+  if (isVerboseEvent(event[1]) && !filters.includes("verbose")) {
+    return "";
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const args = event[2] as any[];
 
@@ -26,20 +42,23 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
   }
 
   switch (event[1]) {
-    case 0:
+    case 0 as LogEvent:
       return "The lux.js script was not loaded on this page.";
 
     case LogEvent.EvaluationStart:
-      return `lux.js v${args[0]} is initialising.`;
+      return `lux.js v${args[0]} init begin.`;
 
     case LogEvent.EvaluationEnd:
-      return "lux.js has finished initialising.";
+      return "lux.js init complete.";
 
     case LogEvent.InitCalled:
-      return "LUX.init()";
+      return "🟢 LUX.init() - new page view started";
+
+    case LogEvent.StartSoftNavigationCalled:
+      return "🟢 LUX.startSoftNavigation() - new page view started";
 
     case LogEvent.MarkLoadTimeCalled:
-      return `LUX.markLoadTime(${argsAsString(args)})`;
+      return `🎯 LUX.markLoadTime(${argsAsString(args)})`;
 
     case LogEvent.MarkCalled:
       if (filters.includes("userTiming")) {
@@ -71,14 +90,17 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
     case LogEvent.SendCancelledPageHidden:
       return "This beacon was not sent because the page visibility was hidden.";
 
+    case LogEvent.SendCancelledSpaMode:
+      return "ℹ️ LUX.send() was ignored because SPA Mode is enabled.";
+
     case LogEvent.ForceSampleCalled:
       return "LUX.forceSample()";
 
     case LogEvent.DataCollectionStart:
       return "Preparing to send main beacon. Metrics received after this point may be ignored.";
 
     case LogEvent.UnloadHandlerTriggered:
-      return "Unload handler was triggered.";
+      return "⤴️ Unload handler was triggered.";
 
     case LogEvent.OnloadHandlerTriggered:
       message = `Onload handler was triggered after ${args[0]} ms.`;
@@ -96,7 +118,7 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return `Sample rate is ${args[0]}%. This session is not being sampled.`;
 
     case LogEvent.MainBeaconSent:
-      message = "Main beacon sent";
+      message = "📫 Main beacon sent";
 
       if (filters.includes("beaconUrl")) {
         message += `: ${args[0]}`;
@@ -105,7 +127,7 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return message;
 
     case LogEvent.UserTimingBeaconSent:
-      message = "Supplementary user timing beacon sent";
+      message = "📧 Supplementary user timing beacon sent";
 
       if (filters.includes("beaconUrl")) {
         message += `: ${args[0]}`;
@@ -114,7 +136,7 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return message;
 
     case LogEvent.InteractionBeaconSent:
-      message = "Supplementary user interaction beacon sent";
+      message = "📧 Supplementary user interaction beacon sent";
 
       if (filters.includes("beaconUrl")) {
         message += `: ${args[0]}`;
@@ -123,7 +145,7 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return message;
 
     case LogEvent.CustomDataBeaconSent:
-      message = "Supplementary custom data beacon sent";
+      message = "📧 Supplementary custom data beacon sent";
 
       if (filters.includes("beaconUrl")) {
         message += `: ${args[0]}`;
@@ -142,20 +164,17 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
 
     case LogEvent.PostBeaconSent:
       if (filters.includes("beaconUrl")) {
-        return `POST beacon sent: ${args[0]}`;
+        return `📫 POST beacon sent: ${args[0]}`;
       }
 
-      return "POST beacon sent.";
+      return "📫 POST beacon sent.";
 
     case LogEvent.PostBeaconSendFailed:
       if (filters.includes("beaconUrl")) {
-        return `POST beacon send failed: ${args[0]}`;
+        return `⚠️ POST beacon send failed: ${args[0]}`;
       }
 
-      return "POST beacon send failed.";
-
-    case LogEvent.PostBeaconAlreadySent:
-      return "POST beacon cancelled (already sent).";
+      return "⚠️ POST beacon send failed.";
 
     case LogEvent.PostBeaconCancelled:
       return "POST beacon cancelled.";
@@ -170,12 +189,20 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return "POST beacon cancelled due to CSP violation.";
 
     case LogEvent.PostBeaconCollector:
-      return `POST beacon metric collector: ${args[0]} (has data: ${args[1]})`;
+      if (filters.includes("metrics")) {
+        return `POST beacon metric collector: ${args[0]} (has data: ${args[1]})`;
+      }
+
+      return "";
 
     case LogEvent.NavigationStart:
       return "";
 
     case LogEvent.PerformanceEntryReceived:
+      if (!filters.includes("metrics")) {
+        return "";
+      }
+
       if (args[0].entryType === "layout-shift") {
         return `Received layout shift at ${args[0].startTime.toFixed()} ms with value of ${args[0].value.toFixed(
           3,
@@ -207,7 +234,7 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
       return message;
 
     case LogEvent.PerformanceEntryProcessed:
-      if (args[0].entryType === "largest-contentful-paint") {
+      if (filters.includes("metrics") && args[0].entryType === "largest-contentful-paint") {
         return `Picked LCP from entry at ${args[0].startTime.toFixed()} ms`;
       }
 
@@ -272,6 +299,12 @@ function getEventName(event: LogEvent) {
       return "MarkLoadTimeCalled";
     case LogEvent.SendCancelledPageHidden:
       return "SendCancelledPageHidden";
+    case LogEvent.StartSoftNavigationCalled:
+      return "StartSoftNavigationCalled";
+    case LogEvent.SendCancelledSpaMode:
+      return "SendCancelledSpaMode";
+    case LogEvent.BfCacheRestore:
+      return "BfCacheRestore";
     case LogEvent.SessionIsSampled:
       return "SessionIsSampled";
     case LogEvent.SessionIsNotSampled:
@@ -318,8 +351,6 @@ function getEventName(event: LogEvent) {
       return "PostBeaconTimeoutReached";
     case LogEvent.PostBeaconSent:
       return "PostBeaconSent";
-    case LogEvent.PostBeaconAlreadySent:
-      return "PostBeaconAlreadySent";
     case LogEvent.PostBeaconCancelled:
       return "PostBeaconCancelled";
     case LogEvent.PostBeaconStopRecording:
@@ -333,4 +364,6 @@ function getEventName(event: LogEvent) {
     case LogEvent.PostBeaconCollector:
       return "PostBeaconCollector";
   }
+
+  return "Unknown Event";
 }

docs/debug-parser/events.ts

@@ -34,7 +34,9 @@ function renderOutput(output: Element) {
     output.appendChild(li(`Could not parse input: ${err}`, "red"));
   }
 
-  eventCounter.innerText = `(${inputEvents.length} events)`;
+  const sentBeacons = inputEvents.filter((event) => event[1] === LogEvent.MainBeaconSent);
+
+  eventCounter.innerText = `(${inputEvents.length} events; ${sentBeacons.length} page views)`;
 
   let navigationStart = Number(new Date(inputEvents[0][0]));
 
@@ -183,7 +185,7 @@ function renderOutput(output: Element) {
 
   output.prepend(
     li(
-      `0 ms: Navigation started at ${startTime.toLocaleDateString()} ${startTime.toLocaleTimeString()}`,
+      `0 ms: 🟢 Navigation started at ${startTime.toLocaleDateString()} ${startTime.toLocaleTimeString()}`,
     ),
   );
 }

docs/debug-parser/index.ts

@@ -0,0 +1,7 @@
+# SPA Mode in lux.js
+
+## Migrating from `LUX.auto = false`
+
+- Remove `LUX.auto = false`.
+- Remove all `LUX.send()` calls. In SPA mode, the beacon is sent automatically. In some very rare cases you may want to send the beacon manually, which can be done by calling `LUX.send(true)` - **this is not recommended**.
+- Replace all `LUX.init()` calls with `LUX.startSoftNavigation()`.