@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
consoleglobal object. Onlywarn,infoanderrorlevels 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
- navigation - captures soft navigations and reports their URL changes and durations
- frustration - sends an event for each rage click, dead click and error click, but not for ordinary clicks
Navigation instrumentation is enabled by default. To disable it, pass trackNavigation: false to
getWebInstrumentations() when supplying custom instrumentations, or provide a custom instrumentations array without
NavigationInstrumentation.
Metas
- browser - captures browser metadata: name, version, etc
- os - captures OS name and version parsed from the user agent
- page - captures current URL
- view - the web SDK enforces a
defaultvalue 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');