Grafana Faro Web SDKGet started with Grafana Faro Web SDK

Get started with Grafana Faro Web SDK

The Grafana Faro Web SDK powers the fully managed Frontend Application Observability service in Grafana Cloud, which is in private beta and not yet publicly available.

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

Create an observability application in Grafana Cloud

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

  1. Sign in to your Grafana Cloud instance.

  2. On the Home page, click Apps > Application Observability.

  3. Click All apps to open the App management page.

  4. Click Create new.

  5. 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: Enter the domains from which you are sending data.

      Grafana Faro Web SDK supports wildcard domains, for example, *.grafana.com.

    • 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.

  6. Click Create.

    A wizard appears that guides you through how to integrate Grafana Faro Web SDK into your codebase and start sending signals.

Add the Grafana Faro Web SDK package to your application

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

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

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

    # 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:

    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
      },
    });
    

To determine that Grafana Faro Web SDK works properly, you should see fetch requests in the Network tab of your browser’s developer tools.

Add the tracing package to your application

Because the OpenTelemetry packages are large, they are not included in the core or web packages of the Grafana Faro Web SDK. You must manually install the tracing package.

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

    # Using npm
    npm install @grafana/faro-web-tracing
    
    # Using yarn
    yarn add @grafana/faro-web-tracing
    
    # Using pnpm
    pnpm add @grafana/faro-web-tracing
    
  2. Modify the initialization code snippet from above to include the tracing package in the instrumentations array.

    import { TracingInstrumentation } from "@grafana/faro-web-tracing";
    import {
      getWebInstrumentations,
      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
      },
    
      instrumentations: [
        // Mandatory, overwriting the instrumentations array would cause the default instrumentations to be omitted
        ...getWebInstrumentations(),
    
        // Mandatory, initialization of the tracing package
        new TracingInstrumentation(),
      ],
    });
    

To determine that tracing works properly, you should see fetch requests that contain tracing data in the Network tab of your browser’s developer tools.