@grafana/faro-core

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

法罗核心包.

中文使用文档
文档目录16 节
  1. 安装
  2. 选项
  3. 法罗实例
  4. API 密码
  5. 错误
  6. 活动
  7. 日志
  8. 计量
  9. 追踪
  10. 仪器
  11. 元数据
  12. 运输
  13. 挂载运输
  14. 空出控制台
  15. 暂停/ 不暂停
  16. 孤立的法罗实例

@ grafana/ faro- core (英语)

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

法罗核心包.

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

安装

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

initializeFaro({
  // ...
});

选项

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

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

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

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

法罗实例

Faro 实例是可以通过从软件包导入或从软件包中引用可以访问的对象 全局对象window 浏览器和 global 在节点.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 密码

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

错误

  • pushError - 将错误/例外推向法罗实例的方法。 它接受强制性的 error 参数 和可选的,可以设置:

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

    faro.api.pushTraces({
      resourceSpans: [/* OTel Traces */],
    });
    
  • getOTEL - 是法罗使用OpenTeleometry实例的一种方法.

    const otel = faro.api.getOTEL();
    
  • isOTELInitialized - 是检查OpenTeleometter软件包是否正确初始化和是否有一种 由法罗使用的 OpenTeleometry 实例.

    const isInitialized = faro.api.isOTELInitialized();
    

仪器

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

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

您也可以写自己的乐器:

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 (英语)。 。 。 .

您也可以定义自己的 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,
        },
      };
    },
  ],
});

运输

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

箱外,没有提供运输工具 core 软件包,应由特定平台提供 软件包类似 @grafana/faro-web-sdk (英语)。 。 。 .

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

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) 基地运输方法.

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

空出控制台

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

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

暂停/ 不暂停

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

孤立的法罗实例

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

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

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

// 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 共发布 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 是什么?

法罗核心包.

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