Documentation Grafana Cloud Monitor applications Frontend Observability Instrument Upgrading Upgrading Faro

Upgrade Faro

Grafana Faro follows Semantic Versioning for releases with the format MAJOR.MINOR.PATCH:

• MAJOR: Includes significant new features and potential breaking changes that affect how Faro operates
• MINOR: Introduces new features while maintaining backward compatibility
• PATCH: Contains bug fixes and security updates without breaking changes

We prioritize stability and backward compatibility in releases. Always review release notes and upgrade guides before installing a new Faro version.

All Faro package versions are synchronized and released together, even when changes affect only a single package. This ensures compatibility across the entire Faro package ecosystem.

We recommend upgrading to the latest Faro version for security updates, bug fixes, and new features. Security patches and feature releases only target the current version. We don’t provide backports or security updates for older major versions.

Supported Node.js versions

Faro supports all active LTS (Long Term Support) and current Node.js versions. We remove end-of-life versions from our test matrix, meaning that we can’t ensure support for such versions. All new Node.js releases are added as they become available. Refer to the Node.js release schedule for version details.

Before you begin

Before upgrading Faro, ensure you have the following:

• Access to the Faro changelog to review new features, bug fixes, and breaking changes
• Access to your project’s Faro configuration for any required setting updates

Upgrade Faro NPM packages

If you use the Faro NPM version, upgrade through your project’s package manager. Upgrade all Faro packages to the latest version, use your package manager’s upgrade command.

Learn about new features or breaking changes and update your Faro configuration.

Upgrade Faro CDN version

The CDN version automatically fetches the latest Faro version based on the version segment in the CDN link. Update the version parameter in your CDN URL to upgrade to a specific version or version range.

Example 1: faro-web-sdk@latest auto upgrades Faro to the latest version. Includes possibly breaking major releases.

Copy

"https://unpkg.com/@grafana/faro-web-sdk@latest/dist/bundle/faro-web-sdk.iife.js";

Example 2: faro-web-sdk@^1.0.0 auto upgrades Faro to the latest minor and patch versions in the 1.x.x range.

Copy

"https://unpkg.com/@grafana/faro-web-sdk@^1.0.0/dist/bundle/faro-web-sdk.iife.js";

Learn about new features or breaking changes before updating your Faro configuration.

After the upgrade

After upgrading Faro, verify the upgrade was successful and the SDK functions correctly.

Verify the Faro version

1. Open your browser’s developer tools and navigate to the Network tab.
2. Reload your application page.
3. Filter network requests by your Faro endpoint URL.
4. Inspect the meta.sdk object in a Faro payload to see the version information.
5. Alternatively, open the Console tab in your browser’s developer tools and enter faro.metas.value.sdk. The result should display version information, for example {version: '1.19.0'}.

Verify network requests in the browser

1. Open your browser’s developer tools and navigate to the Network tab.
2. Reload your application page.
3. Filter network requests by your Faro endpoint URL.
4. Confirm you see POST requests being sent to your Faro collector endpoint with telemetry data.

Check the browser console for error messages

Open your browser’s developer tools and navigate to the Console tab. Look for Faro any new Faro related (error) messages.

Upgrade guides by Faro version

For Faro versions that include breaking changes, refer to the following version-specific upgrade guides for detailed migration instructions and configuration updates.