@nagoorkani/session-capture-vue 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -64,6 +64,27 @@ errors thrown inside components, which Vue catches itself and would otherwise
64
64
  never reach `window` — the plugin chains `app.config.errorHandler` rather than
65
65
  replacing it, so whatever the application already had there still runs.
66
66
 
67
+ ## Performance
68
+
69
+ Page-load timings are captured automatically from what the browser already
70
+ measured — no dependency, nothing to call: `ttfb`, `first_contentful_paint`,
71
+ `dom_content_loaded`, `page_load`, and `largest_contentful_paint`, which is only
72
+ final once the user leaves, so it is sent when the tab is hidden. They appear on
73
+ the session's Performance tab. Only the initial load is timed: a route change
74
+ inside the app is not a navigation to the browser.
75
+
76
+ Anything else, time yourself:
77
+
78
+ ```ts
79
+ import { startMeasure, endMeasure, markAppReady } from '@nagoorkani/session-capture-vue'
80
+
81
+ startMeasure('search')
82
+ await runSearch()
83
+ endMeasure('search') // recorded as "search 412ms"
84
+
85
+ markAppReady() // time from SDK load until your app says it is usable
86
+ ```
87
+
67
88
  ## Sessions
68
89
 
69
90
  **One per tab.** A session lives in `sessionStorage`, so a reload continues it
package/dist/index.d.ts CHANGED
@@ -58,6 +58,12 @@ export declare const onError: (listener: (sessionId: string) => void) => () => v
58
58
  * session the backend had already closed.
59
59
  */
60
60
  export declare const keepSessionAlive: () => void | undefined;
61
+ /** Start a named timing; `endMeasure` with the same name records it. */
62
+ export declare const startMeasure: (name: string) => void | undefined;
63
+ /** Finish a named timing and record it on the Performance tab. */
64
+ export declare const endMeasure: (name: string) => void | undefined;
65
+ /** Record time from SDK load until the app says it is usable. */
66
+ export declare const markAppReady: () => void | undefined;
61
67
  /** Stop capturing and unwind everything installed on the page. */
62
68
  export declare const shutdown: () => void | undefined;
63
69
  /** A `vue-router` instance, described by the two members used here. */
package/dist/index.js CHANGED
@@ -13,6 +13,7 @@
13
13
  import { addBreadcrumb, CONFIG_DIR, DEFAULT_CONFIG, Dispatcher, fetchRemoteConfig, installErrorHandlers, installNetworkCapture, loadCachedConfig, MemoryStore, safe, safeAsync, saveConfig, SDK_VERSION, SdkCore, SendQueue, } from '@nagoorkani/session-capture-core';
14
14
  import { readWebContext } from "./context.js";
15
15
  import { installLifecycleListener } from "./lifecycle-browser.js";
16
+ import { installPageTiming } from "./page-timing.js";
16
17
  import { loadSession, saveSession } from "./session-store.js";
17
18
  import { createBrowserStore } from "./store-browser.js";
18
19
  export { SCHEMA_VERSION, DEFAULT_CONFIG, SDK_VERSION } from '@nagoorkani/session-capture-core';
@@ -146,9 +147,13 @@ export const init = safe((options) => {
146
147
  persistSession();
147
148
  // Not awaited: `init` stays synchronous and the session opens immediately.
148
149
  void bootstrapConfig(options).catch(() => { });
150
+ const timing = installPageTiming((name, durationMs) => core?.capture('performance', { name, durationMs }));
151
+ teardown.push(timing.stop);
149
152
  teardown.push(installLifecycleListener((state) => {
150
153
  core?.onAppStateChange(state);
151
154
  if (state === 'background') {
155
+ // Before the flush below, so the final LCP leaves with this batch.
156
+ timing.finish();
152
157
  // The last chance to do anything. A hidden tab may never run again —
153
158
  // frozen into the back/forward cache, or simply closed — so the
154
159
  // session is written down and the queue is drained with `keepalive`,
@@ -250,6 +255,18 @@ export const keepSessionAlive = safe(() => {
250
255
  core?.keepAlive();
251
256
  persistSession();
252
257
  }, undefined, 'keepSessionAlive');
258
+ /** Start a named timing; `endMeasure` with the same name records it. */
259
+ export const startMeasure = safe((name) => {
260
+ core?.mark(name);
261
+ }, undefined, 'startMeasure');
262
+ /** Finish a named timing and record it on the Performance tab. */
263
+ export const endMeasure = safe((name) => {
264
+ core?.measure(name);
265
+ }, undefined, 'endMeasure');
266
+ /** Record time from SDK load until the app says it is usable. */
267
+ export const markAppReady = safe(() => {
268
+ core?.markReady();
269
+ }, undefined, 'markAppReady');
253
270
  /** Stop capturing and unwind everything installed on the page. */
254
271
  export const shutdown = safe(() => {
255
272
  for (const undo of teardown.splice(0)) {
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Page-load timings the browser has already measured.
3
+ *
4
+ * Free: Navigation Timing and paint entries cost nothing to read and need no
5
+ * dependency, which is why the web SDK has them while Expo, without a native
6
+ * module, has only what the app measures itself (`performance.ts` in core).
7
+ *
8
+ * ponytail: the initial page load only. A client-side route change is not a
9
+ * navigation to the browser, so SPA transitions are not timed; CLS and INP are
10
+ * not reported either, because neither is a duration and the Performance tab
11
+ * reads durations. Add them when the tab can show a score.
12
+ */
13
+ type Record = (name: string, durationMs: number) => void;
14
+ interface Timing {
15
+ /** Largest Contentful Paint keeps changing until the user interacts or
16
+ * leaves, so it is reported once, when the page is hidden. */
17
+ finish(): void;
18
+ stop(): void;
19
+ }
20
+ export declare function installPageTiming(record: Record): Timing;
21
+ export {};
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Page-load timings the browser has already measured.
3
+ *
4
+ * Free: Navigation Timing and paint entries cost nothing to read and need no
5
+ * dependency, which is why the web SDK has them while Expo, without a native
6
+ * module, has only what the app measures itself (`performance.ts` in core).
7
+ *
8
+ * ponytail: the initial page load only. A client-side route change is not a
9
+ * navigation to the browser, so SPA transitions are not timed; CLS and INP are
10
+ * not reported either, because neither is a duration and the Performance tab
11
+ * reads durations. Add them when the tab can show a score.
12
+ */
13
+ const NONE = { finish() { }, stop() { } };
14
+ export function installPageTiming(record) {
15
+ const perf = globalThis.performance;
16
+ const win = globalThis;
17
+ if (!perf?.getEntriesByType || typeof win.addEventListener !== 'function')
18
+ return NONE;
19
+ const report = (name, ms) => {
20
+ if (ms !== undefined && ms > 0)
21
+ record(name, Math.round(ms));
22
+ };
23
+ const onLoad = () => {
24
+ // `loadEventEnd` is only set once the load handlers return, hence a tick.
25
+ setTimeout(() => {
26
+ try {
27
+ const nav = perf.getEntriesByType('navigation')[0];
28
+ report('ttfb', nav?.responseStart);
29
+ report('dom_content_loaded', nav?.domContentLoadedEventEnd);
30
+ report('page_load', nav?.loadEventEnd);
31
+ }
32
+ catch {
33
+ // A timing is never worth an exception in someone else's page.
34
+ }
35
+ }, 0);
36
+ };
37
+ if (win.document?.readyState === 'complete')
38
+ onLoad();
39
+ else
40
+ win.addEventListener('load', onLoad, { once: true });
41
+ // Observed rather than read at load: on a light page the first paint lands
42
+ // after the load event, and would be missed by a read there.
43
+ const observe = (type, onEntries) => {
44
+ try {
45
+ if (!PerformanceObserver.supportedEntryTypes?.includes(type))
46
+ return undefined;
47
+ const observer = new PerformanceObserver((list) => onEntries(list.getEntries()));
48
+ observer.observe({ type, buffered: true });
49
+ return observer;
50
+ }
51
+ catch {
52
+ return undefined;
53
+ }
54
+ };
55
+ let fcpReported = false;
56
+ const paint = observe('paint', (entries) => {
57
+ const fcp = entries.find((e) => e.name === 'first-contentful-paint');
58
+ if (fcp && !fcpReported) {
59
+ fcpReported = true;
60
+ report('first_contentful_paint', fcp.startTime);
61
+ }
62
+ });
63
+ let lcp;
64
+ let largest = observe('largest-contentful-paint', (entries) => {
65
+ lcp = entries.at(-1)?.startTime ?? lcp;
66
+ });
67
+ const stop = () => {
68
+ paint?.disconnect();
69
+ largest?.disconnect();
70
+ largest = undefined;
71
+ win.removeEventListener?.('load', onLoad);
72
+ };
73
+ return {
74
+ finish() {
75
+ if (!largest)
76
+ return;
77
+ report('largest_contentful_paint', lcp);
78
+ stop();
79
+ },
80
+ stop,
81
+ };
82
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nagoorkani/session-capture-vue",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Session capture and observability for Vue 3 applications",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",