@grafana/faro-core

中文文档
2.14.0发布于 2026/11/10Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 657.1万

Core package of Faro.

原始使用文档
文档目录16 节
  1. Installation
  2. Options
  3. Faro instance
  4. API
  5. Errors
  6. Events
  7. Logs
  8. Measurements
  9. Traces
  10. Instrumentations
  11. Metas
  12. Transports
  13. Batched transports
  14. Unpatched console
  15. Pause / unpause
  16. Isolated Faro instances

@grafana/faro-core

Warning: currently pre-release and subject to frequent breaking changes. Use at your own risk.

Core package of Faro.

The entire architecture of the library is contained within this package. Out of the box, it doesn't collect any signals, but it provides the API to do it as well as multiple helper methods.

Installation

import { initializeFaro } from '@grafana/faro-core';

initializeFaro({
  // ...
});

Options

Faro Web SDK requires a configuration object parameter with the following properties:

PropertyDescriptionTypeDefault Value Variable
appApplication metadataApp
dedupeA flag for toggling deduplication filterboolean
globalObjectKeyString that should be used when defining the Faro instance property on the global objectstringdefaultGlobalObjectKey = 'faro'
instrumentationsArray of instrumentations that should be ranInstrumentation[]
internalLoggerLevelThe level of information printed to console for internal messagesInternalLoggerLeveldefaultInternalLoggerLevel = InternalLoggerLevel.ERROR
isolateA flag that will create an isolated Faro instanceboolean
metasArray of metas that should be loggedMetaItem[]
parseStacktraceA function used to parse stack tracesStacktraceParser
pausedFlag for initializing the Faro instance as pausedboolean
preventGlobalExposureFlag for toggling the definition on the global objectboolean
transportsArray of transports that should be usedTransport[]
batching.enabledEnable batch sending of eventsbooleantrue
batching.sendTimeoutThe interval in which to send event batchesnumber250
batching.itemLimitThe size of the signal buffer before the batch is sent (overrides interval)number50

Besides the mandatory properties, Faro configuration also supports the following optional properties:

PropertyDescriptionTypeDefault Value
beforeSendHook invoked before pushing event to transport. Can be used to modify or filter eventsBeforeSendHookundefined
eventDomainevent.domain attribute of an event, to be set on every event item as defaultstringundefined
ignoreErrorsError message patterns for errors that should be ignoredPatterns[]
ignoreUrlsPath patterns for Endpoints that should be ignored form being tracked.Patterns[]
logArgsSerializerA function used to serialize log argumentsLogArgsSerializerundefined
sessionSession metadataSessionundefined
userUser metadataUserundefined
viewView metadataViewundefined

Faro instance

Faro instance is an object which can be accessed by either importing it from the package or by referencing it from the global object (window in browsers and global in Node.js).

// Browser/Node.js
import { faro } from '@grafana/faro-core';

faro.api.pushLog(/* ... */);

// Browser
window.faro.api.pushLog(/* ... */);

// Node.js
global.faro.api.pushLog(/* ... */);

API

The api property on the Faro instance contains all the necessary methods to push new events.

Errors

  • pushError - is a method to push an error/exception to the Faro instance. It accepts a mandatory error parameter and an optional one where you can set:

    • skipDedupe - a flag for enforcing error push even if the error is identical to the previous one.
    • stackFrames - an array of stack frames. Defaults to parsing error.stack if present.
    • type - the type of exception. Default value: error.name or "error".
    • context - a key-value object of additional context attached to the exception.
    • fingerprint - a custom grouping fingerprint used for error aggregation.
    • fatal - boolean flag marking the exception as fatal (e.g. crash / ANR). Participates in dedupe so a fatal and non-fatal error with otherwise identical payload are reported as separate events.
    • spanContext - { traceId, spanId } to attach the exception to an explicit trace/span. Defaults to the currently active trace context.
    • timestampOverwriteMs - override the exception timestamp (milliseconds since epoch). Defaults to now.
    • originalError - internal option for advanced use cases; most users should not set this.
    faro.api.pushError(new Error('This is an error'));
    
    faro.api.pushError(new Error('This is an unhandled exception'), { skipDedupe: true });
    
    faro.api.pushError(new Error('This is an unhandled exception'), { type: 'unhandledException' });
    
    faro.api.pushError(new Error('This is an error with stack frames'), {
      stackFrames: [
        {
          filename: 'file.js',
          function: 'myFunction',
          colno: 120,
          lineno: 80,
        },
      ],
    });
    
    faro.api.pushError(new Error('This is a log with context'), {
      context: {
        message: 'React error boundary',
        componentStackTrace: {...}
      },
    });
    
    faro.api.pushError(new Error('Custom grouping'), { fingerprint: 'login-network-failure' });
    
    faro.api.pushError(new Error('App crashed'), { fatal: true });
    

Events

  • pushEvent - is a method to push an event to the Faro instance. It accepts a mandatory name parameter and a couple of optional parameters.

    The first optional parameter is called attributes and it is a key-value object where you can set additional properties for your event.

    The second optional parameter is called domain and it is a string that's used to group events together.

    The third optional parameter is an optional options object where you can set:

    • skipDedupe - a flag for enforcing event push even if the event is identical to the previous one.
    faro.api.pushEvent('user-logged-in');
    
    faro.api.pushEvent('user-logged-in', { username: 'the-user-id' });
    
    faro.api.pushEvent('user-logged-in', { username: 'the-user-id' }, 'auth');
    
    faro.api.pushEvent('user-logged-in', { username: 'the-user-id' }, 'auth', { skipDedupe: true });
    

Logs

  • pushLog - is a method to register a log event. The method accepts a mandatory args parameter which is an array of arguments that will be stringified and sent to the transports and an optional one where you can set:

    • skipDedupe - a flag for enforcing log push even if the log is identical to the previous one.
    • logLevel - the type of message that we register.
    • context - a plain object containing primitive values that will be recorded along with the message.
    faro.api.pushLog(['This is a log', 'With another message']);
    
    faro.api.pushLog(['This is a log'], { skipDedupe: true });
    
    faro.api.pushLog(['This is a warning'], { level: LogLevel.WARN });
    
    faro.api.pushLog(['This is a log with context'], {
      context: {
        randomNumber: Math.random(),
      },
    });
    

Measurements

  • pushMeasurement - is a method for registering metrics. The method accepts a mandatory payload parameter and an optional parameter for passing additional options:

    • skipDedupe - a flag for enforcing measurement push even if the measurement is identical to the previous one.
    faro.api.pushMeasurement({
      type: 'custom',
      values: {
        my_custom_metric: Math.random(),
      },
    });
    
    faro.api.pushMeasurement(
      {
        type: 'custom',
        values: {
          my_custom_metric: Math.random(),
        },
      },
      { skipDedupe: true }
    );
    
    faro.api.pushMeasurement(
      {
        type: 'custom',
        values: {
          my_custom_metric: Math.random(),
        },
      },
      { context: { hello: 'world' } }
    );
    

Traces

  • pushTraces - is a method for manually sending traces through the transports. The method only accepts a mandatory payload.

    faro.api.pushTraces({
      resourceSpans: [/* OTel Traces */],
    });
    
  • getOTEL - is a method for getting the OpenTelemetry instance used by Faro.

    const otel = faro.api.getOTEL();
    
  • isOTELInitialized - is a method for checking if OpenTelemetry package was correctly initialized and there is an OpenTelemetry instance used by Faro.

    const isInitialized = faro.api.isOTELInitialized();
    

Instrumentations

Instrumentations are packages that leverage the Faro Web SDK API to provide automatic mechanisms for collecting data. They are just simple functions that are executed when the agent is initialized.

Please note that the core package does not contain any instrumentations out of the box and they should be provided by platform specific packages like @grafana/faro-web-sdk.

You can also write your own instrumentations:

import { initializeFaro, BaseInstrumentation } from '@grafana/faro-core';

export class MyInstrumentation extends BaseInstrumentation {
  readonly version = '1.0.0';
  readonly name = 'my-instrumentation';

  initialize(): void {
    this.faro.api.pushLog(['hello from my instrumentation']);
  }
}

initializeFaro({
  // ...
  instrumentations: [new MyInstrumentation()],
});

Metas

Metas are objects that will be attached to every event that is triggered by the API.

Out of the box, only one meta is provided: sdk which contains information about the Faro instance and its version.

Additional metas may be provided by platform packages like @grafana/faro-web-sdk.

You can also define your own metas:

import { initializeFaro } from '@grafana/faro-core';

initializeFaro({
  metas: [
    // Define a static meta
    {
      app: {
        name: 'my-app',
        version: '1.0.0',
      },
    },

    // Define a meta which caches some values on initialization
    () => {
      return {
        user: {
          username: getUser().name,
        },
      };
    },
  ],
});

Transports

Transports are functions that will be called for every event that is triggered by the API. They are used to do something with the data after collecting it.

Out of the box, no transports are provided in the core package and they should be provided by platform specific packages like @grafana/faro-web-sdk.

You can also define your own transports:

import { initializeFaro, BaseTransport, TransportItem } from '@grafana/faro-core';

class MyTransport extends BaseTransport {
  send(item: TransportItem) {
    // do something with paylaod
  }
}

initializeFaro({
  transports: [new MyTransport()],
});

The transports also support batch processing wiht the batchEnabled flag set to true and a positive, non zero batchSendTimeout. The batch executor will group items that share the same metas together and call the send function for each group of signals.

Batched transports

Currently the Transport interface supports implementations of the send function that accept either a TransportItem or an array of them. The latter is useful when you want to batch process signals with your custom transport. In order to achieve this, you should override the isBatched method of the BaseTransport.

export class MyTransport extends BaseTransport {
  async send(item: TransportItem): Promise<void> {
    // do something with the item
  }
}

/* should be */

export class MyBatchedTransport extends BaseTransport {
  async send(items: TransportItem[]): Promise<void> {
    // do something with the array of items
    // all of them share the same metas
  }

  // This is required for the transports layer to differentiate
  // between the two types of Transport implementations
  override isBatched(): boolean {
    return true;
  }
}

Unpatched console

Some instrumentations might override the default console methods but Faro instance provides a way to access the unmodified console methods.

faro.unpatchedConsole.log('This is a log');
faro.unpatchedConsole.warn('This is a warning');

Pause / unpause

Faro instance can be paused by invoking faro.pause(). This will prevent events from being sent to transports. Call faro.unpause() to resume capturing events.

Isolated Faro instances

Sometimes you may want to create one or more isolated Faro instances. For example:

  • you want to bundle Faro in a reusable library and report certain events only for it while the project where the library is used has its own Faro instance
  • you want to log certain events in one system while other events in other systems
  • E2E libraries that may create multiple Faro instances without refreshing the page

In order to achieve this, you can use the isolate flag when initializing the agent:

// faro 1 will be isolated
const faro1 = initializeFaro({
  // ...
  isolate: true,
});

// globalFaro will be available globally
const globalFaro = initializeFaro({
  // ...
  isolate: false,
});

// another isolated Faro instance
const faro2 = initializeFaro({
  // ...
  isolate: true,
});

Although an isolated agent may sound like a great idea, there are some limitations which apply to them:

  • some instrumentations will still register globally (i.e. exceptions instrumentation or console instrumentation)
  • an isolated Faro instance will not be available on the global object
  • the Faro reference should be stored by the project as it won't be available via import { faro } from '@grafana/faro-core';

版本与发布记录

@grafana/faro-core 共发布 102 个版本,首次发布于 2022/10/31;过去 12 个月发布了 26 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.14.0latest2026/11/107 天前
2.13.02026/10/2225 天前
2.12.12026/09/221 个月前
2.12.02026/09/181 个月前
2.11.02026/08/272 个月前
2.10.02026/08/182 个月前

关于 @grafana/faro-core 的常见问题

@grafana/faro-core 是什么?

Core package of Faro.

如何安装 @grafana/faro-core?

在项目目录运行 npm install @grafana/faro-core,或使用 pnpm add / yarn add / bun add。

@grafana/faro-core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grafana/faro-core 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@grafana/faro-core 可以商用吗?

@grafana/faro-core 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/faro-core 的下载量有多少?

根据 npm 官方下载统计,@grafana/faro-core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,570,637 次,日均约 219,021 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/faro-core 还在维护吗?

最新版本 2.14.0 发布于 2026/11/10(7 天前);至今共发布 102 个版本,其中过去 12 个月发布了 26 个;首次发布于 2022/10/31。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。