Send custom measurements

Faro Web SDK exposes some performance measurements, but there are cases where you might need to send application-specific data. For example, you might want to report some internals of the JavaScript framework you are using, or the time that it was elapsed before a user completed a form. The SDK comes with a simple API to do so.

Before you begin

Ensure you have registered your app in the Frontend Observability plugin
Initialize the Faro Web SDK as described in the Get started with Grafana Cloud Frontend Observability

Steps

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 pushMeasurementmethod with which you can send any number of number values.

// Send custom measurements with Faro SDK.
// This example reports some hypothetical measurements from the JavaScript
// framework the application is using.

// send a single measurement
faro.api.pushMeasurement({
  type: 'internal_framework_measurements',
  values: {
    root_render_ms: 142.3,
    memory_used: 286,
  },
});

// send a single measurement with additional contextual attributes
faro.api.pushMeasurement(
  {
    type: 'internal_framework_measurements',
    values: {
      root_render_ms: 142.3,
      memory_used: 286,
    },
  },
  {
    context: {
      hello: 'world',
    },
  }
);

These measurements will ultimately be ingested into a Loki instance as logs with a specific label kind=measurements. For more information about Loki labels, refer to Labels. This is done because the corresponding metrics would potentially be of high cardinality, since e.g. each browser session is being recorded. Measurements stored as logs don’t suffer from this as this information is just stored in the log line. To use the measurements as metrics for visualisations and aggregations, use LogQL metric queries and consider using recording rules.