Package Exports

@grafana/faro-web-sdk
@grafana/faro-web-sdk/dist/cjs/index.js
@grafana/faro-web-sdk/dist/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@grafana/faro-web-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@grafana/faro-web-sdk

Faro is a SDK that can instrument frontend JavaScript applications to collect telemetry and forward it to the Grafana Alloy (with app agent receiver integration enabled).

Grafana Alloy can then send this data to either Loki or Tempo.

Get started

See quick start for web applications.

Alternatively, you can use the CDN version of the library. See use cdn library for details on how to do so.

Instrumentations

console - captures messages logged to console global object. Only warn, info and error levels by default.
errors - captures unhandled top level exceptions
web-vitals - captures performance metrics reported by web vitals API
session - sends session start event
view - sends view changed event

Metas

browser - captures browser metadata: name, version, etc
page - captures current URL
view - the web SDK enforces a default value for the view meta

Transports

console - logs events to global console
fetch - sends events over HTTP to a backend

Example

Basic set up, will automatically report errors and web vitals:

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

const faro = initializeFaro({
  url: 'https://agent.myapp/collect',
  apiKey: 'secret',
  app: {
    name: 'frontend',
    version: '1.0.0',
  },
});

// send a log message
faro.api.pushLog(['hello world']);

// will be captured
throw new Error('oh no');

// push error manually
faro.api.pushError(new Error('oh no'));

With OTel tracing and browser console capture:

import { ConsoleInstrumentation, getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

const faro = initializeFaro({
  url: 'https://agent.myapp/collect',
  apiKey: 'secret',
  instrumentations: [...getWebInstrumentations({ captureConsole: true }), new TracingInstrumentation()],
  app: {
    name: 'frontend',
    version: '1.0.0',
  },
});

// start a span
faro.api
  .getOTEL()
  ?.trace.getTracer('frontend')
  .startActiveSpan('hello world', (span) => {
    // send a log message
    faro.api.pushLog(['hello world']);
    span.end();
  });

// will be captured
throw new Error('oh no');