Grafana Cloud

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.


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
  'user clicked add-to-cart',
    cartLength: 5,

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:

  // ... 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;