feat(PoC): track user actions (#1033)

Author: codecapitano

demo/src/client/faro/initialize.ts

@@ -15,6 +15,7 @@ export function initializeFaro(): Faro {
   const faro = coreInit({
     url: `http://localhost:${env.faro.portAppReceiver}/collect`,
     apiKey: env.faro.apiKey,
+
     trackWebVitalsAttribution: true,
     instrumentations: [
       ...getWebInstrumentations({
@@ -41,6 +42,13 @@ export function initializeFaro(): Faro {
       version: env.package.version,
       environment: env.mode.name,
     },
+    trackResources: true,
+
+    batching: {
+      itemLimit: 100,
+    },
+
+    trackUserActions: true,
   });
 
   faro.api.pushLog(['Faro was initialized']);

demo/src/client/pages/Features/Counter.tsx

@@ -15,7 +15,10 @@ export function CounterComponent({ description, title, value, onChange }: Counte
       <h4 className="mt-3">{title}</h4>
       <p>{description}</p>
       <p>
-        Counter: {value} <Button onClick={() => onChange(value + 1)}>Increment</Button>
+        Counter: {value}{' '}
+        <Button onClick={() => onChange(value + 1)} data-faro-user-action-name="counter-increment">
+          Increment
+        </Button>
       </p>
     </>
   );

demo/src/client/pages/Features/ErrorInstrumentation.tsx

@@ -16,6 +16,11 @@ export function ErrorInstrumentation() {
     fetch('http://localhost:64999', {
       method: 'POST',
     });
+
+    setTimeout(() => {
+      faro.api.pushLog(['Fetch error log']);
+      faro.api.pushError(new Error('TEST - This is a fetch error'));
+    }, 80);
   };
 
   const xhrError = () => {
@@ -47,10 +52,10 @@ export function ErrorInstrumentation() {
         <Button data-cy="btn-call-undefined" onClick={callUndefined}>
           Call Undefined Method
         </Button>
-        <Button data-cy="btn-fetch-error" onClick={fetchError}>
+        <Button data-cy="btn-fetch-error" onClick={fetchError} data-faro-user-action-name="fetch-error">
           Fetch Error
         </Button>
-        <Button data-cy="btn-xhr-error" onClick={xhrError}>
+        <Button data-cy="btn-xhr-error" onClick={xhrError} data-faro-user-action-name="xhr-error">
           XHR Error (promise)
         </Button>
         <Button data-cy="btn-promise-reject" onClick={promiseReject}>

demo/src/client/pages/Features/TracingInstrumentation.tsx

@@ -32,13 +32,13 @@ export function TracingInstrumentation() {
     <>
       <h3>Tracing Instrumentation</h3>
       <ButtonGroup>
-        <Button data-cy="btn-fetch-success" onClick={fetchSuccess}>
+        <Button data-cy="btn-fetch-success" onClick={fetchSuccess} data-faro-user-action-name="fetch-success">
           Fetch Success
         </Button>
-        <Button data-cy="btn-xhr-success" onClick={xhrSuccess}>
+        <Button data-cy="btn-xhr-success" onClick={xhrSuccess} data-faro-user-action-name="xhr-success">
           XHR Success
         </Button>
-        <Button data-cy="btn-trace-with-log" onClick={traceWithLog}>
+        <Button data-cy="btn-trace-with-log" onClick={traceWithLog} data-faro-user-action-name="trace-with-log">
           Trace with Log
         </Button>
       </ButtonGroup>

demo/src/client/pages/Login/LoginForm.tsx

@@ -55,7 +55,7 @@ export function LoginForm() {
         <Form.Control type="password" autoComplete="current-password" {...registerField('password')} />
       </Form.Group>
 
-      <Button variant="primary" type="submit">
+      <Button variant="primary" type="submit" data-faro-user-action-name="login">
         Login
       </Button>
     </Form>

demo/src/client/pages/Register/RegisterForm.tsx

@@ -61,7 +61,7 @@ export function RegisterForm() {
         <Form.Control type="password" autoComplete="current-password" {...registerField('password')} />
       </Form.Group>
 
-      <Button variant="primary" type="submit">
+      <Button variant="primary" type="submit" data-faro-user-action-name="register">
         Register
       </Button>
     </Form>

demo/src/client/pages/Seed/Seed.tsx

@@ -33,7 +33,7 @@ export function Seed() {
         instrumentation coming together.
       </p>
 
-      <Button onClick={handleSeed} disabled={seedResult.isLoading} className="mb-3">
+      <Button onClick={handleSeed} disabled={seedResult.isLoading} className="mb-3" data-faro-user-action-name="seed">
         Seed
       </Button>
 

docs/sources/tutorials/quick-start-browser.md

@@ -284,7 +284,13 @@ const resource = Resource.default().merge(
 
 const provider = new WebTracerProvider({ resource });
 
-provider.addSpanProcessor(new FaroSessionSpanProcessor(new BatchSpanProcessor(new FaroTraceExporter({ ...faro }))));
+provider.addSpanProcessor(
+  new FaroUserActionSpanProcessor(
+    new FaroMetaAttributesSpanProcessor(
+      new FaroSessionSpanProcessor(new BatchSpanProcessor(new FaroTraceExporter({ ...faro })))
+    )
+  )
+);
 
 provider.register({
   propagator: new W3CTraceContextPropagator(),

packages/core/src/api/ItemBuffer.ts

@@ -0,0 +1,27 @@
+import { isFunction } from '../utils/is';
+
+export class ItemBuffer<T> {
+  private buffer: T[];
+
+  constructor() {
+    this.buffer = [];
+  }
+
+  addItem(item: T) {
+    this.buffer.push(item);
+  }
+
+  flushBuffer(cb?: (item: T) => void) {
+    if (isFunction(cb)) {
+      for (const item of this.buffer) {
+        cb(item);
+      }
+    }
+
+    this.buffer.length = 0;
+  }
+
+  size() {
+    return this.buffer.length;
+  }
+}

packages/core/src/api/apiTestHelpers.ts

@@ -0,0 +1,38 @@
+import type { Transports } from '../transports';
+
+import type { TracesAPI } from './traces/types';
+
+export const mockMetas = {
+  add: jest.fn(),
+  remove: jest.fn(),
+  addListener: jest.fn(),
+  removeListener: jest.fn(),
+  value: {},
+};
+
+export const mockTransports: Transports = {
+  add: jest.fn(),
+  addBeforeSendHooks: jest.fn(),
+  execute: jest.fn(),
+  getBeforeSendHooks: jest.fn(),
+  remove: jest.fn(),
+  removeBeforeSendHooks: jest.fn(),
+  isPaused: function (): boolean {
+    throw new Error('Function not implemented.');
+  },
+  transports: [],
+  pause: function (): void {
+    throw new Error('Function not implemented.');
+  },
+  unpause: function (): void {
+    throw new Error('Function not implemented.');
+  },
+};
+
+export const mockTracesApi: TracesAPI = {
+  getOTEL: jest.fn(),
+  getTraceContext: jest.fn(),
+  initOTEL: jest.fn(),
+  isOTELInitialized: jest.fn(),
+  pushTraces: jest.fn(),
+};

packages/core/src/api/const.ts

@@ -0,0 +1,3 @@
+export const USER_ACTION_START_MESSAGE_TYPE = 'user-action-start';
+export const USER_ACTION_END_MESSAGE_TYPE = 'user-action-end';
+export const USER_ACTION_CANCEL_MESSAGE_TYPE = 'user-action-cancel';

packages/core/src/api/events/initialize.test.ts

@@ -1,8 +1,17 @@
 import type { TransportItem } from '../..';
 import { initializeFaro } from '../../initialize';
-import { mockConfig, MockTransport } from '../../testUtils';
-import type { API } from '../types';
-
+import { mockConfig, mockInternalLogger, MockTransport } from '../../testUtils';
+import { dateNow } from '../../utils';
+import { mockMetas, mockTracesApi, mockTransports } from '../apiTestHelpers';
+import {
+  USER_ACTION_CANCEL_MESSAGE_TYPE,
+  USER_ACTION_END_MESSAGE_TYPE,
+  USER_ACTION_START_MESSAGE_TYPE,
+} from '../const';
+import { ItemBuffer } from '../ItemBuffer';
+import type { API, APIEvent, ApiMessageBusMessages } from '../types';
+
+import { initializeEventsAPI } from './initialize';
 import type { EventEvent, PushEventOptions } from './types';
 
 describe('api.events', () => {
@@ -161,4 +170,59 @@ describe('api.events', () => {
       });
     });
   });
+
+  describe('User action', () => {
+    it('buffers the error if a user action is in progress', () => {
+      const internalLogger = mockInternalLogger;
+      const config = mockConfig();
+
+      const actionBuffer = new ItemBuffer<TransportItem<APIEvent>>();
+
+      let message: ApiMessageBusMessages | undefined;
+
+      const getMessage = () => message;
+
+      message = {
+        type: USER_ACTION_START_MESSAGE_TYPE,
+        name: 'testAction',
+        startTime: Date.now(),
+        parentId: 'parent-id',
+      };
+      const api = initializeEventsAPI({
+        unpatchedConsole: console,
+        internalLogger,
+        config,
+        metas: mockMetas,
+        transports: mockTransports,
+        tracesApi: mockTracesApi,
+        actionBuffer,
+        getMessage,
+      });
+
+      api.pushEvent('test');
+      expect(actionBuffer.size()).toBe(1);
+
+      message = {
+        type: USER_ACTION_END_MESSAGE_TYPE,
+        name: 'testAction',
+        id: 'parent-id',
+        startTime: dateNow(),
+        endTime: dateNow(),
+        duration: 0,
+        eventType: 'click',
+      };
+
+      api.pushEvent('test-2');
+      expect(actionBuffer.size()).toBe(1);
+
+      message = {
+        type: USER_ACTION_CANCEL_MESSAGE_TYPE,
+        name: 'testAction',
+        parentId: 'parent-id',
+      };
+
+      api.pushEvent('test-3');
+      expect(actionBuffer.size()).toBe(1);
+    });
+  });
 });

packages/core/src/api/events/initialize.ts

@@ -6,32 +6,45 @@ import type { TransportItem, Transports } from '../../transports';
 import type { UnpatchedConsole } from '../../unpatchedConsole';
 import { deepEqual, getCurrentTimestamp, isEmpty, isNull, stringifyObjectValues } from '../../utils';
 import { timestampToIsoString } from '../../utils/date';
+import { USER_ACTION_START_MESSAGE_TYPE } from '../const';
+import type { ItemBuffer } from '../ItemBuffer';
 import type { TracesAPI } from '../traces';
+import type { ApiMessageBusMessages } from '../types';
 
 import type { EventEvent, EventsAPI } from './types';
 
-export function initializeEventsAPI(
-  _unpatchedConsole: UnpatchedConsole,
-  internalLogger: InternalLogger,
-  config: Config,
-  metas: Metas,
-  transports: Transports,
-  tracesApi: TracesAPI
-): EventsAPI {
+export function initializeEventsAPI({
+  internalLogger,
+  config,
+  metas,
+  transports,
+  tracesApi,
+  actionBuffer,
+  getMessage,
+}: {
+  unpatchedConsole: UnpatchedConsole;
+  internalLogger: InternalLogger;
+  config: Config;
+  metas: Metas;
+  transports: Transports;
+  tracesApi: TracesAPI;
+  actionBuffer: ItemBuffer<TransportItem>;
+  getMessage: () => ApiMessageBusMessages | undefined;
+}): EventsAPI {
   let lastPayload: Pick<EventEvent, 'name' | 'domain' | 'attributes'> | null = null;
 
   const pushEvent: EventsAPI['pushEvent'] = (
     name,
     attributes,
     domain,
-    { skipDedupe, spanContext, timestampOverwriteMs } = {}
+    { skipDedupe, spanContext, timestampOverwriteMs, customPayloadTransformer = (payload: EventEvent) => payload } = {}
   ) => {
     try {
       const attrs = stringifyObjectValues(attributes);
 
       const item: TransportItem<EventEvent> = {
         meta: metas.value,
-        payload: {
+        payload: customPayloadTransformer({
           name,
           domain: domain ?? config.eventDomain,
           attributes: isEmpty(attrs) ? undefined : attrs,
@@ -42,7 +55,7 @@ export function initializeEventsAPI(
                 span_id: spanContext.spanId,
               }
             : tracesApi.getTraceContext(),
-        },
+        }),
         type: TransportItemType.EVENT,
       };
 
@@ -62,7 +75,12 @@ export function initializeEventsAPI(
 
       internalLogger.debug('Pushing event\n', item);
 
-      transports.execute(item);
+      const msg = getMessage();
+      if (msg && msg.type === USER_ACTION_START_MESSAGE_TYPE) {
+        actionBuffer.addItem(item);
+      } else {
+        transports.execute(item);
+      }
     } catch (err) {
       internalLogger.error('Error pushing event', err);
     }

packages/core/src/api/events/types.ts

@@ -1,6 +1,7 @@
 import type { SpanContext } from '@opentelemetry/api';
 
 import type { TraceContext } from '../traces';
+import type { UserAction } from '../types';
 
 export type EventAttributes = Record<string, string>;
 
@@ -11,12 +12,24 @@ export interface EventEvent {
   domain?: string;
   attributes?: EventAttributes;
   trace?: TraceContext;
+
+  action?: UserAction;
 }
 
 export interface PushEventOptions {
   skipDedupe?: boolean;
   spanContext?: Pick<SpanContext, 'traceId' | 'spanId'>;
   timestampOverwriteMs?: number;
+
+  /**
+   * Allows manual transformation of the payload before adding it to the internal buffer.
+   *
+   * @param payload - The event payload to be transformed.
+   * @returns The transformed event payload.
+   *
+   * @remarks This should be used sparingly and only in special cases where custom payload processing cannot be deferred to the before-send hook.
+   */
+  customPayloadTransformer?: (payload: EventEvent) => EventEvent;
 }
 
 export interface EventsAPI {