@cmall/sentry-utils v1.1.5

Sentry Utils

提供 cmall 常用的上报过滤器，和更便捷的 cdn 加载方式

Features

cdn 加载

<script src="https://cmall-static-resource.s3.us-west-2.amazonaws.com/libs/sentry-utils/1.1.1/sentry-util.umd.js"></script>
<script>
  if (window.SentryUtil) {
    window.SentryUtil.loadScript({
      dsn: "请输入您的项目dsn字符串",
      release: {
        package: "请输入release的包名称",
        version: "请输入release的版本",
      },
    });
  }
</script>

beforeSend 中间件

适用于npm包的使用方式。

import Sentry from "@sentry/browser";
import { createPipeline, middlewares } from "@cmall/sentry-utils";

Sentry.init({
  // ..
  beforeSend(event, hints) {
    // 按中间件顺序执行beforeSend
    return createPipeline().use(middlewares.jqAjax).run(event, hints);
  },
});

CONSTANTS

EVENT_TYPE

已知的自定义异常类型，用于tags.eventType

BURIED_POINT_ERROR_PHASE

自埋点错误阶段, 当tags.eventType等于EVENT_TYPE.BURIED_POINT_MUSTACHE有效，取与tags.phase

DEFAULT_IGNORE_ERROS

默认的ignoreErros设置

DEFAULT_BLACKLIST_URLS

默认的blackListUrls设置

DEFAULT_MIDDLESARES

默认使用的中间件列表

API

loadScript(option)

以默认配置加载 cdn 并初始化 sdk

参数

• option.dsn {string}

必填，sentry 项目的 dsn 字符串, 见文档：https://docs.sentry.io/platforms/javascript/configuration/options/#dsn

• option.release {object}

  必填，初始化到指定的 release，初始化成功后网页捕获的异常都或上报到此 release

  • release.package {string} 包名称

  • release.version {string} 包版本

  最终会通过{release.package}@{release.version}组成字符串传递给 sdk 配置的 release 项，见文档：https://docs.sentry.io/platforms/javascript/configuration/options/#release

• option.beforeSend {function}

  选填，相当于一个sentry.init的beforeSend函数或者一个中间件（等价的）， 在原有默认使用的中间件之后追加自定义的beforeSend操作。

createPipeline()

创建一个 pipeline 对象

pipeline.use(...middlewares)

向 pipeline 中注册一个或多个中间件

参数

• middleware {function}

  必填，相当于一个 beforeSend 函数，返回 null 或者 event， 参考文档：https://docs.sentry.io/platforms/javascript/configuration/options/#before-send(https://docs.sentry.io/platforms/javascript/configuration/options/#before-send

  中间件支持 async 异步， 返回 Promise<null | event>, 但是中间件的运行仍然是同步的

e.g.

const middleware1 = (e, h) => e;
const middleware2 = (e, h) => e;
const middleware3 = (e, h) => e;

const pipeline = createPipeline();
// 逐个注册
pipeline.use(middleware1).use(middleware2).use(middleware3);
// 或者批量注册
pipeline.use(middleware1, middleware2, middleware3);

pipeline.run(event, hints)

运行 pipeline， 会根据运行前注册的中间件逐个运行， 直至运行完毕或者中途返回 null

参数

• event {object}

  上报事件对象，从 beforeSend 中获得，参考文档：https://docs.sentry.io/platforms/javascript/configuration/options/#before-send

参数

• hints {object}

  额外的数据，从 beforeSend 中获得，参考文档：https://docs.sentry.io/platforms/javascript/configuration/filtering/#using-hints

e.g.

Sentry.init({
  // ..
  beforeSend(event, hint) {
    const middleware1 = (e, h) => e;
    const middleware2 = (e, h) => e;
    const middleware3 = (e, h) => e;
    const pipeline = createPipeline().use(middleware1, middleware2, middleware3).run(event, hint);
  },
});

pipeline.asMiddleware()

将自身pipeline变成一个中间件， 用于嵌套在其他pipeline里面, 编写自定义中间件时非常有用。

e.g.

const child = createPipeline().use(/** any middlewares */)
const mainPipeline = createPipeline().use(child.asMiddeware())

中间件

jqAjax()

针对 mvc 项目的中间件，捕获 UnhandledRejection 类型事件，判断是否符合 mvc 项目中的 jquery 发起的 ajax 请求异常，如果符合则拦截上报（mvc 项目中已经统一手动上报 jqAjax 异常，所以无需额外上报一个 UnhandledRejection 事件）

environment(option)

根据event.environment过滤

使用上面的cdn方式加载的话，会默认给event设定了environment值是pc或者mobile

参数

• option

  可选参数

• option.blackList {Array}

  可选，黑名单列表，environment值如果在列表范围里面则过滤上报。

• option.whiteList {Array}

  可选，白名单列表，environment值不在列表范围内的都过滤上报。

e.g.

import {createPipeline, middlewares} from '@cmall/sentry-utils'; 
// ..
Sentry.init({
  // ..
  beforeSend(event, hint) {
    return createPipeline().use(middlewares.environment({
      blackList: ['pc'], // 过滤pc环境异常上报
    }))
  }
})

instagram()

过滤基于instagram的webview上报的异常

thirdPartBuriedPoint(option?)

过滤第三方埋点上报的异常

参数

• option 可选

• option.url 可选，默认true

是否过滤第三方外部url加载的js上报的异常

• option.native 可选， 默认true

是否过滤第三方埋点的填入的代码上报的异常