# @grafana/faro-core 中文文档

规范地址：https://npmcn.com/package/%40grafana/faro-core/

版本：2\.14\.0
npm 元数据更新时间：2026-11-09T16:05:00.132Z
中文译文更新时间：2026-11-16T21:41:49.380Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40grafana/faro-core
原文对照：https://npmcn.com/package/%40grafana/faro-core/?lang=original
项目主页：https://github.com/grafana/faro-web-sdk
源码仓库：https://github.com/grafana/faro-web-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：708 kB，439 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2022-10-31T12:07:36.954Z
- 最新版本发布：2026-11-09T16:04:59.807Z
- 近 30 天下载量：6570637（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：102（近 12 个月 26 个）

## 中文简介

法罗核心包.

## 安装

```sh
npm install @grafana/faro-core
```

也可以使用：`pnpm add @grafana/faro-core`、`yarn add @grafana/faro-core`、`bun add @grafana/faro-core`

## README

# @ grafana/ faro- core (英语)

_3⁄4 ̄ ̧漯B_:目前为发售前,并会经常被中断更改. 自己冒险使用.

法罗核心包.

图书馆的整个架构都包含在这个包中. 盒子里没有信号, 但它提供了API来完成它,以及多种帮助方法.

## 安装

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

initializeFaro({
  // ...
});
```

## 选项

Faro Web SDK 需要一个配置对象参数,其属性如下:

| 财产 | 说明 | 类型 | 默认值变量 |
| --- | --- | --- | --- |
| `app` | 应用程序元数据 | `App` |  |
| `dedupe` | 拖动分解过滤器的旗 | `boolean` |  |
| `globalObjectKey` | 用于定义全局对象上法罗实例属性的字符串 | `string` | `defaultGlobalObjectKey = 'faro'` |
| `instrumentations` | 应运行的仪器组合 | `Instrumentation[]` |  |
| `internalLoggerLevel` | 打印到控制台的内部信息级别 | `InternalLoggerLevel` | `defaultInternalLoggerLevel = InternalLoggerLevel.ERROR` |
| `isolate` | 将创建孤立的法罗实例的旗帜 | `boolean` |  |
| `metas` | 应记录的 meta 阵列 | `MetaItem[]` |  |
| `parseStacktrace` | 用于分析堆栈痕迹的函数 | `StacktraceParser` |  |
| `paused` | 将 Faro 实例初始化为已暂停的旗帜 | `boolean` |  |
| `preventGlobalExposure` | 全局对象上定义的标签 | `boolean` |  |
| `transports` | 应使用的运输阵列 | `Transport[]` |  |
| `batching.enabled` | 启用批量发送事件 | `boolean` | `true` |
| `batching.sendTimeout` | 发送事件批次的间隔 | `number` | 250号 |
| `batching.itemLimit` | 批发前信号缓冲器的大小( 覆盖间隔) | `number` | 第50条 |

除了强制属性外,法罗配置还支持以下可选属性:

| 财产 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `beforeSend` | Hook在把事件推向运输之前援引了 可用于修改或过滤事件 | `BeforeSendHook` | `undefined` |
| `eventDomain` | 事件域属性, 将设定为默认的每个事件项 | `string` | `undefined` |
| `ignoreErrors` | 应忽略的错误消息模式 | `Patterns` | `[]` |
| `ignoreUrls` | 跟踪应忽略的 Endpoint 路径模式 . | `Patterns` | `[]` |
| `logArgsSerializer` | 用于串行日志参数的函数 | `LogArgsSerializer` | `undefined` |
| `session` | 会话元数据 | `Session` | `undefined` |
| `user` | 用户元数据 | `User` | `undefined` |
| `view` | 查看元数据 | `View` | `undefined` |

## 法罗实例

Faro 实例是可以通过从软件包导入或从软件包中引用可以访问的对象 全局对象`window` 浏览器和 `global` 在节点.js.

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

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

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

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

## API 密码

这个 `api` 包含推动新事件的所有必要方法.

## 错误

-   `pushError` - 将错误/例外推向法罗实例的方法。 它接受强制性的 `error` 参数 和可选的,可以设置:
    
    -   `skipDedupe` - 即使错误与前一个错误相同,执行错误推动的旗帜.
    -   `stackFrames` - 一堆堆栈框 分析的默认值 `error.stack` 如果现在.
    -   `type` - 特例类型 默认值 : `error.name` 或者说 `"error"`。 。 。 .
    -   `context` - 例外附加的额外上下文的密钥值对象.
    -   `fingerprint` - 用于错误汇总的自定义分组指纹.
    -   `fatal` - 标记例外为致命的布尔旗帜(如坠机/ANR)。 参与破解如此致命 与原本相同的有效载荷有关的非致命错误作为单独事件报告.
    -   `spanContext` - 说吧 `{ traceId, spanId }` 将例外附加在明确的微量/平面上。 默认 当前活动跟踪上下文.
    -   `timestampOverwriteMs` - 推翻例外时间戳(自时代起为毫秒)。 默认现在.
    -   `originalError` - 内部预先使用选项;大多数用户不应设置.
    
    ```ts
    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 });
    ```
    

## 活动

-   `pushEvent` - 是将事件推向法罗事件的方法 它接受强制性的 `name` 参数和夫妇 可选参数.
    
    第一个可选参数叫做 `attributes` 它是一个键值对象,您可以在其中设置额外的 属性.
    
    第二个可选参数叫做 `domain` 它是用来组合事件的一个字符串.
    
    第三个可选参数是可选参数 `options` 设置对象 :
    
    -   `skipDedupe` - 执行事件推力的旗帜,即使事件与前一次相同.
    
    ```ts
    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 });
    ```
    

## 日志

-   `pushLog` - 是记录事件的方法。 该方法接受强制性 `args` 参数是 将字符串并发送到传输器和您可以设置的可选参数:
    
    -   `skipDedupe` - 执行日志推的旗帜,即使日志与上一个相同.
    -   `logLevel` - 我们登记的信息类型.
    -   `context` - 包含原始值的平面对象,随信件一起记录.
    
    ```ts
    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(),
      },
    });
    ```
    

## 计量

-   `pushMeasurement` - 登记指标的方法。 该方法接受强制性 `payload` 参数和一个 通过额外选项的可选参数 :
    
    -   `skipDedupe` - 执行测量推力的旗帜,即使测量与前一次相同.
    
    ```ts
    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' } }
    );
    ```
    

## 追踪

-   `pushTraces` - 一种通过运输工具手动发送痕迹的方法。 该方法只接受强制 `payload`。 。 。 .
    
    ```ts
    faro.api.pushTraces({
      resourceSpans: [/* OTel Traces */],
    });
    ```
    
-   `getOTEL` - 是法罗使用OpenTeleometry实例的一种方法.
    
    ```ts
    const otel = faro.api.getOTEL();
    ```
    
-   `isOTELInitialized` - 是检查OpenTeleometter软件包是否正确初始化和是否有一种 由法罗使用的 OpenTeleometry 实例.
    
    ```ts
    const isInitialized = faro.api.isOTELInitialized();
    ```
    

## 仪器

仪器是利用法罗Web SDK API提供自动数据收集机制的软件包. 它们只是代理初始化时执行的简单函数.

请注意: `core` 包件不包含框外的任何仪器,应当由 平台特定软件包 [@grafana/faro-web-sdk (英语)](https://github.com/grafana/faro-web-sdk/tree/main/packages/web-sdk)。 。 。 .

您也可以写自己的乐器:

```ts
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是每个由API所触发的事件都会附加的对象.

在框外,只提供了一种元: `sdk` 包含关于法罗实例及其版本的信息.

平台软件包可以提供额外的 metas [@grafana/faro-web-sdk (英语)](https://github.com/grafana/faro-web-sdk/tree/main/packages/web-sdk)。 。 。 .

您也可以定义自己的 metas :

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

## 运输

运算是API所触发的每起事件都需要的函数. 他们用来做一些事情 与收集后的数据.

箱外,没有提供运输工具 `core` 软件包,应由特定平台提供 软件包类似 [@grafana/faro-web-sdk (英语)](https://github.com/grafana/faro-web-sdk/tree/main/packages/web-sdk)。 。 。 .

您也可以定义自己的运输工具 :

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

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

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

运输也支持批发加工 `batchEnabled` 旗帜设置为正 和一个正,非零 `batchSendTimeout`。批次执行器将分组共享的项目 `metas` 一起行动 并召唤 `send` 每个信号组的函数.

### 挂载运输

目前运输接口支持执行 `send` 函数接受 a `TransportItem` 或数组它们。 当您想要用您的自定义运输批量处理信号时, 后者是有用的 。 顺序 要做到这一点,你应该 覆盖 `isBatched` (b) 基地运输方法.

```ts
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;
  }
}
```

## 空出控制台

某些仪器可能取代默认控制台方法,但法罗实例提供了一种访问方式 未修改的控制台方法 .

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

## 暂停/ 不暂停

Faro 实例可以通过引用 `faro.pause()`这将防止事件被送往运输站。 打电话 `faro.unpause()` 恢复捕捉事件.

## 孤立的法罗实例

有时您可能想要创建一个或多个孤立的法罗实例 。 例如:

-   您想要将 Faro 捆绑在一个可重复使用的库中, 并且仅报告某些事件, 而项目中 库有自己的法罗实例
-   您想要在一个系统中记录某些事件,而在其他系统中记录其他事件
-   可以创建多个 Faro 实例而不刷新页面的 E2E 库

为了实现这一点,你可以使用 `isolate` 初始化代理机时的旗帜 :

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

虽然一个孤立的代理人听起来可能是一个伟大的想法,但有一些限制适用于他们:

-   一些仪器仍将在全球注册(即例外仪器或控制台仪器)
-   无法在全球对象上找到孤立的 Faro 实例
-   法罗参考文献应该由项目存储,因为它无法通过 `import { faro } from '@grafana/faro-core';`

## 常见问题

### @grafana/faro-core 是什么？

法罗核心包\.

### 如何安装 @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 和提交记录判断。

