Send custom events

Faro correlates multiple data points such as logs, measurements, traces, and exceptions, to provide insights into how users interact with your web application. This is a powerful tool when you want to identify user experience bottlenecks with context-rich data from across the stack.

Although integrating the Faro Web SDK in your application provides auto instrumentation, there are cases where you might want to track user behavior by sending events during a session (for example, when a user clicks a button. The SDK includes an event API that can send any event.

The events sent to the collector endpoint are ingested by a Loki instance as logs with a specific label kind=event. For more information about Loki labels, refer to Labels.

To reduce data usage Faro de-duplicates events. This means if two similar events are emitted consecutively, Faro only sends the event once.

Before you begin

Ensure you have registered your app in the Frontend Observability plugin
Set up the Faro Web SDK from the quickstart or instrumentation documentation.

Steps

A Faro instance is an object that can be accessed, after initialization, by either importing it from the @grafana/faro-web-sdk or by referencing it from the window global object.

// Import the global faro instance
import { faro } from '@grafana/faro-web-sdk';

The faro.api object is a wrapper of the Faro API and provides a pushEvent method with which you can send any event. You can also provide optional event metadata and a domain that is used to group events.

// Send custom events with Faro SDK.
// 1. Send a simple, string based event
// 2. Send an event with enriched context

// Simple usecase
faro.api.pushEvent('user clicked add-to-cart');

// Context rich usecase
faro.api.pushEvent(
  'user clicked add-to-cart',
  {
    cartLength: 5,
  },
  'checkout'
);

API

The events API allows you to pass the following parameters and options:

pushEvent: (name: string, attributes?: EventAttributes, domain?: string, options?: PushEventOptions)

Parameters

Name	Description
`name`	The name of the event
`attributes`	Includes additional event attributes as key/value pairs
`domain`	Separates events by domain
`options`	Configures the behavior of the push API or injects additional data to change the signal data.

Push event options

Name	Description
`skipDedupe`	Pushes the signal even if it is identical to the previous one
`spanContext`	Provides a custom `spanContext` to the signal
`timestampOverwriteMs`	The timestamp represents the exact moment when the respective API was called. In most cases, this precision is sufficient. The `timestampOverwriteMs`option allows you to pass an adjustment timestamp which can be used instead.

Modify beacon data before send

Faro provides the beforeSend hook which gets the current beacon (TransportItem) as it’s parameter, which allows you to modify beacon data before send:

initializeFaro({
  // ... faro configuration
  beforeSend: (item) => {
    switch (item.type) {
      case 'exception':
      case 'event':
      case 'trace':
      case 'measurement':
        return item;
      case 'log':
        return item.meta.user?.attributes?.['sendNoLogs'] ? null : item;
    }
  }