repository·main·Indexed 22 days ago
https://github.com/grafana/faro-web-sdkA toolkit for instrumenting frontend JavaScript applications to collect and forward telemetry—including logs, traces, and metrics—to observability backends such as Grafana Cloud, Loki, or Tempo. It supports various frameworks including React, Next.js, Angular, Vue, Svelte, and Vanilla JS. Key features include automatic tracking of JavaScript errors, Core Web Vitals, and distributed tracing for API calls, as well as experimental support for session replay and OpenTelemetry HTTP transport.
Grafana Faro Web SDK is used to instrument frontend JavaScript applications to collect telemetry. This telemetry can be forwarded to:
Once collected, data can be sent to Loki (for logs) or Tempo (for traces).
The @grafana/faro-web-tracing package allows you to integrate OpenTelemetry-based tracing into your application using the Faro Web SDK. This enables web-based distributed tracing to be captured and sent via Faro's transport mechanisms.
To use this package, you must have the Faro Web SDK already configured in your application.
The @grafana/faro-react package is a distribution of the Faro Web SDK specifically designed for React projects. It simplifies integration by providing specialized React-aware features that automatically capture telemetry related to the React component lifecycle and routing.
Key features include:
pushError behavior.The view meta allows you to associate signals with specific sections of your UI that change without a full route change (e.g., an auth view containing both sign-in and sign-up components).
Unlike other dynamic metas, view does not change automatically. You can set it during initialization or update it programmatically to track movement between different UI states.
/* Example View meta */
{
"name": "auth"
}You can customize what the SDK captures by providing an array of instrumentations to initializeFaro.
Available Instrumentations:
console: Captures warn, info, and error messages from the global console object.errors: Captures unhandled top-level exceptions.web-vitals: Captures performance metrics from the web vitals API.session: Sends session start events.view: Sends view changed events.To enable console capture, use getWebInstrumentations({ captureConsole: true }). For OpenTelemetry (OTel) tracing, include TracingInstrumentation from @grafana/faro-web-tracing in the instrumentations array.
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',
},
});The 'unpatched console' is the original, unmodified console object captured at the very beginning of the Faro initialization process. Faro uses this unpatched instance for several critical purposes:
console is later modified.By capturing the console before any other logic runs, Faro ensures its own telemetry and error reporting remain reliable even if the host application overrides console.log, console.error, etc.
The app meta ties signals to a specific application. It is a static meta that must be defined by the end-user during initialization and should not change during a session.
When using the faro-web-tracing package, the following mapping occurs for resource attributes:
name, namespace, and version are attached as service.name|namespace|version.environment becomes deployment.environment./* Example properties for App meta */
{
"name": "my-app",
"version": "1.0.0",
"namespace": "my-namespace",
"release": "commit-hash-or-build-id",
"environment": "production",
"bundleId": "com.example.app", // mobile
"installationId": "unique-id" // mobile
}In the Faro architecture, Instrumentations are the data collectors. Their primary responsibility is to gather data from various sources, such as browser APIs or other available interfaces.
Note that the @grafana/faro-core library does not include any instrumentations by default. They are typically provided in one of two ways:
@grafana/faro-web-sdk.Metas are key-value properties sent with every payload to provide context to signals. They are categorized into two types:
app).page, view).Faro supports several advanced configuration options to enhance observability:
/users/:id) instead of raw URLs.console.log calls.The SDK is modular. Depending on your requirements, you can combine different packages:
By default, OtlpHttpTransport only adds the body property to signals that have a body value. This excludes Measurement and Exception signals, which can cause issues with some Otel Collector components.
To resolve this, use the otlpTransform property in OtlpHttpTransportOptions to provide custom body string generators: createErrorLogBody and createMeasurementLogBody. Each function receives a TransportItem representing the log being transformed, allowing you to build a custom string from the payload.
initializeFaro({
// ...
transports: [
new OtlpHttpTransport({
apiKey: env.faro.apiKey,
logsURL: 'https://example.com/v1/logs',
tracesURL: 'https://example.com/v1/traces',
// customize logs transformation
otlpTransform: {
// create custom body string for measurement logs
createMeasurementLogBody(item) {
const { payload } = item;
const [measurementName, measurementValue] = Object.entries(payload.values).flat();
const body = `faro.signal.measurement: type=${payload.type} name=${measurementName} value=${measurementValue}`;
return body;
},
// create custom body string for error logs
createErrorLogBody(item) {
const { payload } = item;
const body = `faro.signal.error: type=${payload.type} message=${payload.value}`;
return body;
},
},
}),
],
});