Documentation Grafana Cloud Monitor applications Frontend Observability Instrument User actions

Monitor user actions

Monitor your users’ critical interactions with your application by leveraging Faro’s User Actions instrumentation. Track the end-to-end journey and attach important context to signals such as HTTP requests and performance metrics as your users interact with your app.

Overview

A user action is an end user’s interaction with your product, for example, clicking a button or submitting a form. User actions are automatically or manually initiated, and linked with signals such as measurements, logs, and errors, within their lifetime to help you monitor critical paths, identify issues, and measure feature adoption rates.

Create a user action

User actions can be created in two primary ways:

1. Automatically: User actions are started when a user clicks or presses the Space/Enter key on an HTML element containing the data-faro-user-action-name attribute.

   The attribute name is customizable. Refer to Configuration for more details.

2. Manually: Use the Faro Web SDK faro.api.startUserAction method to programmatically start a user action with customizable options.

User action lifecycle

After creation, all signals within the user action’s lifetime are tagged with an action attribute. For example, a performance resource event looks like this:

JSON Copy

{
  "name": "faro.performance.resource",
  "domain": "browser",
  "attributes": {
    "name": "http://localhost:3000/",
    "duration": "45",
    "tcpHandshakeTime": "1"
    ...
  },
  "timestamp": "2025-07-17T08:09:34.051Z",
  "trace": {
    "trace_id": "77ae1ba7a590bb8c085deacb83907e87",
    "span_id": "83e4ec9b0511a4ec"
  },
  "action": {
    "parentId": "CdK96bsFeT",
    "name": "fetch-success"
  }
}

User actions follow two main lifecycle paths:

1. Completion

   • An action auto-completes 100ms after the last linked event is received. Each new event resets the timer.
   • Events are tagged with the action name and include timing data, such as userActionStartTime, userActionEndTime, and userActionDuration.
   • Completion after halt: If an open HTTP request exists after the 100ms mark, the action “halts” for up to 10s (configurable), allowing slow or long-running network requests to complete. After all requests close within the halt timeout, the action completes. If an open HTTP request exists after the 100ms mark, the action “halts” for up to 10s (configurable), allowing slow or long-running network requests to complete. After all requests close within the halt timeout, the action completes.

2. Cancellation

   • If no qualifying events occur within 100ms of user action creation, the action is cancelled and ignored.
   • Cancellation after halt: If an action halts waiting for requests but timeout occurs before they close, the action is cancelled.

Configuration

User Action instrumentation is enabled by default in the Faro SDK. If you use custom instrumentation, manually include the UserActionInstrumentation:

JavaScript Copy

import { UserActionInstrumentation } from '@grafana/faro-web-sdk';

const instrumentations = [
  // ...other instrumentations
  new UserActionInstrumentation(),
];

The data attribute name defaults to data-faro-user-action-name for automatic actions. To override it, use the trackUserActionsDataAttributeName option in your configuration:

JavaScript Copy

initializeFaro({
  // ... other config
  trackUserActionsDataAttributeName: 'myAttribute', // must be camelCase
});

Then, in your HTML:

HTML Copy

<button data-my-attribute="add-to-cart">Add to cart</button>

Clicking this button starts a new user action named add-to-cart.

Manual user action API

The startUserAction method offers advanced control and customization:

JavaScript Copy

startUserAction(
  name: string,
  attributes?: Record<string, string>,
  options?: StartUserActionOptions
)

Parameters

• name: (string) The name of the user action.
• attributes: (Record<string, string>, optional) Additional event attributes appended to the completion event.
• options.triggerName: (string, optional) Describes the action origin (default: 'faroApiCall' when used via API, or the event type if auto-created).
• options.severity: (enum, optional) Severity (import from core) for grouping/journey analysis.

Example usage

JavaScript Copy

faro.api.startUserAction(
  'checkout',
  { cartSize: '3', paymentMethod: 'card' },
  { triggerName: 'customEvent', severity: UserActionSeverity.Critical }
);

Best practices

• Use descriptive action names to make filtering and analysis easier.
• Attach relevant attributes to actions for enhanced context, for example, button name and page context.
• For highly custom interactions, prefer manual initiation with startUserAction.
• For Single Page Applications (SPA) where event handlers might take more than 100ms to execute, use the manual initiation and avoid using the HTML data- attribute as it might have unexpected behavior.