@grafana/faro-web-sdk

What is @grafana/faro-web-sdk?

@grafana/faro-web-sdk is a JavaScript SDK designed to integrate with Grafana Faro, a platform for observability and monitoring. It provides tools for logging, tracing, and collecting metrics from web applications, helping developers monitor and debug their applications effectively.

What are @grafana/faro-web-sdk's main functionalities?

Logging

The logging feature allows developers to send log messages to a Faro instance. This can be used to track application behavior and debug issues.

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

const faro = initializeFaro({
  url: 'https://your-faro-instance.com',
  app: { name: 'my-app', version: '1.0.0' }
});

faro.log('This is a log message');

Tracing

Tracing helps in monitoring the flow of requests and operations within an application. This feature allows developers to trace specific operations and collect contextual data.

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

const faro = initializeFaro({
  url: 'https://your-faro-instance.com',
  app: { name: 'my-app', version: '1.0.0' }
});

faro.trace('operation-name', { key: 'value' });

Metrics Collection

Metrics collection allows developers to gather quantitative data about their application's performance, such as response times or error rates, which can be visualized in Grafana.

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

const faro = initializeFaro({
  url: 'https://your-faro-instance.com',
  app: { name: 'my-app', version: '1.0.0' }
});

faro.metric('metric-name', 100);

Other packages similar to @grafana/faro-web-sdk

sentry

Sentry is a popular open-source error tracking and performance monitoring tool. It provides similar functionalities to @grafana/faro-web-sdk, such as logging, tracing, and metrics collection, but is more focused on error tracking and performance monitoring across various platforms.

logrocket

LogRocket is a front-end application monitoring solution that provides session replay, error tracking, and performance monitoring. While it offers similar logging and monitoring capabilities as @grafana/faro-web-sdk, it is particularly strong in session replay and user experience analysis.

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');

Changelog

1.18.2

• fix(user actions): don't attach user action context to http request when in halt mode (#1249)

• chore(deps): Updated Node.js version support by removing Node.js 18 (EOL) and adding Node.js 24 LTS (#1259).