Documentation Grafana Cloud Monitor applications Frontend Observability Architecture Metas

Provided metas

Metas are additional data that accompany the errors or events that an instrumentation collects. Metas are useful because they provide additional context and enable you to filter the data and extract it only for a particular user, session, or browser.

For example, when you need to associate the collected data with your application, you provide the application name as a meta and, optionally, the application version and the environment where it runs.

App

The app meta is mandatory and associates the collected data with your application.

The app meta contains three fields that you can set:

• name (required): The name of your application
• namespace - a namespace for app.name
• version (optional): The application version, for example, 1.0.0
• release - a release identifier for the app, like a commit hash, a build number or a Docker container tag
• environment (optional): The environment where your application is running, for example production

The version and environment fields are optional, but we recommend using them because:

• They provide another set of labels that you can use to filter data
• They help you determine when an error was introduced, for example, version 1.0.1 produces the error but version 1.0.0 doesn’t
• You can check error rates between application versions and environments
• You can identify problematic containers, for example, the application served from container X takes more time to serve a page

How to use the app meta

In order to set the following app meta, you must provide at least the name field when you initialize the Grafana Faro Web SDK.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    // You must provide at least the name field!
    name: 'my-app',

    // Optional, if you want to specify an app version
    version: '1.0.0',

    // Optional, if you want to specify the environment where the app is running
    environment: 'production',
  },
});

Session

The session meta is an optional meta that associates the collected data with the current session. A session is defined by a single access of a web page, and it is persisted across the entire page lifetime or longer depending on the session manager mode you select.

You don’t need to manually set the session during initialization because it is automatically set by the Grafana Faro Web SDK. However, you can manually set it if you want to control the session ID. For example, manually set the session when you want to set a custom session ID or want to access the session ID for other purposes.

For a comprehensive understanding of session tracking mechanics and guidance on its configuration, refer to Session tracking.

How to use the session meta

The following session meta is enabled by default. No additional configuration is required.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
});

If you receive your session ID from an external system or you want to create a session ID manually, you can define the session ID via the generateSessionId() function.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  sessionTracking?: {
    generateSessionId() {
      return `my-custom-id-${Math.random()}`
    },
    session: {
      attributes: {
        'my-custom-attribute': 'my-custom-attribute-value',
      },
    },
  };
});

If you want to manually update the session meta dynamically after Faro Web SDK was initialized, you can use the setSession function. The payload can be either a session object created using the createSession helper function or a session object described above.

ts Copy

faro.api.setSession(createSession());

User

The user meta is an optional meta that links the collected data with the current user. This is useful when you want to connect events to the user who performed them. In conjunction with the session meta, events that occurred prior to the user’s login can be associated with the user once they log in.

Although optional, the user meta is useful in the following use cases:

• The application you are instrumenting has an authentication system
• You want to associate the collected data with the user who performed the operations
• You are not concerned about GDPR regulations

How to use the user meta

The easiest way to set the user meta is to define it when you initialize the Grafana Faro Web SDK.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  user: {
    // Optional, if you want to pass the user ID
    id: '744072d1-5dc6-4442-aabb-0c2f6f28e81c',

    // Optional, if you want to pass the user email
    email: 'my-email@my-domain.my-tld',

    // Optional, if you want to pass the username
    username: 'my-user',

    // Optional, if you want to set custom attributes
    attributes: {
      'my-custom-attribute': 'my-custom-attribute-value',
    },
  },
});

There might be cases when the user details are not available upon initialization, (for example, the user is not yet logged in). In this case, you can use the following setUser function to set the user.

ts Copy

faro.api.setUser({
  // Optional, if you want to pass the user ID
  id: '744072d1-5dc6-4442-aabb-0c2f6f28e81c',

  // Optional, if you want to pass the user email
  email: 'my-email@my-domain.my-tld',

  // Optional, if you want to pass the username
  username: 'my-user',

  // Optional, if you want to set custom attributes
  attributes: {
    'my-custom-attribute': 'my-custom-attribute-value',
  },
});

View

The view meta is an optional meta that associates the collected data with a view. A view can be seen as a way to categorize events or logs under a certain section of your application instead of relying only on URLs. For example, the register and login pages of your application can be in an “auth” view while the homepage can be in a “home” view.

By default, Grafana Faro Web SDK creates a “default” view which you can either override during initialization or manually update afterwards.

How to use the view meta

The following view meta is enabled by default.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
});

However, you can set a view during initialization if you already know the view name. This is particularly useful for cases where users access your application using a page other than homepage.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  view: {
    name: 'auth',
  },
});

If you want to manually update the view meta dynamically after Faro Web SDK is initialized, you can use the setView function.

ts Copy

faro.api.setView({ name: 'auth' });

Browser

The browser meta is an optional meta that attaches information about the browser used to access the web page.

The following information is extracted from the browser’s user-agent:

• name: The name of the browser
• version: The browser version
• os: The operating system where the browser is running
• mobile: A boolean flag that indicates if the browser is running on a mobile device

The browser meta is enabled by default. We don’t recommend disabling it because:

• Browser statistics won’t be available
• Troubleshooting browser, version, or OS errors becomes more difficult.

How to use the browser meta

The following browser meta is automatically set by the Grafana Faro Web SDK during initialization. No additional configuration is required.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
});

To manually include the browser meta, use the following defaultMetas array.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  metas: [...defaultMetas],
});

Alternatively, if you want to fine-tune which instrumentations are enabled, you can use the browserMeta meta getter.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  metas: [browserMeta],
});

Page

The page meta is an optional but useful meta that attaches the URL of the current page to all collected data.

Because the page meta is useful and comes with zero overhead, it is enabled by default. We recommend that don’t disable the page meta.

How to use the page meta

The following page meta is automatically set by the Grafana Faro Web SDK during initialization. No additional configuration is required.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
});

To manually include the page meta, use the following defaultMetas array.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  metas: [...defaultMetas],
});

Alternatively, if you want to fine-tune which instrumentations are enabled, you can use the following pageMeta meta getter.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  metas: [pageMeta],
});

K6

The K6 meta is only added if Faro is running in a K6 environment. It derives the information from the existence of the K6 object in the browser window (window.k6).

Starting with K6 v0.50.0, the property testRunId is attached to the K6 object, which is the test run ID of the current K6 test and can be used to reference the respective K6 test. If available, Faro adds this property to the K6 meta as well.

How to use the K6 meta

The K6 meta is fully managed by Faro and is not meant to be altered outside of Faro.