Menu
Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Monitor applicationsbreadcrumb arrow Frontend Observabilitybreadcrumb arrow Instrumentbreadcrumb arrow Upgradingbreadcrumb arrow Upgrade to v2.0.0
Grafana Cloud

Upgrade to Faro v2.0.0

This guide explains the major changes introduced in Faro v2.0.0 (including beta versions). It details breaking changes and provides migration instructions for updating your existing configuration.

Breaking changes

  • Web Vitals library upgraded to version 5.x.x: The upgrade removes the deprecated First Input Delay (FID) metric. Use the Interaction to Next Paint (INP) metric instead. If you have custom dashboards or panels using the FID metric, update them to use INP.

  • Experimental packages removed: The following unmaintained experimental packages have been removed from the Faro codebase:

    • instrumentation-fetch
    • instrumentation-xhr
    • instrumentation-performance-timeline

    These packages remain available on NPM for a limited time and are marked as deprecated. If you didn’t explicitly add any of these experimental packages, you aren’t affected by the removal.

Tracing instrumentation

Removed the deprecated FaroSessionSpanProcessor The FaroSessionSpanProcessor was replaced by the FaroMetaAttributesSpanProcessor in earlier versions but remained available for users with custom Faro and OpenTelemetry setups.

To migrate from FaroSessionSpanProcessor, replace it with FaroMetaAttributesSpanProcessor in your configuration. No additional changes are required.

ts 
import { FaroMetaAttributesSpanProcessor, FaroTraceExporter } from '@grafana/faro-web-tracing';

const faro = initializeFaro(/* ... */);
const resource = /* ... */
const provider = new WebTracerProvider({ resource });

provider.addSpanProcessor(
  new FaroUserActionSpanProcessor( // if you useFaro's user actions feature
    new FaroMetaAttributesSpanProcessor(
      new BatchSpanProcessor(new FaroTraceExporter({ ...faro })
    ))
  )
);

Removed the deprecated session_id attribute

The deprecated session_id attribute has been removed in favor of session.id. If you need to maintain the session_id attribute for backward compatibility, add it manually using the resourceAttributes option in your TracingInstrumentation configuration:

ts 
import { VolatileSessionsManager } from '@grafana/faro-web-sdk';
// import { PersistentSessionsManager } from '@grafana/faro-web-sdk'; // if persistent (sticky) sessions are configured, default is volatile

initializeFaro({
  // ...

  instrumentations: [
    ...getWebInstrumentations(/* ... */),

    new TracingInstrumentation({
      resourceAttributes: {
        session_id: VolatileSessionsManager.fetchUserSession()?.sessionId,
        // session_id: PersistentSessionsManager.fetchUserSession()?.sessionId, // if persistent (sticky) sessions are configured, default is volatile
      },
    }),
  ],

  // ...
});

Console Instrumentation

Removed deprecated console instrumentation configuration options

Console instrumentation configuration options were removed from the ...getWebInstrumentations() function. Configure console instrumentation through the global Faro setup instead. Refer to How to use the console instrumentation for details.

Migration example

Note

The new configuration has been used in the Faro documentation for some time. If you don’t configure Console Instrumentation through the getWebInstrumentations() function, you don’t need to make any changes.

Before (deprecated configuration):

ts 
initializeFaro({
  // ...
  instrumentations: [
    ...getWebInstrumentations({
      // Optional, disables console instrumentation
      captureConsole: false,
      // Optional, collects all levels
      captureConsoleDisabledLevels: [],
      // Optional, disables specific levels
      captureConsoleDisabledLevels: [LogLevel.DEBUG, LogLevel.TRACE],
    }),
  ],
});

After (new configuration):

ts 
initializeFaro({
  instrumentations: [
    ...getWebInstrumentations({
      // Optional, disables console instrumentation
      captureConsole: false,
    }),
  ],

  // Console instrumentation configuration moved here
  consoleInstrumentation: {
    consoleErrorAsLog: true,
    // Optional, collects all levels
    captureConsoleDisabledLevels: [],
    // Optional, disables specific levels
    captureConsoleDisabledLevels: [LogLevel.DEBUG, LogLevel.TRACE],
  },
});

Removed the internal deprecated Faro conventions names object

The internal deprecated Faro conventions names object has been removed. This object contained constants for Faro event names used by internal instrumentations.

Note

If you don’t import constants from this object, no changes are required.

Migration example

Before (deprecated constants object):

ts 
export const Conventions = {
  EventNames: {
    CLICK: 'click',
    NAVIGATION: 'navigation',
    SESSION_START: 'session_start',
    VIEW_CHANGED: 'view_changed',
  },
} as const;

After (individual exports):

ts 
export const EVENT_CLICK = 'click';
export const EVENT_NAVIGATION = 'navigation';
export const EVENT_VIEW_CHANGED = 'view_changed';
export const EVENT_SESSION_START = 'session_start';