How grafana/faro-web-sdk works
Faro is a browser-focused frontend observability SDK. Its main workflow is to initialize web instrumentation, collect events and telemetry through the core APIs, then forward telemetry to a receiver such as Grafana Alloy, Grafana Cloud, or a custom endpoint. Core also manages metadata and transport batching; the web packages add session tracking, user-action monitoring, tracing, and React integrations. README statements establish the package capabilities and delivery destinations; some internal links are omitted where the sampled source does not show the call path.
Main entry points: index.ts Browser instrumentations · src/initialize.ts Web initialization · api/initialize.ts Telemetry APIs · transports/initialize.ts Transport dispatch
Components 22
SDK Core
- SDK initialization
packages/core/src/initialize.ts - Telemetry APIs
packages/core/src/api/initialize.ts - Metadata capture
packages/core/src/metas/capture.ts - Transport dispatch
packages/core/src/transports/initialize.ts - Batch executor
packages/core/src/transports/batchExecutor.ts
Browser Telemetry
- Web configuration
packages/web-sdk/src/config/makeCoreConfig.ts - Web initialization
packages/web-sdk/src/initialize.ts - Browser instrumentations
packages/web-sdk/src/instrumentations/index.ts - Error capture
packages/web-sdk/src/instrumentations/errors/instrumentation.ts - Performance metrics
packages/web-sdk/src/instrumentations/performance/instrumentation.ts - Session tracking
packages/web-sdk/src/instrumentations/session/sessionManager/sessionManagerUtils.ts - User actions
packages/web-sdk/src/instrumentations/userActions/userActionController.ts - Fetch transport
packages/web-sdk/src/transports/fetch/transport.ts
Tracing
- Web tracing
packages/web-tracing/src/instrumentation.ts - Trace export
packages/web-tracing/src/faroTraceExporter.ts
Framework Integrations
- Router instrumentation
packages/react/src/router/v6v7/FaroRoutes.tsx - React error boundary
packages/react/src/errorBoundary/FaroErrorBoundary.tsx
Experimental
- Session replay
experimental/instrumentation-replay/src/recordingState.ts - OTLP HTTP transport
experimental/transport-otlp-http/src/transport.ts
Other components
- Application developer
- Browser application
- Telemetry receiver
Connections 19
- Application developer → Web initialization: configures
- Browser application → Browser instrumentations: produces activity
- Web initialization → Web configuration: uses configuration
- Web initialization → Browser instrumentations: enables collection
- Browser instrumentations → Error capture: includes capture
- Browser instrumentations → Performance metrics: includes metrics
- Browser instrumentations → Session tracking: tracks sessions
- Browser instrumentations → User actions: tracks actions
- Telemetry APIs → Metadata capture: captures metadata
- Transport dispatch → Batch executor: batches items
packages/core/src/transports/initialize.ts - Web initialization → SDK initialization: initializes core
- Transport dispatch → Fetch transport: dispatches telemetry
- Web tracing → Trace export: exports traces
- Router instrumentation → Telemetry APIs: pushes route event
packages/react/src/router/v6v7/FaroRoutes.tsx - React error boundary → Telemetry APIs: reports exceptions
- Session replay → Telemetry APIs: records replay data
- OTLP HTTP transport → Telemetry receiver: sends OTLP
- Fetch transport → Telemetry receiver: forwards telemetry
README.md - OTLP HTTP transport → Telemetry receiver: sends telemetry
README.md