@ grafana/ faro- core (英语)
3⁄4 ̄ ̧漯B:目前为发售前,并会经常被中断更改. 自己冒险使用.
法罗核心包.
图书馆的整个架构都包含在这个包中. 盒子里没有信号, 但它提供了API来完成它,以及多种帮助方法.
安装
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.
// 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';