Grafana Cloud Monitor applications Frontend Observability

Grafana Cloud Frontend Observability

Grafana Cloud Frontend Observability provides a simplified and feature rich approach to instrument your web applications. With it you can visualize the performance of your application in real time as well as get a real-time stream of errors and exceptions.

Get started with Grafana Faro Web SDK

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 details about the SDK, see the relevant documentation

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

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.

Before you begin

• Ensure you have a Grafana Cloud instance with access to Grafana Cloud Logs and Grafana Cloud Traces.
• Become familiar with the core functionality of Grafana Faro Web SDK.

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.

   • Extra Log Labels: The application observability service includes labels that help you to better understand logs. If you require more fine-grained labels, you can add them.

     The system adds the label to every log.

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 Provided instrumentations.

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

   # 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

   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 does not 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

<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 from above so it will be 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.