faro-web-sdk

@grafana/faro-web-sdk is the browser instrumentation package of Grafana’s Faro project, a real-user-monitoring (RUM) SDK purpose-built to feed the Grafana observability stack. A single initializeFaro() call wires up console capture, unhandled-error and rejection tracking, Web Vitals, session and view tracking, navigation timing, and CSP violation reporting, then batches the resulting logs, errors, measurements, and events over a fetch transport to a Grafana Alloy collector or Grafana Cloud endpoint.

Because it shares the @grafana/faro-core API, exception, log, and trace data collected in the browser correlates directly with backend traces in Tempo and logs in Loki, giving teams a single pane of glass from frontend interaction down to backend span. Companion packages (@grafana/faro-web-tracing for OpenTelemetry spans, @grafana/faro-react for React-specific instrumentation) extend the same core without requiring a different vendor SDK.

What You Get

• Pre-built instrumentations for console output, unhandled errors/rejections, Web Vitals, sessions, view changes, navigation timing, user actions, and CSP violations, all toggled via getWebInstrumentations()
• A FetchTransport (plus an experimental v2 transport) that batches and compresses telemetry before sending it to a configured collector URL
• Meta providers for browser, OS, page, and SDK metadata that are automatically attached to every event
• Session management with both persistent (localStorage-backed) and volatile session managers, including configurable inactivity/expiration windows
• Full re-export of @grafana/faro-core primitives (API types, internal logger, promise buffer, global-object helpers) so the web SDK is a complete, self-sufficient entry point

Common Use Cases

• Adding real user monitoring to a production single-page app to catch JS errors and slow page loads before users report them
• Correlating frontend exceptions with backend traces by feeding both into the same Grafana Tempo/Loki backend
• Tracking Core Web Vitals (LCP, CLS, INP) across a fleet of marketing or product pages to catch performance regressions
• Capturing user session replay context (session start/resume/extend events) to reconstruct what a user did before a crash
• Self-hosting an observability pipeline via Grafana Alloy instead of sending frontend telemetry to a third-party SaaS RUM vendor

Under The Hood

Architecture The SDK is layered on top of @grafana/faro-core, which owns the transport/instrumentation/extension contracts, the internal event API (pushLog, pushError, pushMeasurement), and the global faro singleton. packages/web-sdk supplies the browser-specific implementations: makeCoreConfig() (packages/web-sdk/src/config/makeCoreConfig.ts) normalizes a BrowserConfig into the core’s Config shape, filling in default metas (browser, OS, page, SDK), a default FetchTransport, session-tracking overrides, and a filtered instrumentation list; initialize.ts then hands that config to core’s initializeFaro(). Each instrumentation (errors, web-vitals, session, view, navigation, CSP, user-actions) is a self-contained class under src/instrumentations/* implementing the core’s BaseInstrumentation extension point, so adding or removing a capability is additive rather than invasive. What breaks if the core abstraction changes: every instrumentation and transport in this package, plus the sibling faro-react and faro-web-tracing packages, since they all extend the same core interfaces.

Tech Stack TypeScript throughout (97.6% of the repo), built with tsdown into dual CJS/ESM/.d.ts outputs per package, orchestrated as a Yarn 4 + Lerna monorepo (packages/*, experimental/*, e2e/* workspaces). Runtime dependencies are deliberately minimal: ua-parser-js for browser/OS parsing and Google’s web-vitals package for Core Web Vitals collection; everything else (batching, buffering, logging) is hand-rolled in @grafana/faro-core rather than pulled from a third-party observability SDK. CI runs through Drone (.drone/) and GitHub Actions, with husky+lint-staged enforcing lint/format on commit.

Code Quality The web-sdk package alone carries 38 *.test.ts files exercising instrumentations, transports, and utilities (transport.test.ts, registerOnerror.test.ts, getErrorDetails.test.ts, etc.) under Jest + ts-jest with a jsdom environment, plus a packages/e2e Cypress smoke suite for end-to-end coverage. ESLint is configured with @grafana/eslint-config, TypeScript-ESLint, eslint-plugin-jsdoc, and eslint-plugin-no-only-tests (to stop .only() tests reaching CI); Prettier and markdownlint cover formatting. quality:circular-deps runs madge to catch import cycles. Config types (BrowserConfig) are fully typed, and error paths funnel through a dedicated internal logger rather than being swallowed silently.

API Design The public surface is intentionally narrow: initializeFaro(config) is the only call most integrators need, and getWebInstrumentations() supplies sane defaults (console, errors, web-vitals, session, view, navigation, performance) that can be selectively disabled via boolean options rather than requiring manual instrumentation assembly. Escape hatches exist for advanced users — custom transports, a v2 fetch transport behind an experimental flag, and direct access to every exported instrumentation class for hand-picked setups. Documentation trades a large from-scratch README for pointers into docs/sources/tutorials/ (quick-start, CDN usage, Angular integration), which keeps the root README approachable while still covering framework-specific onboarding elsewhere in the repo.