Documentation Grafana Cloud Monitor applications Frontend Observability Instrument JavaScript

Frontend Observability instrumentation setup

Grafana Faro Web SDK is a library that collects observability data from your web application and sends it to Grafana Cloud.

This guide describes how to add the Grafana Faro Web SDK package and the optional tracing package to your application.

For more information about the instrumentations included in the Grafana Faro Web SDK, refer to the instrumentation documentation.

For more information about the transports included in the Grafana Faro Web SDK, refer to Provided transports.

For more information about the metas included in the Grafana Faro Web SDK, refer to Provided metas.

Ensure you have a Grafana Cloud instance with access to Grafana Cloud Logs and Grafana Cloud Traces.

Create an application in Grafana Cloud Frontend Observability

The application you create in Grafana Cloud connects your frontend application with the Grafana Faro Web SDK.

1. Sign in to your Grafana Cloud instance.

2. On the Home page, click Observability > Frontend.

3. Click Create new.

4. On the Application creation page, complete the following fields:

   • Application Name: Enter the name of your application.

     The name of your application can be any string. You use the application name to filter signals.

   • CORS Allowed Origins: Add allowed origins to accept data from.

     The following rules are used to match allowed origins:

     • If no origin is supplied, all origins are blocked.
     • Origins are matched exactly. For example, https://app.grafana.com.
     • Origins can contain one wildcard character to match 0 or more characters. For example, https://*.grafana.com.

     Matching all domains with a global wildcard rule * is supported but discouraged as it allows anyone to submit data to your endpoint.

     Allow two minutes for saved changes to CORS Allowed Origins to propagate and take effect.

   • Default attributes: the default attributes added to all signals (logs, events, errors, etc). Adding default attributes in Frontend Observability reduces bandwidth and ensures the attributes are always present.

5. Click Create.

Use the wizard to guide you through integrating Grafana Faro Web SDK into your codebase and start sending signals.

Add the Grafana Faro Web SDK package to your application

As of Grafana Faro Web SDK version 1.0.0-beta4, you can add the library to your application using either NPM registry or a CDN like unpkg.

The Grafana Faro Web SDK comes preconfigured for the most common use cases. For advanced configuration options, refer to the instrumentation documentation.

Add the Grafana Faro Web SDK package using NPM registry

Because Grafana Faro Web SDK is distributed using the NPM registry, use your package manager to add it to your application.

1. Run one of the following commands, depending on your package manager. The command installs the library in your project.

   shell Copy

   # Using npm
   npm install @grafana/faro-web-sdk
   
   # Using yarn
   yarn add @grafana/faro-web-sdk
   
   # Using pnpm
   pnpm add @grafana/faro-web-sdk

2. Add the following code snippet in your application before any other JavaScript/TypeScript code:

   ts Copy

   import { initializeFaro } from '@grafana/faro-web-sdk';
   
   initializeFaro({
     // Mandatory, the URL of the Grafana Cloud collector with embedded application key.
     // Copy from the configuration page of your application in Grafana.
     url: 'http://faro-collector-us-central-0.grafana.net/collect/{app-key}',
   
     // Mandatory, the identification label(s) of your application
     app: {
       name: 'my-app',
       version: '1.0.0', // Optional, but recommended
     },
   });

Add the Grafana Faro Web SDK package using a CDN

Alternatively, if your project doesn’t use a package manager, you can add the Grafana Faro Web SDK using a CDN like unpkg. This is possible because the library is distributed as an IIFE (Immediately Invoked Function Expression) module as well, meaning that the entire content of the library is exposed to you in a global variable called GrafanaFaroWebSdk.

The easiest way to add the Grafana Faro Web SDK to your application is to add the following script to the head of the HTML document:

html Copy

<script>
  (function () {
    // Create a script tag for loading the library
    var script = document.createElement('script');

    // Initialize the Web SDK at the onLoad event of the script element so it is called when the library is loaded.
    script.onload = () => {
      window.GrafanaFaroWebSdk.initializeFaro({
        // Mandatory, the URL of the Grafana Cloud collector with embedded application key.
        // Copy from the configuration page of your application in Grafana.
        url: 'http://faro-collector-us-central-0.grafana.net/collect/{app-key}',

        // Mandatory, the identification label(s) of your application
        app: {
          name: 'my-app',
          version: '1.0.0', // Optional, but recommended
        },
      });
    };

    // Set the source of the script tag to the CDN
    script.src = 'https://unpkg.com/@grafana/faro-web-sdk@^1.0.0-beta/dist/bundle/faro-web-sdk.iife.js';

    // Append the script tag to the head of the HTML document
    document.head.appendChild(script);
  })();
</script>

Add OpenTelemetry-JS based tracing to your application

For instructions on how to integrate with OpenTelemetry-JS and set up tracing, refer to Integrate OpenTelemetry-JS tracing with Faro.